edu.neu.ccs
Class Strings

java.lang.Object
  |
  +--edu.neu.ccs.Strings

public class Strings
extends Object

Class StringsString data together with corresponding tools for decoding such data.

An encoded string will have one of the following forms that we will refer to as a string group:

A string group enclosed in [] uses the character ; as its string separator.

A string group enclosed in () uses the character , as its string separator.

A string group enclosed in {} uses the character | as its string separator.

The encoding methods in this class are NOT 100% robust since the decoding process will fail if any encoded string contains the separator character used for the encoding. To guarantee robust encoding, use the encoding methods in CodecUtilities.

Despite this consideration, these methods of encoding and decoding are quite valuable in the situations where what is to be encoded refers to data that should not contain the particular separator being used. It is for this reason that three forms of encoding are provided with three separators.

The method decodeStringGroup directly looks for the type of encoding performed by the encoding methods in this class. The more general method decode tries 3 algorithms in turn including CodecUtilities.decode to see if the given string has been encoded in any of 3 possible ways. It is recommended that the method decode in this class be used for general decoding of a string into a string array.

As a helpful support tool, this class contains a method tokenize that uses a StringTokenizer to break a string into a string array of tokens according to a given list of delimiters. Optionally, the trim method may be invoked to trim the tokens.

This class contains methods to build name-value string pairs of the form name=value and to decompose such pairs.

This class contains utility methods to convert between arrays of string and arrays of long or double.

Finally, this class contains a simple utility to convert a string to the equivalent HTML string with ampersand, less than, greater than, and quote encoded.

Class Strings cannot be instantiated.

Since:
2.4.0

Field Summary
static char BRACES
          The start character for encodings {s0|s1|etc}.
static char BRACES_END
          The end character for encodings {s0|s1|etc}.
static char BRACES_SEP
          The separator character for encodings {s0|s1|etc} as a string.
static char BRACKETS
          The start character for encodings [s0;s1;etc].
static char BRACKETS_END
          The end character for encodings [s0;s1;etc].
static char BRACKETS_SEP
          The separator character for encodings [s0;s1;etc] as a string.
static char PARENS
          The start character for encodings (s0,s1,etc).
static char PARENS_END
          The end character for encodings (s0,s1,etc).
static char PARENS_SEP
          The separator character for encodings (s0,s1,etc) as a string.
 
Method Summary
static String[] decode(String string)
          Attempts several algorithms to decode the given string into an array of strings and returns this array if successful and returns null if unsuccessful with all attempts.
static String[] decodeStringGroup(String string)
          Returns a String array by decoding the given string assuming it is encoded by the encoding conventions of this class.
static String[] doublesToStrings(double[] data)
          Returns an array of strings corresponding to the given array of double.
static String encode(String[] data)
          Returns the encoded String array as [s0;s1;etc] where s0, s1, etc represent the array elements.
static String encodeStringGroup(char start, String[] data)
          Returns the encoded String array as a sequence enclosed with the given start character, its matching end character, and its associated separator character.
static String encodeWithBraces(String[] data)
          Returns the encoded String array as {s0|s1|etc} where s0, s1, etc represent the array elements.
static String encodeWithBrackets(String[] data)
          Returns the encoded String array as [s0;s1;etc] where s0, s1, etc represent the array elements.
static String encodeWithParens(String[] data)
          Returns the encoded String array as (s0,s1,etc) where s0, s1, etc represent the array elements.
static int getIndexValue(String message)
          Returns the array index that was prepended to an error message thrown by stringsToLongs or stringsToDoubles.
static String getName(String string)
          Given a string of the form name=value, return the name portion.
static String[] getNames(String[] pairs)
          Given an array of name-value pairs, returns the array of names.
static String getValue(String string)
          Given a string of the form name=value, return the value portion.
static String[] getValues(String[] pairs)
          Given an array of name-value pairs, returns the array of values.
static boolean isStartEnd(String string, char start, char end)
          Returns true if the given string starts and ends with the given pair of distinct start and end characters.
