edu.utexas.its.eis.tools.qwicap.util
Class ArrayToString

java.lang.Object
  edu.utexas.its.eis.tools.qwicap.util.ArrayToString

public class ArrayToString
extends Object

Converts an array or Collection to a neatly formatted String when its toString method is invoked. This class is useful anytime an array or collection of objects is to be converted to a string, but it is particularly useful in conjunction with the Logger, since it allows an array of objects to be incorporated into a log message in a human-readable fashion. Moreover, because it defers all of the nitty-gritty work of the string conversions, formatting and appending until its toString method is invoked, an instance of this class will do no work if the Logger discards the log entry in which it is used.

Note that when performing quoting this class attempts to avoid redundant quoting, so, before any item is quoted it is checked to see if it already begins and ends with the relevant opening- and closing-quote sequences. If it does, no additional quotes are added.

Also note that any type of object may be passed to this class' constructors in place of an array or Collection. Therefore, this class can be used to supply deferred string conversion for any other class, and from time-to-time the quoting logic might come in handy, too.

Author:

Chris W. Johnson

Constructor Summary

ArrayToString(Object A)
Constructs a new ArrayToString object that will create a String representation of the supplied array or Collection object when this object's toString method is invoked, and not before then.

ArrayToString(Object A, String FinalSeparatorStr)
Constructs a new ArrayToString object that will create a String representation of the supplied array or Collection object when this object's toString method is invoked, and not before then.

ArrayToString(Object A, String SeparatorStr, String FinalSeparatorStr, String QuoteStr)
Constructs a new ArrayToString object that will create a String representation of the supplied array or Collection object when this object's toString method is invoked, and not before then.

Method Summary

ArrayToString	alwaysQuote() Causes all elements to be quoted, whether or not this class would ordinarily judge quoting to be necessary.
int	length() The number of elements in the array or Collection that was converted to a String by this object.
ArrayToString	neverQuote() Prevents all elements from being quoted, whether or not this class would ordinarily judge quoting to be necessary.
ArrayToString	setFinalSeparator(String FinalSeparatorStr) Sets the string that should be placed between the final two elements in the array or Collection.
ArrayToString	setQuote(String QuoteStr) Sets the string that should be placed around elements that would benefit from being quoted.
ArrayToString	setQuotes(char OpenQuote, char CloseQuote) Sets the characters that should be placed to the left and right of elements that would benefit from being quoted.
ArrayToString	setQuotes(String OpenQuote, String CloseQuote) Sets the strings that should be placed to the left and right of elements that would benefit from being quoted.
ArrayToString	setSeparator(String SeparatorStr) Sets the separator string to be placed between all elements except the final two (see setFinalSeparator).
String	toString() Returns a String representation of the array or Collection object passed to the constructor.
ArrayToString	trim() Causes the whitespace at the beginning or end of each element in the array or Collection to be trimmed away.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ArrayToString

public ArrayToString(Object A)

Constructs a new ArrayToString object that will create a String representation of the supplied array or Collection object when this object's toString method is invoked, and not before then. Commas will be placed between all elements except for the final two which will be separated by the string " and ". Elements that will benefit from quoting are surrounded by the double-quote ('"') character. An item is judged to benefit from being quoted if it contains any whitespace, or a comma.

Parameters:

A - An array or Collection object whose contents should be converted to a String. At this time, arrays or Collection objects whose elements are other arrays or Collection objects are not supported in a useful manner.

ArrayToString

public ArrayToString(Object A,
                     String FinalSeparatorStr)

Constructs a new ArrayToString object that will create a String representation of the supplied array or Collection object when this object's toString method is invoked, and not before then. Commas will be placed between all elements except for the final two which will be separated by the string specified in the FinalSeparatorStr parameter. Elements that will benefit from quoting are surrounded by the double-quote ('"') character. An item is judged to benefit from being quoted if it contains any whitespace, or a comma.

Parameters:

A - An array or Collection object whose contents should be converted to a String. At this time, arrays or Collection objects whose elements are other arrays or Collection objects are not supported in a useful manner.

FinalSeparatorStr - The string that should be placed between the final two elements in the array or Collection, for example: " and " or " or ".

ArrayToString

public ArrayToString(Object A,
                     String SeparatorStr,
                     String FinalSeparatorStr,
                     String QuoteStr)

Constructs a new ArrayToString object that will create a String representation of the supplied array or Collection object when this object's toString method is invoked, and not before then.

Parameters:

A - An array or Collection object whose contents should be converted to a String. At this time, arrays or Collection objects whose elements are other arrays or Collection objects are not supported in a useful manner.

