com.ibm.are.common
Class StringList

java.lang.Object
  extended by java.util.AbstractCollection
      extended by java.util.AbstractList
          extended by java.util.AbstractSequentialList
              extended by java.util.LinkedList
                  extended by com.ibm.are.common.GenericList
                      extended by com.ibm.are.common.StringList
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.lang.Iterable, java.util.Collection, java.util.Deque, java.util.List, java.util.Queue

public class StringList
extends GenericList

The StringList class represents a list of java.lang.String objects. Because only strings are allowed to exist in the list, this class can provide a robust set of methods to query, manipulate, and search the contents of the list. Many of the features provided by this class allow users to choose between case sensitive or case insensitive implementations.

Beyond list operations, this class also provides a standardized format for a string representation of itself. This string representation can be provided by this class using the GenericList.toString() method, or can be parsed and built into a StringList object by this class using the parse(String) method.

The string representation of this class has the following format:

    Start of list marker is an open bracket: [

    End of list marker is a close bracket: ]

Each item in the list is enclosed by single quotes. Typically items in the list are separated by a single space, but this is not a requirement.

Version:
1.0
Author:
IBM
See Also:
Serialized Form

Field Summary
static java.lang.String COPYRIGHT
          Copyright for class bytecode
 
Fields inherited from class com.ibm.are.common.GenericList
DEFAULT_LIST_END_MARKER, DEFAULT_LIST_ITEM_END_MARKER, DEFAULT_LIST_ITEM_START_MARKER, DEFAULT_LIST_START_MARKER, listEndMarker, listItemEndMarker, listItemStartMarker, listStartMarker, maxInputListItems
 
Fields inherited from class java.util.AbstractList
modCount
 
Constructor Summary
StringList()
          Constructs an empty StringList object
StringList(java.util.Collection c)
          Constructs a StringList object and populates it with the contents of the given collection.
StringList(java.util.Iterator strListIter)
          Constructs a StringList object and populates it with the contents of all of the items in the provided iterator.
StringList(java.lang.String theList)
          Constructs a StringList object and populates it with the contents of the string representation of a StringList specified by the input parameter.
StringList(java.lang.String[] theList)
          Constructs a StringList object and populates it with the contents of the provided string array.
 
Method Summary
 void addAll(java.util.Iterator strListIter)
          Adds all of the items in the iterator to the list
 void addAll(java.lang.String theList)
          Adds all of the items from the string representation of a StringList to this object's list.
 void addAll(java.lang.String[] theList)
          Adds all of the strings in the array to the list
 boolean containsAllIgnoreCase(StringList otherList)
          Searches the list of strings to see if the list contains all of the items in given list of strings.
 boolean containsIgnoreCase(java.lang.Object o)
          Searches the list of strings to see if the list contains the given item.
 boolean containsIgnoreCase(StringList otherList)
          Check if the list of strings contains every string in the given list.
 boolean equalsIgnoreCase(StringList otherList)
          Compare whether the given list contains all the strings in this list and this list contains all the strings in the given list, regardless of the element order.
 StringList findElementsContainingText(java.lang.String theText)
          Searches the list of strings for the specified text.
protected  StringList findElementsContainingText(java.lang.String theText, boolean ignoreCase)
          Implementation of the findElementsContainingText and findElementsContainingTextIgnoreCase methods.
 StringList findElementsContainingTextIgnoreCase(java.lang.String theText)
          Searches the list of strings for the specified text.
static boolean isList(java.lang.String candidate)
          Determines if the given string is a string representation of a StringList object.
static StringList parse(java.lang.String str)
          Parses the given string and creates a StringList object that contains all of the items represented by the string.
 void removeAllIgnoreCase(StringList otherList)
          Removes all items in the given list from the list of strings.
 java.lang.String removeIgnoreCase(java.lang.String item)
          Removes the given item from the list of strings.
 java.lang.String[] toStringArray()
          Puts the contents of the list of strings into an array of strings.
 
Methods inherited from class com.ibm.are.common.GenericList
equals, getListEndMarker, getListItemEndMarker, getListItemStartMarker, getListStartMarker, initFields, setListEndMarker, setListItemEndMarker, setListItemStartMarker, setListStartMarker, toString
 
Methods inherited from class java.util.LinkedList
add, add, addAll, addAll, addFirst, addLast, clear, clone, contains, descendingIterator, element, get, getFirst, getLast, indexOf, lastIndexOf, listIterator, offer, offerFirst, offerLast, peek, peekFirst, peekLast, poll, pollFirst, pollLast, pop, push, remove, remove, remove, removeFirst, removeFirstOccurrence, removeLast, removeLastOccurrence, set, size, toArray, toArray
 
Methods inherited from class java.util.AbstractSequentialList
iterator
 
Methods inherited from class java.util.AbstractList
hashCode, listIterator, removeRange, subList
 
Methods inherited from class java.util.AbstractCollection
containsAll, isEmpty, removeAll, retainAll
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.List
containsAll, hashCode, isEmpty, iterator, listIterator, removeAll, retainAll, subList
 

Field Detail

COPYRIGHT

public static final java.lang.String COPYRIGHT
Copyright for class bytecode

See Also:
Constant Field Values
Constructor Detail

StringList

public StringList()
Constructs an empty StringList object


StringList

public StringList(java.util.Collection c)
Constructs a StringList object and populates it with the contents of the given collection. If any items in the collection are not strings, an IllegalArgumentException exception is thrown.

Parameters:
c - The collection of items to add to the newly created list
Throws:
java.lang.IllegalArgumentException - If any item in the collection is not a string

StringList

