com.sas.collection
Class StringCollection

com.sas.collection.StringCollection

All Implemented Interfaces:

com.sas.beans.PropertyChangeSource, com.sas.beans.VetoableChangeSource, CollectionInterface, com.sas.collection.ContentsChangedListener, com.sas.collection.ContentsChangedSource, OrderedCollectionInterface, Sortable, StaticCollectionInterface, StaticOrderedCollectionInterface, StaticStringListInterface, StringCollectionInterface, StringListInterface, ComponentInterface, LinkPropertiesInterface, ModelInterface, com.sas.PublicClonable, com.sas.util.Countable, com.sas.util.Enumerable, com.sas.util.EventGateInterface, IndexedGetInterface, IndexedSetInterface, ViewInterface, MultipleValueEventSourceInterface, java.beans.PropertyChangeListener, java.io.ObjectInputValidation, java.io.Serializable, java.lang.Cloneable, java.util.EventListener

public class StringCollection
implements StringCollectionInterface, com.sas.collection.ContentsChangedListener

A StringCollection is an ordered collection of java.lang.String values.

See Also:

Serialized Form

Field Summary

protected OrderedCollection	collection The actual data structure that holds the data
static java.lang.String	RB_KEY

Fields inherited from class com.sas.collection.BaseCollection

allContentsChangedListeners, mappingObject

Constructor Summary

StringCollection()
Default constructor.

StringCollection(int initialCapacity)
A constructor that allows the user to specify the initial capacity.

StringCollection(StaticStringListInterface strings)
Construct a StringCollection that is populated with another collection of Strings.

StringCollection(java.lang.String source)
Construct a new StringCollection from comma separated text.

StringCollection(java.lang.String[] strings)
Construct a StringCollection that is populated with an array of Strings.

StringCollection(java.lang.String source, char separator)
Constructor that takes a String and a separator character and converts the String into a list of Strings.

Method Summary

void	add(java.lang.Object item) Add a String to this collection.
void	add(java.lang.Object item, int index) Add a String at a specific location in this collection.
void	add(java.lang.String item) Add a string to this collection.
void	add(java.lang.String item, int index) Add an item to this collection at a specific location.
void	addItems(java.util.Enumeration items) Add all elements of an enumeration to this collection.
void	addItems(java.util.Enumeration items, int index) Add multiple strings to this collection.
void	addItems(StaticStringListInterface items) Add multiple strings to this collection.
void	append(int index, java.lang.Object item) Store a string to this collection, or append it if necessary.
void	append(int index, java.lang.String string) Store a string to this collection, or append it if necessary.
void	apply(com.sas.util.ApplyInterface action) Applies the action action to every item in the current collection.
java.lang.Object	clone() Clone the StringCollection
boolean	contains(java.lang.Object element) Test for the existence of a String in this collection
void	contentsChanged(com.sas.collection.ContentsChangedEvent event) Handle a ContentsChangedEvent.
int	count() Returns the number of strings in this collection
boolean	equals(java.lang.Object obj) Test for equality.
boolean	equals(StaticOrderedCollectionInterface orderedCollection) Test if this collection equals another string collection by comparing elements in order.
boolean	equals(StaticStringListInterface list) Test if this collection equals another string collection by comparing elements in order.
java.lang.Object	get(int index) Fetch a String at an index.
static com.sas.beans.ExtendedBeanInfo	getExtendedBeanInfo()
int	getIndex(java.lang.Object element, int startIndex) Returns the index associated with the String (searches forward)
int	getIndex(java.lang.String item, int startIndex) Returns the index associated with the string (searches forward)
java.util.Enumeration	getItems() Return an Enumeration of all the strings.
java.util.Enumeration	getItems(int start, int end) Returns an enumeration of the strings from this collection.
int	getLastIndex(java.lang.Object element, int startIndex) Returns the last index associated with the string (searches backward)
int	getLastIndex(java.lang.String string, int startIndex) Returns the last index associated with the string (searches backward)
java.lang.String	getString(int index) Fetch a string at an index.
java.lang.String[]	getStringItems() Return the strings in this collection as an array of strings.
StaticStringListInterface	getStringItems(int start, int end) Extract a sublist of strings from this collection.
boolean	remove(java.lang.Object string) Remove a string from this collection.
void	removeAll() Remove all strings from this collection.
int	removeAll(java.lang.Object element) Remove all occurrences of a string from this collection.
java.lang.Object	removeAt(int index) Remove from this collection the string at the specified index.
void	removeAt(int start, int n) Delete multiple strings starting at a specified index.
java.lang.String	removeStringAt(int index) Delete a string at a specified index.
void	set(int index, java.lang.Object item) Replace the item at the specified index with a new item.
void	setSize(int newSize) Set the number of items that are being held in this collection.
void	setString(int index, java.lang.String item) Replace the string at the specified index with a new string
void	sort(boolean ascending) Sorts the current collection in place in ascending/descending order using the built-in String comparator.
void	sort(boolean ascending, int start, int end) Sorts the current collection in place in ascending/descending order using the built-in String comparison functions.
void	sort(com.sas.util.Comparator comparator) Sorts the current collection in place using the provided comparison function.
void	sort(com.sas.util.Comparator comparator, int start, int end) Sorts the current collection in place using the provided comparison function.
java.lang.String	toString() Convert the string collection to a single string.
java.lang.String	toString(char delimiter, boolean alwaysQuote) Convert the string collection to a single string.
java.lang.String[]	toStringArray() Return the Strings in this collection as an array of Strings.

