Code review. Adds comments. Refactoring methods.

src/fr/devinsy/util/strings/StringList.java

@@ -1,5 +1,5 @@
 /**
- * Copyright (C) 2008-2010, 2013-2014 Christian Pierre MOMON
+ * Copyright (C) 2008-2010, 2013-2015 Christian Pierre MOMON
  * 
  * This file is part of Devinsy-utils.
  * 
@@ -21,8 +21,8 @@ package fr.devinsy.util.strings;
 import java.io.IOException;
 import java.text.Collator;
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.Collections;
-import java.util.List;
 
 /**
  * This class is a collection of String objects with specific methods. It makes
@@ -37,7 +37,8 @@ public class StringList extends ArrayList<String> implements CharSequence
 	public static final String LINE_SEPARATOR = "\n";
 
 	/**
-	 *
+	 * Constructs an empty list with an initial capacity of ten (see ArrayList
+	 * constructor).
 	 */
 	public StringList()
 	{
@@ -45,17 +46,12 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Constructs a list of string of the specified collection, in the order
+	 * they are returned by the collection's iterator.
 	 * 
+	 * @param source
 	 */
-	public StringList(final int initialCapacity)
+	public StringList(final Collection<String> source)
-	{
-		super(initialCapacity);
-	}
-
-	/**
-	 *
-	 */
-	public StringList(final List<String> source)
 	{
 		super();
 
@@ -73,7 +69,19 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Constructs an empty list with the specified initial capacity.
 	 * 
+	 * @param initialCapacity
+	 */
+	public StringList(final int initialCapacity)
+	{
+		super(initialCapacity);
+	}
+
+	/**
+	 * Constructs a list of string from a string array.
+	 * 
+	 * @param source
 	 */
 	public StringList(final String... source)
 	{
@@ -93,27 +101,11 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Appends the string representation of the char argument to this string
+	 * list.
 	 * 
-	 */
+	 * @param character
-	public StringList(final StringList source)
+	 * @return
-	{
-		super();
-
-		if (source != null)
-		{
-			//
-			ensureCapacity(source.size());
-
-			//
-			for (String string : source)
-			{
-				this.add(string);
-			}
-		}
-	}
-
-	/**
-	 * 
 	 */
 	public StringList append(final char character)
 	{
@@ -128,7 +120,36 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Appends the string of the specified collection, in the order they are
+	 * returned by the collection's iterator.
 	 * 
+	 * @param strings
+	 * @return
+	 */
+	public StringList append(final Collection<String> strings)
+	{
+		StringList result;
+
+		if (strings != null)
+		{
+			for (String string : strings)
+			{
+				this.append(string);
+			}
+		}
+
+		result = this;
+
+		//
+		return (result);
+	}
+
+	/**
+	 * Appends the string representation of the double argument to this string
+	 * list.
+	 * 
+	 * @param value
+	 * @return
 	 */
 	public StringList append(final double value)
 	{
@@ -141,7 +162,11 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Appends the string representation of the Double argument to this string
+	 * list.
 	 * 
+	 * @param value
+	 * @return
 	 */
 	public StringList append(final Double value)
 	{
@@ -159,7 +184,11 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Appends the string representation of the int argument to this string
+	 * list.
 	 * 
+	 * @param value
+	 * @return
 	 */
 	public StringList append(final int value)
 	{
@@ -172,28 +201,11 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Appends the string representation of the long argument to this string
+	 * list.
 	 * 
-	 */
+	 * @param value
-	public StringList append(final List<String> strings)
+	 * @return
-	{
-		StringList result;
-
-		if (strings != null)
-		{
-			for (String string : strings)
-			{
-				this.add(string);
-			}
-		}
-
-		result = this;
-
-		//
-		return (result);
-	}
-
-	/**
-	 * 
 	 */
 	public StringList append(final long value)
 	{
@@ -206,7 +218,12 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Appends the string argument to this string list.
+	 * 
 	 * Check null parameter before add.
+	 * 
+	 * @param string
+	 * @return
 	 */
 	public StringList append(final String string)
 	{
@@ -224,7 +241,10 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Appends the string of the array argument to this string list.
 	 * 
+	 * @param strings
+	 * @return
 	 */
 	public StringList append(final String... strings)
 	{
@@ -245,28 +265,9 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Appends a break line to this string list.
 	 * 
-	 */
+	 * @return
-	public StringList append(final StringList strings)
-	{
-		StringList result;
-
-		if (strings != null)
-		{
-			for (String string : strings)
-			{
-				this.add(string);
-			}
-		}
-
-		result = this;
-
-		//
-		return (result);
-	}
-
-	/**
-	 * 
 	 */
 	public StringList appendln()
 	{
@@ -281,7 +282,11 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Appends the string representation of the char argument to this string
+	 * list, then append a break line too.
 	 * 
+	 * @param character
+	 * @return
 	 */
 	public StringList appendln(final char character)
 	{
@@ -295,6 +300,23 @@ public class StringList extends ArrayList<String> implements CharSequence
 
 	/**
 	 * 
+	 * @param string
+	 * @return
+	 */
+	public StringList appendln(final Collection<String> string)
+	{
+		StringList result;
+
+		result = this.append(string).appendln();
+
+		//
+		return (result);
+	}
+
+	/**
+	 * 
+	 * @param value
+	 * @return
 	 */
 	public StringList appendln(final double value)
 	{
@@ -308,6 +330,8 @@ public class StringList extends ArrayList<String> implements CharSequence
 
 	/**
 	 * 
+	 * @param value
+	 * @return
 	 */
 	public StringList appendln(final int value)
 	{
@@ -321,19 +345,8 @@ public class StringList extends ArrayList<String> implements CharSequence
 
 	/**
 	 * 
-	 */
+	 * @param value
-	public StringList appendln(final List<String> string)
+	 * @return
-	{
-		StringList result;
-
-		result = this.append(string).appendln();
-
-		//
-		return (result);
-	}
-
-	/**
-	 * 
 	 */
 	public StringList appendln(final long value)
 	{
@@ -347,6 +360,8 @@ public class StringList extends ArrayList<String> implements CharSequence
 
 	/**
 	 * 
+	 * @param string
+	 * @return
 	 */
 	public StringList appendln(final String string)
 	{
@@ -360,6 +375,8 @@ public class StringList extends ArrayList<String> implements CharSequence
 
 	/**
 	 * 
+	 * @param strings
+	 * @return
 	 */
 	public StringList appendln(final String... strings)
 	{
@@ -371,19 +388,6 @@ public class StringList extends ArrayList<String> implements CharSequence
 		return (result);
 	}
 
-	/**
-	 * 
-	 */
-	public StringList appendln(final StringList string)
-	{
-		StringList result;
-
-		result = this.append(string).appendln();
-
-		//
-		return (result);
-	}
-
 	/**
 	 * 
 	 */
@@ -426,6 +430,8 @@ public class StringList extends ArrayList<String> implements CharSequence
 
 	/**
 	 * 
+	 * @param id
+	 * @return
 	 */
 	public String getByIndex(final int id)
 	{
@@ -439,6 +445,7 @@ public class StringList extends ArrayList<String> implements CharSequence
 
 	/**
 	 * 
+	 * @return
 	 */
 	public String getFirst()
 	{
@@ -459,6 +466,7 @@ public class StringList extends ArrayList<String> implements CharSequence
 
 	/**
 	 * 
+	 * @return
 	 */
 	public String getLast()
 	{
@@ -535,7 +543,11 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Merge all strings of the list into in single string. At the end of
+	 * operation, the new string is the first of the list and the size list is
+	 * 1.
 	 * 
+	 * @return
 	 */
 	public StringList merge()
 	{
@@ -546,13 +558,16 @@ public class StringList extends ArrayList<String> implements CharSequence
 		clear();
 		add(merge);
 
-		//
 		result = this;
+
+		//
 		return result;
 	}
 
 	/**
+	 * Removes the last element of the list.
 	 * 
+	 * @return This list.
 	 */
 	public StringList removeLast()
 	{
@@ -570,7 +585,12 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Extends the list copying the last element a number of time.
 	 * 
+	 * @param count
+	 *            The number of time to copy the last element.
+	 * 
+	 * @return This list.
 	 */
 	public StringList repeatLast(final int count)
 	{
@@ -600,8 +620,9 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Sorts this list.
 	 * 
-	 * @return
+	 * @return This List.
 	 */
 	public StringList sort()
 	{
@@ -617,7 +638,7 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
-	 * 
+	 * {@inheritDoc}
 	 */
 	@Override
 	public CharSequence subSequence(final int start, final int end)
@@ -631,10 +652,14 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Extracts a substring from this list.
 	 * 
 	 * @param start
+	 *            The first character of the substring.
 	 * @param end
-	 * @return
+	 *            The last character of the substring.
+	 * 
+	 * @return The sublist targeted.
 	 */
 	public StringList substring(final int beginIndex, final int endIndex)
 	{
@@ -694,15 +719,15 @@ public class StringList extends ArrayList<String> implements CharSequence
 					String target = source.substring(0, endPosition.getLocalCharIndex());
 					result.append(target);
 				}
-
 			}
 		}
+
 		//
 		return result;
 	}
 
 	/**
-	 * 
+	 * {@inheritDoc}
 	 */
 	@Override
 	public String toString()
@@ -733,6 +758,8 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Returns an array containing all of the strings in this list in proper
+	 * sequence (from first to last element).
 	 * 
 	 * @return
 	 */
@@ -752,7 +779,13 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Returns a string containing the concatenation of the strings of this
+	 * list. Between each string of this list, a separator argument string is
+	 * concatenated too.
 	 * 
+	 * @param separator
+	 * 
+	 * @return
 	 */
 	public String toStringSeparatedBy(final String separator)
 	{
@@ -779,6 +812,7 @@ public class StringList extends ArrayList<String> implements CharSequence
 
 	/**
 	 * 
+	 * @return
 	 */
 	public String toStringWithCommas()
 	{
@@ -792,6 +826,7 @@ public class StringList extends ArrayList<String> implements CharSequence
 
 	/**
 	 * 
+	 * @return
 	 */
 	public String toStringWithFrenchCommas()
 	{
@@ -804,7 +839,12 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Writes the strings of this list into a {@code PrintWriter}.
 	 * 
+	 * @param out
+	 *            The {@code PrintWriter} where to write.
+	 * 
+	 * @throws IOException
 	 */
 	public void writeInto(final java.io.PrintWriter out) throws IOException
 	{
@@ -815,7 +855,12 @@ public class StringList extends ArrayList<String> implements CharSequence
 	}
 
 	/**
+	 * Writes the strings of this list into a {@code Writer}.
 	 * 
+	 * @param out
+	 *            The {@code Writer} where to write.
+	 * 
+	 * @throws IOException
 	 */
 	public void writeInto(final java.io.Writer out) throws IOException
 	{
@@ -824,23 +869,4 @@ public class StringList extends ArrayList<String> implements CharSequence
 			out.write(string);
 		}
 	}
-
-	/**
-	 * 
-	 */
-	public static String multiply(final String source, final int number)
-	{
-		String result;
-
-		StringList strings = new StringList(number);
-		for (int index = 0; index < number; index++)
-		{
-			strings.append(source);
-		}
-
-		result = strings.toString();
-
-		//
-		return (result);
-	}
 }

src/fr/devinsy/util/strings/StringListCharPosition.java

@@ -1,5 +1,5 @@
 /**
- * Copyright (C) 2013-2014 Christian Pierre MOMON
+ * Copyright (C) 2013-2015 Christian Pierre MOMON
  * 
  * This file is part of Devinsy-utils.
  * 
@@ -29,6 +29,12 @@ public class StringListCharPosition
 	private int stringIndex;
 	private int localCharIndex;
 
+	/**
+	 * 
+	 * @param index
+	 * @param stringIndex
+	 * @param localIndex
+	 */
 	public StringListCharPosition(final int index, final int stringIndex, final int localIndex)
 	{
 		this.charIndex = index;

src/fr/devinsy/util/strings/StringListWriter.java

@@ -1,5 +1,5 @@
 /**
- * Copyright (C) 2013-2014 Christian Pierre MOMON
+ * Copyright (C) 2013-2015 Christian Pierre MOMON
  * 
  * This file is part of Devinsy-utils.
  * 

src/fr/devinsy/util/strings/StringSet.java

@@ -1,5 +1,5 @@
 /**
- * Copyright (C) 2015 Christian Pierre MOMON
+ * Copyright (C) 2014-2015 Christian Pierre MOMON
  * 
  * This file is part of Devinsy-utils.
  * 
@@ -416,12 +416,7 @@ public class StringSet extends HashSet<String>
 	{
 		StringList result;
 
-		result = new StringList(this.size());
+		result = new StringList(this);
-
-		for (String string : this)
-		{
-			result.append(string);
-		}
 
 		//
 		return result;