static String[] longsToStrings(long[] data)
          Returns an array of strings corresponding to the given array of longs.
static ParseException makeAdjustedParseException(ParseException ex, String type, String[] names)
          Returns a new ParseException based on the given ParseException but adjusted to include information from the given type name and the given field names.
static String makeCommaList(String[] arrayList)
          Creates a comma separated list by trimming the data in the given String array and concatenating with commas.
static String makeNameValuePair(String name, String value)
          Given a pair of strings name and value, return the string name=value.
static String[] makeNameValuePairs(String[] names, String[] values)
          Given an array of names and an array of values, constructs and returns an array of pairs of the form: name=value.
static String makeSeparatorList(String[] arrayList, char separator)
          Creates a separated list by trimming the data in the given String array and concatenating with the given separator.
static String pad(String string)
          Returns the given string if it is non-null and has length at least 1; otherwise returns " ".
static String[] pad(String[] data)
          Returns a string array with all strings in the original array padded using Strings.pad.
static String removeIndexValue(String message)
          Returns the error message with its prepended index value removed.
static String[] splitCommaList(String commalist)
          Extract the non-empty strings from a comma separated list.
static String[] splitIn2(String string)
          Splits the given string into 2 parts: a prefix and a suffix and returns these 2 parts in a string array.
static String[] splitIn3(String string)
          Splits the given string into 3 parts: a prefix, a string group, and a suffix and returns these 3 parts in a string array.
static double[] stringsToDoubles(String[] data)
          Returns an array of doubles corresponding to the given array of strings.
static long[] stringsToLongs(String[] data)
          Returns an array of longs corresponding to the given array of strings.
static XComplex[] stringsToXComplexValues(String[] data)
          Returns an array of XComplex values corresponding to the given array of strings.
static String textToSafeHTML(String text)
          Returns an HTML safe string built from the given string by replacing ampersand, less than, greater than, and quote with their HTML encodings; replaces tabs with spaces assuming a tab size of 4.
static String textToSafeHTML(String text, int tabsize)
          Returns an HTML safe string built from the given string by replacing ampersand, less than, greater than, and quote with their HTML encodings; replaces tabs with spaces assuming the given tab size.
static String[] tokenize(String string, String delimiters, boolean trim)
          Returns a string array contains the tokens obtained by using a StringTokenizer to split the string according to the given delimiters; if the given trim is true then the tokens are trimmed before being returned.
static String[] trim(String[] data)
          Returns a string array with all strings in the original array trimmed using String.trim.
static String[] XComplexValuesToStrings(XComplex[] data)
          Returns an array of strings corresponding to the given array of XComplex.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BRACKETS

public static final char BRACKETS
The start character for encodings [s0;s1;etc].

See Also:
Constant Field Values

PARENS

public static final char PARENS
The start character for encodings (s0,s1,etc).

See Also:
Constant Field Values

BRACES

public static final char BRACES
The start character for encodings {s0|s1|etc}.

See Also:
Constant Field Values

BRACKETS_END

public static final char BRACKETS_END
The end character for encodings [s0;s1;etc].

See Also:
Constant Field Values

PARENS_END

public static final char PARENS_END
The end character for encodings (s0,s1,etc).

See Also:
Constant Field Values

BRACES_END

public static final char BRACES_END
The end character for encodings {s0|s1|etc}.

See Also:
Constant Field Values

BRACKETS_SEP

public static final char BRACKETS_SEP
The separator character for encodings [s0;s1;etc] as a string.

See Also:
Constant Field Values

PARENS_SEP

public static final char PARENS_SEP
The separator character for encodings (s0,s1,etc) as a string.

See Also:
Constant Field Values

BRACES_SEP

public static final char BRACES_SEP
The separator character for encodings {s0|s1|etc} as a string.

See Also:
Constant Field Values
Method Detail

encode

public static String encode(String[] data)