Methods inherited from class com.sas.collection.BaseCollection

addContentsChangedListener, anyContentsChangedListeners, disableEvents, enableEvents, enableEvents, fireContentsChanged, map, removeContentsChangedListener, unmap

Methods inherited from class com.sas.Component

addLink, addPropertyChangeListener, addVetoableChangeListener, anyPropertyChangeListeners, attachModel, attachView, beansIsDesignTime, beansSetDesignTime, clone, detachModel, detachView, dumpComponent, firePropertyChange, firePropertyChange, fireVetoableChange, getComponentDescription, getComponentSupportInfo, getEventMethod, getEventValues, getLinkInfo, getModelInterface, getRequiredInterfaces, getResources, getStringResource, getViewInterfaceSupportInfo, initialize, initializeComponent, isDesignTime, isLinked, propertyChange, queryLinks, queryLinks, refresh, removeAllLinks, removeInterfaceTraps, removeLink, removePropertyChangeListener, removeVetoableChangeListener, setComponentDescription, setComponentSupportInfo, setDefaultValues, setLinkInfo, setModelInterface, setRequiredInterfaces, setViewInterfaceSupportInfo, supportsListenerInterface, supportsRequiredInterfaces, trapInterfaceEvents, validateObject

Methods inherited from interface com.sas.collection.ContentsChangedSource

addContentsChangedListener, removeContentsChangedListener

Methods inherited from interface com.sas.beans.PropertyChangeSource

addPropertyChangeListener, removePropertyChangeListener

Field Detail

RB_KEY

public static final java.lang.String RB_KEY

See Also:

Constant Field Values

collection

protected OrderedCollection collection

The actual data structure that holds the data

Constructor Detail

StringCollection

public StringCollection()

Default constructor. Create and empty StringCollection.

StringCollection

public StringCollection(java.lang.String source)

Construct a new StringCollection from comma separated text.

Parameters:

source - a string of comma separated items. This invokes the StringCollection(String, ',') constructor.

StringCollection

public StringCollection(java.lang.String source,
                        char separator)

Constructor that takes a String and a separator character and converts the String into a list of Strings.

Parameters:

source - The String to be broken up. Leading and trailing space is trimmed from each item. Items may be quoted but it is necessary only if the item contains the separator or double quotes, Unicode, octal, or other escaped characters.

