X-Git-Url: http://git.nikiroo.be/?a=blobdiff_plain;f=src%2Fbe%2Fnikiroo%2Fjvcard%2FContact.java;h=4b4446de67c7ab0b9d4fed2650024a7274913421;hb=f04a32e97c847d7e2551037a4d5f6a070879215c;hp=d75d3380326a8bfde6c245f959dd6ff916b1f07f;hpb=7671a2499e6f0d6c8e0765b36c18c1e89bc457c5;p=jvcard.git

diff --git a/src/be/nikiroo/jvcard/Contact.java b/src/be/nikiroo/jvcard/Contact.java
index d75d338..4b4446d 100644
--- a/src/be/nikiroo/jvcard/Contact.java
+++ b/src/be/nikiroo/jvcard/Contact.java
@@ -11,13 +11,17 @@ import java.util.UUID;
 
 import be.nikiroo.jvcard.parsers.Format;
 import be.nikiroo.jvcard.parsers.Parser;
-import be.nikiroo.jvcard.resources.StringUtils;
+import be.nikiroo.utils.StringUtils;
 
 /**
  * A contact is the information that represent a contact person or organisation.
+ * <p>
+ * Each {@link Data} inside can be binary encoded or not: if it is binary
+ * encoded, it has an active BKey number (not -1) associated to it (of value 0
+ * if still not sorted, or unique for the whole {@link Contact} if already
+ * processed).
  * 
  * @author niki
- * 
  */
 public class Contact extends BaseClass<Data> {
 	private int nextBKey = 1;
@@ -60,7 +64,8 @@ public class Contact extends BaseClass<Data> {
 
 	/**
 	 * Return the value of the preferred data field with this name, or NULL if
-	 * none (you cannot differentiate a NULL value and no value).
+	 * none (you cannot differentiate a NULL value and no value with this method
+	 * -- for that, check {@link Contact#getPreferredData(String)}).
 	 * 
 	 * @param name
 	 *            the name to look for
@@ -77,7 +82,7 @@ public class Contact extends BaseClass<Data> {
 	 * Get the Data fields that share the given name.
 	 * 
 	 * @param name
-	 *            the name to ook for
+	 *            the name to look for
 	 * @return a list of Data fields with this name
 	 */
 	public List<Data> getData(String name) {
@@ -131,7 +136,7 @@ public class Contact extends BaseClass<Data> {
 	 * @return the {@link String} representation
 	 */
 	public String toString(String format, String separator) {
-		return toString(format, separator, null, -1, true, false);
+		return toString(format, separator, null, -1, true);
 	}
 
 	/**
@@ -173,14 +178,13 @@ public class Contact extends BaseClass<Data> {
 	 *            the {@link String} to use for left and right padding
 	 * @param width
 	 *            a fixed width or -1 for "as long as needed"
-	 * 
 	 * @param unicode
-	 *            allow Uniode or only ASCII characters
+	 *            allow Unicode or only ASCII characters
 	 * 
 	 * @return the {@link String} representation
 	 */
 	public String toString(String format, String separator, String padding,
-			int width, boolean unicode, boolean removeAccents) {
+			int width, boolean unicode) {
 		StringBuilder builder = new StringBuilder();
 
 		for (String str : toStringArray(format, separator, padding, width,
@@ -305,7 +309,7 @@ public class Contact extends BaseClass<Data> {
 	 *            a fixed width or -1 for "as long as needed"
 	 * @param unicode
 	 *            allow Uniode or only ASCII characters
-	 *
+	 * 
 	 * @return the {@link String} representation
 	 */
 	public String[] toStringArray(String format, int width, boolean unicode) {
@@ -506,8 +510,8 @@ public class Contact extends BaseClass<Data> {
 	}
 
 	/**
-	 * Return a {@link String} representation of this contact, in vCard 2.1,
-	 * without BKeys.
+	 * Return a simple {@link String} representation of this contact without
+	 * BKeys.
 	 * 
 	 * @return the {@link String} representation
 	 */
@@ -588,12 +592,26 @@ public class Contact extends BaseClass<Data> {
 	/**
 	 * Add a {@link String} to the given {@link List}, but make sure it does not
 	 * exceed the maximum size, and truncate it if needed to fit.
+	 * <p>
+	 * Will always add one and only one {@link String} (potentially empty) at
+	 * the end of <tt>list</tt>.
 	 * 
 	 * @param list
+	 *            the list to add to
 	 * @param add
+	 *            the {@link String} to (either fully or partially) add
 	 * @param currentSize
+	 *            the current total size (managed outside of this method)
 	 * @param maxSize
-	 * @return
+	 *            the maximum size that cannot be exceeded (or -1 for
+	 *            "no maximum") -- if the maximum size would be exceeded by
+	 *            adding this {@link String}, only a part of it will be added;
+	 *            if the maximum size is already reached or exceeded (should not
+	 *            happen because of this method), an empty {@link String} will
+	 *            be added
+	 * 
+	 * @return the number of characters added (the size of the last
+	 *         {@link String} in <tt>list</tt>)
 	 */
 	static private int addToList(List<String> list, String add,
 			int currentSize, int maxSize) {