Returns the encoded String array as [s0;s1;etc] where s0, s1, etc represent the array elements.

Equivalent to encodeWithBrackets.

Parameters:
data - the data to encode
See Also:
encodeStringGroup(char, String[])

encodeWithBrackets

public static String encodeWithBrackets(String[] data)

Returns the encoded String array as [s0;s1;etc] where s0, s1, etc represent the array elements.

Equivalent to encode.

Parameters:
data - the data to encode
See Also:
encodeStringGroup(char, String[])

encodeWithParens

public static String encodeWithParens(String[] data)

Returns the encoded String array as (s0,s1,etc) where s0, s1, etc represent the array elements.

Parameters:
data - the data to encode
See Also:
encodeStringGroup(char, String[])

encodeWithBraces

public static String encodeWithBraces(String[] data)

Returns the encoded String array as {s0|s1|etc} where s0, s1, etc represent the array elements.

Parameters:
data - the data to encode
See Also:
encodeStringGroup(char, String[])

encodeStringGroup

public static String encodeStringGroup(char start,
                                       String[] data)

Returns the encoded String array as a sequence enclosed with the given start character, its matching end character, and its associated separator character.

Assume the array elements are s0, s1, etc. Then the elements are encoded in one of the following ways.

depending on whether the start character is [, (, or {.

If the start character is none of the three characters required then returns null to signal failure.

If the given data array is null then also returns null to signal failure.

Assuming a valid start character and a non-null data array, then for each null data entry there are no characters placed in the return string. Thus a null data entry is equivalent to a data entry that is an empty string.

Note that because the decoding algorithm uses the Java class StringTokenizer, empty string data is ignored. Thus the decoded array may have fewer items that the array that was originally encoded.

Each valid start character is paired with a corresponding separator character for the encoding.

To be robust and decodable, the encoded strings must not contain the separator character used in the encoding.

For a fully robust but more complex encoding, see the classes in the codec package especially CodecUtilities.

Parameters:
start - the start character for the encoding which must be either [, (, or {
data - the array data to encode

decode

public static String[] decode(String string)

Attempts several algorithms to decode the given string into an array of strings and returns this array if successful and returns null if unsuccessful with all attempts.

Algorithm 1 uses CodecUtilities.decode to attempt to parse the given string as a codec-encoded string.

Algorithm 2 calls splitIn2 and then calls decodeStringGroup to parse the suffix as a string group if possible.

Algorithm 3 calls splitIn3 and then calls decodeStringGroup to parse the internal string group if this string group is non-empty.

In particular, since this decode method calls the decode method of CodecUtilities, it is more general and is recommended as the preferred method for decoding a string into an array of strings.

Parameters:
string - the string to decode

decodeStringGroup

public static String[] decodeStringGroup(String string)

Returns a String array by decoding the given string assuming it is encoded by the encoding conventions of this class.

The given string should be what we call a string group, that is, it should have one of the following forms.

The string array returned contains s0 s1 ... except that empty (zero length) strings will be omitted from the array.

To avoid issues with leading and trailing whitespace, the given string is trimmed prior to processing.

Returns null if.

Parameters:
string - the string group to decode

isStartEnd

public static boolean isStartEnd(String string,
                                 char start,
                                 char end)

Returns true if the given string starts and ends with the given pair of distinct start and end characters.

Parameters:
string - the string to test
start - the start character
end - the end character

splitIn2

public static String[] splitIn2(String string)

Splits the given string into 2 parts: a prefix and a suffix and returns these 2 parts in a string array.

The prefix consists of the longest substring of the given string starting at the beginning that does not contain one of the following start characters: [, (, or {.

If the given string does not contain any of the start characters, then the prefix is the given string and the suffix is the empty string.

Otherwise, the prefix is the substring up to but not including the first start character and the suffix is the rest of the string.

This algorithm does not guarantee that the suffix is a string group but if it is then it is the largest possible string group contained in the original string.

Returns null if the given string is null. If the given string is non-null, then both strings in the return array will be non-null.

Parameters:
string - the string to split
Returns:
an array with the prefix and suffix

splitIn3

public static String[] splitIn3(String string)

Splits the given string into 3 parts: a prefix, a string group, and a suffix and returns these 3 parts in a string array.

The prefix consists of the longest substring of the given string starting at the beginning that does not contain one of the following start characters: [, (, or {.

If the given string does not contain any of the start characters, then the prefix is the given string and the other two parts are empty strings.

If a start character exists, then a search is made for the nearest matching end character that follows the start character. If such an end character is found then this defines the string group and the suffix is what is left. If no matching end character is found then the string group is empty and the suffix is the rest of the string including the unmatched start character.

With this specification, it is possible for the suffix to contain additional string groups that could be peeled off by repeated use of this method.

Returns null if the given string is null. If the given string is non-null, then all three strings in the return array will be non-null.

Parameters:
string - the string to split
Returns:
an array with the prefix, string group, and suffix

makeNameValuePair

public static String makeNameValuePair(String name,
                                       String value)

Given a pair of strings name and value, return the string name=value.

If either string is null, return null.

Parameters:
name - the name
value - the value

getName

public static String getName(String string)

Given a string of the form name=value, return the name portion.

Return null if the given string is null.

Return an empty string if the given string does not contain an equals sign.

Parameters:
string - the name-value string

getValue

public static String getValue(String string)

Given a string of the form name=value, return the value portion.

Return null if the given string is null.

Return the given string if the given string does not contain an equals sign.

Parameters:
string - the name-value string

makeNameValuePairs

public static String[] makeNameValuePairs(String[] names,
                                          String[] values)

Given an array of names and an array of values, constructs and returns an array of pairs of the form: name=value.

Returns null to signal failure if any of the following situations takes place.

Parameters:
names - the array of names
values - the array of values

getNames

public static String[] getNames(String[] pairs)

Given an array of name-value pairs, returns the array of names.

Returns null if the given array is null.

Returns null if any entry in the given array is null.

Parameters:
pairs - the array of name-value pairs

getValues

public static String[] getValues(String[] pairs)

Given an array of name-value pairs, returns the array of values.

Returns null if the given array is null.

Returns null if any entry in the given array is null.

Parameters:
pairs - the array of name-value pairs

longsToStrings

public static String[] longsToStrings(long[] data)

Returns an array of strings corresponding to the given array of longs.

Returns null if the given data is null.

Parameters:
data - the data to convert
Returns:
the converted data

doublesToStrings

public static String[] doublesToStrings(double[] data)

Returns an array of strings corresponding to the given array of double.

Returns null if the given data is null.

Parameters:
data - the data to convert
Returns:
the converted data

XComplexValuesToStrings

public static String[] XComplexValuesToStrings(XComplex[] data)

Returns an array of strings corresponding to the given array of XComplex.

Each XComplex is converted by the static method XComplex.toStringData.

Returns null if the given data is null.

Parameters:
data - the data to convert
Returns:
the converted data

stringsToLongs

public static long[] stringsToLongs(String[] data)
                             throws ParseException

Returns an array of longs corresponding to the given array of strings.

Returns null if the given data is null.

Trims the data strings prior to the numeric conversion.

In converting the i-th data item of the array to a long, the following conventions and procedures are followed.

Parameters:
data - the data to convert
Returns:
the converted data
ParseException

stringsToDoubles

public static double[] stringsToDoubles(String[] data)
                                 throws ParseException

Returns an array of doubles corresponding to the given array of strings.

Returns null if the given data is null.

Trims the data strings prior to the numeric conversion.

In converting the i-th data item of the array to a double, the following conventions and procedures are followed.

Parameters:
data - the data to convert
Returns:
the converted data
ParseException

stringsToXComplexValues

public static XComplex[] stringsToXComplexValues(String[] data)
                                          throws ParseException

Returns an array of XComplex values corresponding to the given array of strings.

Returns null if the given data is null.

Trims the data strings prior to the numeric conversion.

In converting the i-th data item of the array to an XComplex, the following conventions and procedures are followed.

Parameters:
data - the data to convert
Returns:
the converted data
ParseException

getIndexValue

public static int getIndexValue(String message)

Returns the array index that was prepended to an error message thrown by stringsToLongs or stringsToDoubles.

This is a hack required since there is no extra data field in a ParseException to hold the array index directly.

Returns 0 if the message has no prepended value.

Parameters:
message - the error message

removeIndexValue

public static String removeIndexValue(String message)

Returns the error message with its prepended index value removed.

Assumes that the original error message was created by stringsToLongs or stringsToDoubles.

This is a hack required since there is no extra data field in a ParseException to hold the array index directly.

Returns the message if the message has no prepended index value.

Parameters:
message - the error message

makeAdjustedParseException

public static ParseException makeAdjustedParseException(ParseException ex,
                                                        String type,
                                                        String[] names)

Returns a new ParseException based on the given ParseException but adjusted to include information from the given type name and the given field names.

Assumes that the given ParseException was thrown by stringsToLongs or stringsToDoubles while parsing the given type.

The type name is used to make the user aware of the specific type whose data was being parsed.

The names array is used to replace the array index in the original message with a more understandable field name.

This is a helper method for the methods fromStringData in assorted Stringable classes.

Parameters:
ex - the original ParseException
type - the type being parsed
names - the field names that replace indices

trim

public static String[] trim(String[] data)

Returns a string array with all strings in the original array trimmed using String.trim.

null data strings are returned as is.

Returns null if the given data array is null.

Parameters:
data - the data to trim

tokenize

public static String[] tokenize(String string,
                                String delimiters,
                                boolean trim)

Returns a string array contains the tokens obtained by using a StringTokenizer to split the string according to the given delimiters; if the given trim is true then the tokens are trimmed before being returned.

If the given string is null, return null.

If the given delimiters string is null or of length 0, return a string array with the given string as its only element (possibly trimmed).

Parameters:
string - the string to tokenize
delimiters - the delimiter characters
trim - whether or not to trim the tokens

splitCommaList

public static String[] splitCommaList(String commalist)

Extract the non-empty strings from a comma separated list.

Return a zero length array if the list is null or has length 0 after being trimmed.

This is a frequently used special case of the method tokenize and so is explicitly given its own name.

Parameters:
commalist - a comma separated list of strings

makeSeparatorList

public static String makeSeparatorList(String[] arrayList,
                                       char separator)

Creates a separated list by trimming the data in the given String array and concatenating with the given separator.

Parameters:
arrayList - the array of strings to concatenate
separator - the separator character

makeCommaList

public static String makeCommaList(String[] arrayList)

Creates a comma separated list by trimming the data in the given String array and concatenating with commas.

This is a frequently used special case of the method makeSeparatorList and so is explicitly given its own name.

Parameters:
arrayList - the array of strings to concatenate

pad

public static String pad(String string)

Returns the given string if it is non-null and has length at least 1; otherwise returns " ".

Parameters:
string - the string to pad to length at least 1

pad

public static String[] pad(String[] data)

Returns a string array with all strings in the original array padded using Strings.pad.

null data strings are returned as " ".

Returns null if the given data array is null.

Parameters:
data - the data to pad

textToSafeHTML

public static String textToSafeHTML(String text)

Returns an HTML safe string built from the given string by replacing ampersand, less than, greater than, and quote with their HTML encodings; replaces tabs with spaces assuming a tab size of 4.

Parameters:
text - the string to convert to HTML

textToSafeHTML

public static String textToSafeHTML(String text,
                                    int tabsize)

Returns an HTML safe string built from the given string by replacing ampersand, less than, greater than, and quote with their HTML encodings; replaces tabs with spaces assuming the given tab size.

Parameters:
text - the string to convert to HTML
tabsize - the tabsize for conversion of tabs to spaces