separator - The character to be used as a separator.

StringCollection

public StringCollection(int initialCapacity)

A constructor that allows the user to specify the initial capacity. The collection will be empty but will initially have room for initialCapacity strings items. This may be desirable for efficiency reasons if the client knows that a large list will be required. The collection can grow beyond this initialCapacity.

Parameters:

initialCapacity - The initial capacity of the list.

StringCollection

public StringCollection(StaticStringListInterface strings)

Construct a StringCollection that is populated with another collection of Strings.

Parameters:

strings - a collection of strings.

StringCollection

public StringCollection(java.lang.String[] strings)

Construct a StringCollection that is populated with an array of Strings.

Parameters:

strings - an array of String with which to initialize the StringCollection

Method Detail

getExtendedBeanInfo

public static com.sas.beans.ExtendedBeanInfo getExtendedBeanInfo()

add

public void add(java.lang.String item,
                int index)

Add an item to this collection at a specific location. Items will be shifted forward to make room for the new item.

Specified by:

add in interface StringListInterface

Parameters:

item - The item to insert into this collection

index - The index where the item will be inserted. A call of getString(index) will return the item after the call is completed.

Throws:

java.lang.IndexOutOfBoundsException - if index is not in the range [0..count()]

append

public void append(int index,
                   java.lang.Object item)

Store a string to this collection, or append it if necessary. Calls append(index, (String) item)last.

Parameters:

item - The Object to be added to the StringCollection; it must be null or a String.

Throws:

java.lang.ClassCastException - if item is not a String

append

public void append(int index,
                   java.lang.String string)

Store a string to this collection, or append it if necessary. If this collection contains fewer than index items, perform a setSize(index+1) first. Then perform a set(index, string).

Parameters:

string - The string to be added to the StringCollection

contentsChanged

public void contentsChanged(com.sas.collection.ContentsChangedEvent event)

Handle a ContentsChangedEvent. (This method is used internally.)

Specified by:

contentsChanged in interface com.sas.collection.ContentsChangedListener

Parameters:

event - a ContentsChangedEvent

add

public void add(java.lang.String item)

Add a string to this collection.

Specified by:

add in interface StringListInterface

Parameters:

item - a string to add to the end of this list.

addItems

public void addItems(StaticStringListInterface items)

Add multiple strings to this collection.

Specified by:

addItems in interface StringListInterface

Parameters:

items - a list of strings to add to the end of this list.

addItems

public void addItems(java.util.Enumeration items)

Add all elements of an enumeration to this collection.

Specified by:

addItems in interface CollectionInterface

Parameters:

items - an Enumeration of strings to add to the end of this collection

Throws:

java.lang.ClassCastException - if the enumeration contains non-String items.

addItems

public void addItems(java.util.Enumeration items,
                     int index)

Add multiple strings to this collection.

Specified by:

addItems in interface OrderedCollectionInterface

Parameters:

index - Insert the objects starting before the indexed item. The first of the newly inserted item can be accessed by get(index) afterwards.

items - an Enumeration of strings to add to this collection at the index.

Throws:

java.lang.ClassCastException - if the enumeration contains non-String items.

add

public void add(java.lang.Object item)

Add a String to this collection.

Specified by:

add in interface CollectionInterface

Parameters:

item - a String to add to this collection

Throws:

java.lang.ClassCastException - is thrown if item is non-null and not a String.

add

public void add(java.lang.Object item,
                int index)

Add a String at a specific location in this collection.

Specified by:

add in interface OrderedCollectionInterface

Parameters:

item - the string to add to this collection. The string may exist multiple times in this collection.

Insert - the string before the indexed item. The newly inserted string can be accessed by get(index) afterwards.

Throws:

java.lang.IndexOutOfBoundsException - if index is not in the range [0, count()].

java.lang.ClassCastException - This is thrown if the caller tries to insert a non-String.

apply

public void apply(com.sas.util.ApplyInterface action)

