Improve StringUtils.copyToBuffer.

Changes the logic for resizing the buffer so that it first calculates
the new buffer size and then allocates the buffer instead of growing the
buffer in multiple steps during the calculation.

Additionally, the commit adds assertions to ensure the method is called
with valid parameters.

The Javadoc of `copyToBuffer` now describes the assertions and adds an
example showing how the method is intended to be used.

Finally, the commit adds two test cases for the method.

Author: cboehme

src/main/java/org/culturegraph/mf/util/StringUtil.java

@@ -19,9 +19,9 @@
 import java.util.Map;
 
 /**
- * Basic utils
+ * Some handy string utility methods
  *
- * @author Markus Michael Geipel
+ * @author Markus Michael Geipel, Christoph Böhme
  *
  */
 public final class StringUtil {
@@ -30,7 +30,7 @@ public final class StringUtil {
 	private static final String DEFAULT_VAREND = "}";
 
 	private StringUtil() {
-		// no instances
+		// no instances allowed
 	}
 
 	public static <O> O fallback(final O value, final O fallbackValue) {
@@ -100,17 +100,46 @@ public static String format(final String format, final String varStartIndicator,
 	/**
 	 * Copies the contents of {@code str} into the {@code currentBuffer}. If the size of
 	 * the buffer is not sufficient to store the string then a new buffer is allocated.
+	 * {@code copyToBuffer} is intended to be used as shown in the example:
+	 * <pre>
+	 *   final int INITIAL_SIZE = 10;
+	 *   char[] myBuffer = new char[INITIAL_SIZE];
 	 *
-	 * @param str string to copy
+	 *   List<String> strings = getAListOfStringsFromSomewhere();
+	 *   for (String str : strings) {
+	 *     myBuffer = StringUtil.copyToBuffer(str, myBuffer);
+	 *     dataLen = str.length();
+	 *     // Process data in myBuffer in the range from 0 to dataLen
+	 *   }
+	 *   myBuffer = null;
+	 * </pre>
+	 *
+	 * This allows the buffer to be reused but at the same time frees the user from
+	 * having to manage the size of the buffer.
+	 *
+	 * @param str string to copy. Must not be null.
 	 * @param currentBuffer array to store the string in. If it is too small a new buffer
-	 *                      is allocated
-	 * @return either currentBuffer or a new buffer if one was allocated.
+	 *                      is allocated.  currentBuffer must not be null.
+	 *                      The length of the current buffer must not be 0.
+	 * @return either currentBuffer or a new buffer if one was allocated. The returned
+	 *                      buffer may be larger than the string. Users should call
+	 *                      {@code str.length()} to retrieve the actual length of the
+	 *                      data in the returned buffer.
 	 */
 	public static char[] copyToBuffer(final String str, final char[] currentBuffer) {
-		char[] buffer = currentBuffer;
+		assert str != null;
+		assert currentBuffer != null;
+		assert currentBuffer.length > 0;
+
 		final int strLen = str.length();
-		while(strLen > buffer.length) {
-			buffer = new char[buffer.length * 2];
+		char[] buffer = currentBuffer;
+		int bufferLen = buffer.length;
+
+		while(strLen > bufferLen) {
+			bufferLen *= 2;
+		}
+		if (bufferLen > buffer.length) {
+			buffer = new char[bufferLen];
 		}
 		str.getChars(0, strLen, buffer, 0);
 		return buffer;

src/test/java/org/culturegraph/mf/util/StringUtilTest.java

@@ -0,0 +1,55 @@
+/*
+ *  Copyright 2014 Christoph Böhme
+ *
+ *  Licensed under the Apache License, Version 2.0 the "License";
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.culturegraph.mf.util;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+
+import org.junit.Test;
+
+/**
+ * Tests for the static methods in {@link StringUtil}.
+ *
+ * @author Christoph Böhme
+ *
+ */
+public final class StringUtilTest {
+
+	private static final String STRING_WITH_4_CHARS = "1234";
+	private static final String STRING_WITH_10_CHARS = "1234567890";
+
+	@Test
+	public void copyToBufferShouldResizeBufferIfNecessary() {
+		final char[] buffer = new char[2];
+		final String str = STRING_WITH_10_CHARS;
+
+		final char[] newBuffer = StringUtil.copyToBuffer(str, buffer);
+
+		assertTrue(newBuffer.length >= str.length());
+	}
+
+	@Test
+	public void copyToBufferShouldReturnBufferContainingTheStringData() {
+		final int bufferLen = STRING_WITH_4_CHARS.length();
+		char[] buffer = new char[bufferLen];
+		final String str = STRING_WITH_4_CHARS;
+
+		buffer = StringUtil.copyToBuffer(str, buffer);
+
+		assertEquals(STRING_WITH_4_CHARS, String.valueOf(buffer, 0, bufferLen));
+	}
+
+}