SeparatorStr - The string that should be placed between elements in the array or Collection, for example: a comma with trailing space (", ").

FinalSeparatorStr - The string that should be placed between the final two elements in the array or Collection, for example: " and " or " or ".

QuoteStr - The string to be placed around items in the array or Collection that would benefit from being quoted. An item is judged to benefit from being quoted if it contains any whitespace, or a comma. To disable all quoting behavior, pass null in this parameter. To provide separate open- and close-quote strings, use setQuotes(java.lang.String, java.lang.String).

Method Detail

setSeparator

public ArrayToString setSeparator(String SeparatorStr)

Sets the separator string to be placed between all elements except the final two (see setFinalSeparator).

Parameters:

SeparatorStr - The string that should be placed between elements in the array or Collection, for example: a comma with trailing space (", ").

Returns:

A reference to this instance of the ArrayToString class.

setFinalSeparator

public ArrayToString setFinalSeparator(String FinalSeparatorStr)

Sets the string that should be placed between the final two elements in the array or Collection.

Parameters:

FinalSeparatorStr - The string that should be placed between the final two elements in the array or Collection, for example: " and " or " or ".

Returns:

A reference to this instance of the ArrayToString class.

setQuote

public ArrayToString setQuote(String QuoteStr)

Sets the string that should be placed around elements that would benefit from being quoted. An item is judged to benefit from being quoted if it contains any whitespace, or a comma. To disable all quoting behavior, pass null, or invoke neverQuote(). To force quoting under all circumstances, invoke alwaysQuote(). To provide separate open- and close-quote strings, use setQuotes.

Parameters:

QuoteStr - The string to be placed around items in the array or Collection that would benefit from being quoted. To disable all quoting behavior, pass null in this parameter.

Returns:

A reference to this instance of the ArrayToString class.

setQuotes

public ArrayToString setQuotes(String OpenQuote,
                               String CloseQuote)

Sets the strings that should be placed to the left and right of elements that would benefit from being quoted. An item is judged to benefit from being quoted if it contains any whitespace, or a comma. To disable all quoting behavior, pass null in both parameters, or invoke neverQuote(). To force quoting under all circumstances, invoke alwaysQuote().

Parameters:

OpenQuote - The string to be placed to the left of items in the array or Collection that would benefit from being quoted.

CloseQuote - The string to be placed to the right of items in the array or Collection that would benefit from being quoted.

Returns:

A reference to this instance of the ArrayToString class.

setQuotes

public ArrayToString setQuotes(char OpenQuote,
                               char CloseQuote)

Sets the characters that should be placed to the left and right of elements that would benefit from being quoted. An item is judged to benefit from being quoted if it contains any whitespace, or a comma. To disable all quoting behavior, or invoke neverQuote(). To force quoting under all circumstances, invoke alwaysQuote().

Parameters:

OpenQuote - The character to be placed to the left of items in the array or Collection that would benefit from being quoted.

CloseQuote - The character to be placed to the right of items in the array or Collection that would benefit from being quoted.

Returns:

A reference to this instance of the ArrayToString class.

alwaysQuote

public ArrayToString alwaysQuote()

Causes all elements to be quoted, whether or not this class would ordinarily judge quoting to be necessary.

Returns:

A reference to this instance of the ArrayToString class.

neverQuote

public ArrayToString neverQuote()

Prevents all elements from being quoted, whether or not this class would ordinarily judge quoting to be necessary.

Returns:

A reference to this instance of the ArrayToString class.

trim

public ArrayToString trim()

Causes the whitespace at the beginning or end of each element in the array or Collection to be trimmed away. By default, trimming does not occur.

Returns:

A reference to this instance of the ArrayToString class.

length

public int length()

The number of elements in the array or Collection that was converted to a String by this object. Note that this information isn't available until this object's toString method has been called once, so length calls toString automatically, if it hasn't already been called.

Returns:

The number of elements in the array or Collection that was passed to this object's constructor.

toString

public String toString()

Returns a String representation of the array or Collection object passed to the constructor. The String representation is not created until this method is called for the first time, and is thereafter cached, so that all future toString invocations will return the same String object as the first invocation, and will do so essentially instantly. Note, however, that if any of the methods that control the way the string is generated are invoked (for example setQuotes or trim()), they will discard the cached String object to ensure that the next time this toString method is invoked, the String that is returned will be formatted in a manner consistent with the caller's expressed intent.

Overrides:

toString in class Object

Returns:

A String representation of the array or Collection object passed to the constructor.