Applies the action action to every item in the current collection. This is a general way to modify all the items in this collection.

Specified by:

apply in interface StaticCollectionInterface

Overrides:

apply in class BaseCollection

Parameters:

action - An object which operates on another object.

removeAll

public void removeAll()

Remove all strings from this collection.

Specified by:

removeAll in interface CollectionInterface

Specified by:

removeAll in interface StringListInterface

contains

public boolean contains(java.lang.Object element)

Test for the existence of a String in this collection

Specified by:

contains in interface StaticCollectionInterface

Overrides:

contains in class BaseCollection

Parameters:

element - the string to search for

Returns:

true if and only the string exists in this collection.

Throws:

java.lang.ClassCastException - This is thrown if the caller tries to insert a non-String.

See Also:

StaticCollectionInterface.contains(java.lang.Object)

count

public int count()

Returns the number of strings in this collection

Specified by:

count in interface com.sas.util.Countable

Specified by:

count in class BaseCollection

Returns:

the number of strings in this collection

equals

public boolean equals(StaticStringListInterface list)

Test if this collection equals another string collection by comparing elements in order.

Specified by:

equals in interface StaticStringListInterface

Parameters:

list - Another string collection to be compared to.

Returns:

true if equal, false otherwise.

equals

public boolean equals(StaticOrderedCollectionInterface orderedCollection)

Test if this collection equals another string collection by comparing elements in order.

Specified by:

equals in interface StaticOrderedCollectionInterface

Parameters:

orderedCollection - Another ordered collection to be compared to.

Returns:

true if equal, false otherwise.

equals

public boolean equals(java.lang.Object obj)

Test for equality. If the object is a StaticStringListInterface or StaticOrderedCollectionInterface, compare the collection contents for equality as well using equals(StaticStringListInterface) or equals(StaticOrderedCollectionInterface), respoectively. If obj is neither of these interfaces, return false.

Overrides:

equals in class java.lang.Object

Parameters:

obj - an object to compare to.

Returns:

true if equal, false otherwise.

get

public java.lang.Object get(int index)

Fetch a String at an index.

Specified by:

get in interface IndexedGetInterface

Parameters:

index - the position of the item, zero-based indexing.

Returns:

the string associated with the index value

Throws:

java.lang.IndexOutOfBoundsException - if index is not in the range [0, count()-1].

getIndex

public int getIndex(java.lang.String item,
                    int startIndex)

Returns the index associated with the string (searches forward)

Specified by:

getIndex in interface StaticStringListInterface

Parameters:

item - string to search for

startIndex - index where search should start

Returns:

the zero-based index corresponding to the string or -1 if the string is not found.

Throws:

java.lang.IndexOutOfBoundsException - if startIndex is not in the range [0..count()-1]

getIndex

public int getIndex(java.lang.Object element,
                    int startIndex)

Returns the index associated with the String (searches forward)

Specified by:

getIndex in interface StaticOrderedCollectionInterface

Parameters:

element - string to search for

startIndex - the position where the search should start

Returns:

the zero-based index corresponding to the string or -1 if the string is not found.

Throws:

java.lang.IndexOutOfBoundsException - if startIndex is not valid.

java.lang.ClassCastException - if the caller tries to insert a non-String.

getStringItems

public StaticStringListInterface getStringItems(int start,
                                                int end)

Extract a sublist of strings from this collection.

Specified by:

getStringItems in interface StaticStringListInterface

Parameters:

start - the index of the first string, zero based.

end - one past the index of the last item to include in the sublist, zero based.

Returns:

a collection of the selected elements.

Throws:

java.lang.IndexOutOfBoundsException - if start is not in the range [0, count()-1]. or end is not in the range [0, count()].

See Also:

StaticOrderedCollectionInterface.getItems(int, int), String.substring(int, int)

getStringItems

public java.lang.String[] getStringItems()

Return the strings in this collection as an array of strings.

