/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.apache.wicket.util.string;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;

/**
 * An abstract base class for string list implementations. Besides having an implementation for
 * IStringSequence (iterator(), get(int index) and size()), an AbstractStringList can be converted
 * to a String array or a List of Strings.
 * <p>
 * The total length of all Strings in the list can be determined by calling totalLength().
 * <p>
 * Strings or a subset of Strings in the list can be formatted using three join() methods:
 * <p>
 * <ul>
 * <li>join(String) Joins strings together using a given separator
 * <li>join() Joins Strings using comma as a separator
 * <li>join(int first, int last, String) Joins a sublist of strings using a given separator
 * </ul>
 * 
 * @author Jonathan Locke
 */
public abstract class AbstractStringList implements IStringSequence, Serializable
{
	/**
	 * 
	 */
	private static final long serialVersionUID = 1L;

	/**
	 * @return String iterator
	 * @see org.apache.wicket.util.string.IStringSequence#iterator()
	 */
	@Override
	public abstract IStringIterator iterator();

	/**
	 * @return Number of strings in this string list
	 * @see org.apache.wicket.util.string.IStringSequence#size()
	 */
	@Override
	public abstract int size();

	/**
	 * @param index
	 *            The index into this string list
	 * @return The string at the given index
	 * @see org.apache.wicket.util.string.IStringSequence#get(int)
	 */
	@Override
	public abstract String get(int index);

	/**
	 * Returns this String sequence as an array of Strings. Subclasses may provide a more efficient
	 * implementation than the one provided here.
	 * 
	 * @return An array containing exactly this sequence of Strings
	 */
	public String[] toArray()
	{
		// Get number of Strings
		final int size = size();

		// Allocate array
		final String[] strings = new String[size];

		// Copy string references
		for (int i = 0; i < size; i++)
		{
			strings[i] = get(i);
		}

		return strings;
	}

	/**
	 * Returns this String sequence as an array of Strings. Subclasses may provide a more efficient
	 * implementation than the one provided here.
	 * 
	 * @return An array containing exactly this sequence of Strings
	 */
	public final List<String> toList()
	{
		// Get number of Strings
		final int size = size();

		// Allocate list of exactly the right size
		final List<String> strings = new ArrayList<>(size);

		// Add strings to list
		for (int i = 0; i < size; i++)
		{
			strings.add(get(i));
		}

		return strings;
	}

	/**
	 * @return The total length of all Strings in this sequence.
	 */
	public int totalLength()
	{
		// Get number of Strings
		final int size = size();

		// Add strings to list
		int totalLength = 0;

		for (int i = 0; i < size; i++)
		{
			totalLength += get(i).length();
		}

		return totalLength;
	}

	/**
	 * Joins this sequence of strings using a comma separator. For example, if this sequence
	 * contains [1 2 3], the result of calling this method will be "1, 2, 3".
	 * 
	 * @return The joined String
	 */
	public final String join()
	{
		return join(", ");
	}

	/**
	 * Joins this sequence of strings using a separator
	 * 
	 * @param separator
	 *            The separator to use
	 * @return The joined String
	 */
	public final String join(final String separator)
	{
		return join(0, size(), separator);
	}

	/**
	 * Joins this sequence of strings from first index to last using a separator
	 * 
	 * @param first
	 *            The first index to use, inclusive
	 * @param last
	 *            The last index to use, exclusive
	 * @param separator
	 *            The separator to use
	 * @return The joined String
	 */
	public final String join(final int first, final int last, final String separator)
	{
		// Allocate buffer of exactly the right length
		final int length = totalLength() + (separator.length() * (Math.max(0, last - first - 1)));
		final AppendingStringBuffer buf = new AppendingStringBuffer(length);

		// Loop through indexes requested
		for (int i = first; i < last; i++)
		{
			// Add next string
			buf.append(get(i));

			// Add separator?
			if (i != (last - 1))
			{
				buf.append(separator);
			}
		}

		return buf.toString();
	}

	/**
	 * Converts this object to a string representation
	 * 
	 * @return String version of this object
	 */
	@Override
	public String toString()
	{
		return "[" + join() + "]";
	}
}