public StringList(java.lang.String theList)
Constructs a StringList object and populates it with the contents of the string representation of a StringList specified by the input parameter.

Parameters:
theList - A string representation of a StringList whose items should be added to the newly constructed StringList object.
Throws:
java.lang.IllegalArgumentException - If the input parameter is not a string representation of a StringList

StringList

public StringList(java.lang.String[] theList)
Constructs a StringList object and populates it with the contents of the provided string array.

Parameters:
theList - An array of strings to add to the newly constructed StringList object

StringList

public StringList(java.util.Iterator strListIter)
Constructs a StringList object and populates it with the contents of all of the items in the provided iterator. If any items in the iterator are not strings, an IllegalArgumentException exception is thrown.

Parameters:
strListIter - An iterator whose contents are to be added to the newly constructed StringList object
Throws:
java.lang.IllegalArgumentException - If any item in the iterator is not a string
Method Detail

parse

public static StringList parse(java.lang.String str)
Parses the given string and creates a StringList object that contains all of the items represented by the string. If the provided string is just a single string, and not a string representation of a StringList, then a new StringList object is created and the string itself is added as the list's only item.

Parameters:
str - The string to parse and build a StringList from
Returns:
A StringList object that all of the items represented by the string

isList

public static boolean isList(java.lang.String candidate)
Determines if the given string is a string representation of a StringList object.

Parameters:
candidate - The string to inspect
Returns:
true if the given string is a string representation of a StringList object, false if it is not.

addAll

public void addAll(java.lang.String theList)
Adds all of the items from the string representation of a StringList to this object's list.

Parameters:
theList - The string representation of a StringList
Throws:
java.lang.IllegalArgumentException - If the input parameter is not a string representation of a StringList

addAll

public void addAll(java.lang.String[] theList)
Adds all of the strings in the array to the list

Parameters:
theList - Array of strings to add to the list

addAll

public void addAll(java.util.Iterator strListIter)
Adds all of the items in the iterator to the list

Parameters:
strListIter - An iterator whose contents are to be added to the list
Throws:
java.lang.IllegalArgumentException - If any item in the iterator is not a string

containsIgnoreCase

public boolean containsIgnoreCase(java.lang.Object o)
Searches the list of strings to see if the list contains the given item. All comparisons between items in the list and the given item are done in a case insensitive manner.

Parameters:
o - The item to search for
Returns:
true if the given item is contained in the list, false if it is not. If the given item is null or the item is not a string, false is returned.

containsAllIgnoreCase

public boolean containsAllIgnoreCase(StringList otherList)
Searches the list of strings to see if the list contains all of the items in given list of strings. All comparisons between items in the list and the given list of strings are done in a case insensitive manner.

Parameters:
otherList - The list of items to search for in the list of strings
Returns:
true if the list of items to search for are all contained in the list of strings, false if they are not.

equalsIgnoreCase

public boolean equalsIgnoreCase(StringList otherList)
Compare whether the given list contains all the strings in this list and this list contains all the strings in the given list, regardless of the element order. All comparisons between items in the lists are performed in a case insensitive manner.

Parameters:
otherList - The list to compare against for equality
Returns:
true if the two lists are equal (ignoring case), false if they are not equal.

containsIgnoreCase

public boolean containsIgnoreCase(StringList otherList)
Check if the list of strings contains every string in the given list. All comparisons between items in the lists are performed in a case insensitive manner.

Parameters:
otherList - The list to search
Returns:
true if this list contains every string in the given list, false if it does not. If the given list is empty, true is returned.

removeIgnoreCase

public java.lang.String removeIgnoreCase(java.lang.String item)
Removes the given item from the list of strings. The list is searched until the given item is found, or until the end of the list is reached. All comparisons done during the search for the given item in the list are done in a case insensitive manner.

Parameters:
item - The item to remove from the list of strings
Returns:
A reference to the item that was removed from the list, or null if the given item was not found in the list.

removeAllIgnoreCase

public void removeAllIgnoreCase(StringList otherList)
Removes all items in the given list from the list of strings. All comparisons done during the search for the given item in the list are done in a case insensitive manner.

Parameters:
otherList - The list of strings to remove

toStringArray

public java.lang.String[] toStringArray()
Puts the contents of the list of strings into an array of strings.

Returns:
The contents of the list of strings as an array of strings.

findElementsContainingText

public StringList findElementsContainingText(java.lang.String theText)
Searches the list of strings for the specified text. All items in the list that contain the specified text are put into a newly allocated StringList and returned.

Parameters:
theText - The text to find within each item in the list of strings
Returns:
A newly allocated StringList containing all items in the list that contain the specified text. If no items were found that match the specified text, an empty list is returned.

findElementsContainingTextIgnoreCase

public StringList findElementsContainingTextIgnoreCase(java.lang.String theText)
Searches the list of strings for the specified text. All items in the list that contain the specified text are put into a newly allocated StringList and returned. Comparisons done to between the given text and the items in the list of strings are done in a case insensitive manner.

Parameters:
theText - The text to find within each item in the list of strings
Returns:
A newly allocated StringList containing all items in the list that contain the specified text. If no items were found that match the specified text, an empty list is returned.

findElementsContainingText

protected StringList findElementsContainingText(java.lang.String theText,
                                                boolean ignoreCase)
Implementation of the findElementsContainingText and findElementsContainingTextIgnoreCase methods.

Parameters:
theText - The text to search for
ignoreCase - Whether or not the search is case sensitive
Returns:
A newly allocated StringList containing all items in the list that contain the specified text. If no items were found that match the specified text, an empty list is returned.