Specified by:

getStringItems in interface StaticStringListInterface

Returns:

an array containin this collection's strings, in order.

toStringArray

public final java.lang.String[] toStringArray()

Return the Strings in this collection as an array of Strings. This is an alias for getStringItems()

Returns:

an array containin this collection's strings, in order.

getItems

public java.util.Enumeration getItems()

Return an Enumeration of all the strings.

Specified by:

getItems in interface com.sas.util.Enumerable

Specified by:

getItems in class BaseCollection

Returns:

an Enumeration of this collection's elements

See Also:

Enumerable.getItems()

getItems

public java.util.Enumeration getItems(int start,
                                      int end)

Returns an enumeration of the strings from this collection.

Specified by:

getItems in interface StaticOrderedCollectionInterface

Parameters:

start - the index of the first string, zero based.

end - one past the index of the last item to include in the enumeration, zero based. Note that the range of elements returned in the Enumeration does not include the endthe item; this is consistent with substring(start, end), for example.

Returns:

an Enumeration of the strings.

Throws:

java.lang.IndexOutOfBoundsException - if start is not in the range [0, count()-1], or if end is not in the range [0, count()]

getLastIndex

public int getLastIndex(java.lang.String string,
                        int startIndex)

Returns the last index associated with the string (searches backward)

Specified by:

getLastIndex in interface StaticStringListInterface

Parameters:

string - the string to search for

startIndex - index where search should start

Returns:

the zero-based index corresponding to the last string in this collection which equals string, or -1 if the string is not found.

Throws:

java.lang.IndexOutOfBoundsException - if the start index is not in the range [0..count()-1]

getLastIndex

public int getLastIndex(java.lang.Object element,
                        int startIndex)

Returns the last index associated with the string (searches backward)

Specified by:

getLastIndex in interface StaticOrderedCollectionInterface

Parameters:

element - the string to search for

startIndex - the position where the search should start

Returns:

the zero-based index corresponding to the last string in this collection which equals string and is at or before startIndex, or -1 if the string is not found.

Throws:

java.lang.IndexOutOfBoundsException - if startIndex is not valid.

getString

public java.lang.String getString(int index)

Fetch a string at an index.

Specified by:

getString in interface StaticStringListInterface

Parameters:

the - position of the string, zero based indexing.

Returns:

the string associated with the index value

Throws:

java.lang.IndexOutOfBoundsException - if index is not in the range [0, count()-1].

remove

public boolean remove(java.lang.Object string)

Remove a string from this collection. If the string appears multiple times, only the first occurrence is removed.

Specified by:

remove in interface CollectionInterface

Parameters:

string - the string to remove

Returns:

true if the string was removed, false if not.

removeAll

public int removeAll(java.lang.Object element)

Remove all occurrences of a string from this collection.

Specified by:

removeAll in interface CollectionInterface

Parameters:

element - the item to remove

Returns:

the number of items deleted

removeAt

public void removeAt(int start,
                     int n)

Delete multiple strings starting at a specified index.

Specified by:

removeAt in interface StringListInterface

Parameters:

start - position of first string to delete

n - number of strings to delete from this collection

Throws:

java.lang.IndexOutOfBoundsException - if start or (start+n-1) are not in the range [0..count()-1]

removeAt

public java.lang.Object removeAt(int index)

Remove from this collection the string at the specified index.

Specified by:

removeAt in interface OrderedCollectionInterface

Parameters:

index - the position of the string, zero-based indexing.

Returns:

the item that was removed from this collection

Throws:

java.lang.IndexOutOfBoundsException - if index is not in the range [0, count()-1].

removeStringAt

public java.lang.String removeStringAt(int index)

Delete a string at a specified index.

Specified by:

removeStringAt in interface StringListInterface

Parameters:

index - delete the string at this zero-based position

Returns:

the string at the specified position

Throws:

java.lang.IndexOutOfBoundsException - if the index is not in the range [0..count()-1]

See Also:

StringListInterface.removeAt(int, int)

set

public void set(int index,
                java.lang.Object item)

Replace the item at the specified index with a new item.

Specified by:

set in interface OrderedCollectionInterface

Specified by:

set in interface IndexedSetInterface

Parameters:

index - The position where the item will be placed.

item - The object to be added to this Collection

Throws:

java.lang.IndexOutOfBoundsException - if index is not in the range [0, count()-1].

java.lang.ClassCastException - This is thrown if item is not a String.

setString

public void setString(int index,
                      java.lang.String item)

Replace the string at the specified index with a new string

Specified by:

setString in interface StringListInterface

Parameters:

index - position of the string to replace

item - The new string to put in the specified location

Throws:

java.lang.IndexOutOfBoundsException - if index is not in the range [0..count()-1]

setSize

public void setSize(int newSize)

Set the number of items that are being held in this collection. If newSize is smaller than the current collection size, then this collection is truncated to the size specified. If newSize is greater than the current collection size, then this collection is extended, and the new collection slots are assigned null.

Specified by:

setSize in interface OrderedCollectionInterface

Specified by:

setSize in interface StringListInterface

Parameters:

size - The new size of this collection

Throws:

java.lang.IndexOutOfBoundsException - if newSize is less than zero.

sort

public void sort(com.sas.util.Comparator comparator,
                 int start,
                 int end)

Sorts the current collection in place using the provided comparison function.

Specified by:

sort in interface Sortable

Specified by:

sort in interface StringListInterface

Parameters:

comparator - An instance of a Comparator which providess a Comparator.compare(Object, Object) function.

start - the index of the first item in the range to sort

end - sort the items between start and (end-1)

See Also:

Comparator

sort

public void sort(com.sas.util.Comparator comparator)

Sorts the current collection in place using the provided comparison function.

Specified by:

sort in interface Sortable

Specified by:

sort in interface StringListInterface

Parameters:

comparator - An instance of a Comparator which provides a Comparator.compare(Object, Object) function.

See Also:

Comparator

sort

public void sort(boolean ascending)

Sorts the current collection in place in ascending/descending order using the built-in String comparator.

Specified by:

sort in interface StringListInterface

Parameters:

ascending - If true, sort this collection in ascending order; otherwise descending order.

See Also:

StringComparator

sort

public void sort(boolean ascending,
                 int start,
                 int end)

Sorts the current collection in place in ascending/descending order using the built-in String comparison functions.

Specified by:

sort in interface StringListInterface

Parameters:

ascending - If true, sort this collection in ascending order; otherwise descending order.

start - the index of the first item in the range to sort

end - sort the items between start and (end-1)

See Also:

StringComparator

toString

public java.lang.String toString()

Convert the string collection to a single string. This has the same effect as calling toString(',', true).

Overrides:

toString in class java.lang.Object

Returns:

a string consisting of the quoted elements of the StringCollection, separated by commas.

toString

public java.lang.String toString(char delimiter,
                                 boolean alwaysQuote)

Convert the string collection to a single string.

Parameters:

delimiter - a delimiter for separating the items.

alwaysQuote - if true, all items are quoted. If false, only quote items which require quotes (such as strings containing the delimiter character, or the '\' character, etc.)

Returns:

a string consisting of the optionally quoted elements of the StringCollection, separated by a delimiter.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clone the StringCollection

Specified by:

clone in interface CollectionInterface

Specified by:

clone in interface OrderedCollectionInterface

Specified by:

clone in interface StaticCollectionInterface

Specified by:

clone in interface StaticOrderedCollectionInterface

Specified by:

clone in interface StaticStringListInterface

Specified by:

clone in interface StringListInterface

Specified by:

clone in interface com.sas.PublicClonable

Overrides:

clone in class BaseCollection

Returns:

a clone of this StringCollection

Throws:

java.lang.CloneNotSupportedException - if this collection cannot be cloned.