net.lucidviews.util.text
Class Strings

java.lang.Object
  net.lucidviews.util.text.Strings

public class Strings
extends Object

A collection of utility methods for performing operations on Strings.

Since:

1.0

Version:

$Revision: 1.7.2.1 $

Author:

Stephen Battey

Nested Class Summary

protected static class	Strings.ClassMustBeValid Helper class required for exported constant CLASS_MUST_BE_VALID, which must be unique/different to avoid confusion with any other value a client may use.
protected static class	Strings.EnumValueMustBeValid Helper class required for exported constant ENUM_VALUE_MUST_BE_VALID, which must be unique/different to avoid confusion with any other value a client may use.

Field Summary

static Boolean	BOOLEAN_MUST_BE_VALID Special default value that ensures a valid Boolean value is parsed (i.e.
static Class	CLASS_MUST_BE_VALID Special default value that ensures a valid Class is parsed (i.e.
static long	COLOR_ALPHA_MASK Bitmask for extracting the alpha component from a argb value.
static char	COLOR_HEX_LENGTH_WITHOUT_ALPHA The maximum length of a hex colour string (exlucing '#' prefix) without an alpha component.
static char	COLOR_HEX_PREFIX The character used to prefix hex colour codes.
static Color	COLOR_MUST_BE_VALID Special default value that ensures a valid Color is parsed (i.e.
static Double	DOUBLE_MUST_BE_VALID Special default value that ensures a valid floating-point value is parsed (i.e.
static File	ENSURE_FILE_EXISTS Special default value that ensures a valid File is parsed and references an existing file or a location where a new file can be created.
static File	ENSURE_FOLDER_EXISTS Special default value that ensures a valid File is parsed and references an existing folder or a location where a new folder can be created.
static File	ENSURE_PARENT_FOLDER_EXISTS Special default value that ensures a valid File is parsed and references a location within an existing folder or in a folder that can be created.
static EnumValue	ENUM_VALUE_MUST_BE_VALID Special default value that ensures a valid Enumeration value is parsed (i.e.
static File	FILE_MUST_EXIST Special default value that ensures a valid File is parsed and references a file that already exists on the file system.
static File	FOLDER_MUST_EXIST Special default value that ensures a valid File is parsed and references a folder that already exists on the file system.
static Long	LONG_MUST_BE_VALID Special default value that ensures a valid Integer value is parsed (i.e.
static Object	OBJECT_MUST_BE_VALID Special default value that ensures a valid Object is parsed (i.e.
static File	PARENT_FOLDER_MUST_EXIST Special default value that ensures a valid File is parsed and references a location within an existing folder on the file system.
static String	WHITESPACE_CHARS A string containing all the characters Java treats as whitespace.

Constructor Summary

protected

Strings() The default constructor is protected to prevent instantiation.

Method Summary

static boolean	containsAll(String string, String chars) Check if a string contains all of a given set of characters.
static boolean	containsAny(String string, String chars) Check if a string contains any of a given set of characters.
static String	firstLine(String text) Extract the first line from a text string.
static String	nextLine(String text, int fromIndex) Extract a line from a text string.
static Boolean	parseBoolean(Boolean defaultValue, String string) Parse a Boolean value from a String, returning the default value if the string was invalid.
static Boolean	parseBoolean(String string) Parse a Boolean value from a String.
static boolean	parseBoolean(String string, boolean defaultValue) Parse a boolean value from a String, returning the default value if the string was invalid.
static Boolean	parseBoolean(String string, Boolean defaultValue) Parse a Boolean value from a String, returning the default value if the string was invalid.
static Class	parseClass(Class defaultValue, String string) Parse a Java Class from a String, returning the default value if the string was invalid.
static Class	parseClass(Class defaultValue, String string, String relativeToPackage) Parse a Java Class from a String, returning the default value if the string was invalid.
static Class	parseClass(String string) Parse a Java Class from a String.
static Class	parseClass(String string, Class defaultValue) Parse a Java Class from a String, returning the default value if the string was invalid.
static Class	parseClass(String string, String relativeToPackage, Class defaultValue) Parse a Java Class from a String, returning the default value if the string was invalid.
static Color	parseColor(Color defaultValue, String string) Parse a Color from a String, returning the default value if the string was invalid.
static Color	parseColor(String string) Parse a Color from a String, returning the default value if the string was invalid.
static Color	parseColor(String string, Color defaultValue) Parse a Color from a String, returning the default value if the string was invalid.
static Double	parseDouble(Double defaultValue, String string) Parse a Double value from a String, returning the default value if the string was invalid.
static Double	parseDouble(String string) Parse a Double value from a String.
static double	parseDouble(String string, double defaultValue) Parse a Double value from a String, returning the default value if the string was invalid.
static Double	parseDouble(String string, Double defaultValue) Parse a Double value from a String, returning the default value if the string was invalid.
static EnumValue	parseEnumValue(EnumValue defaultValue, String string, Enumeration enumeration) Parse an enumeration value of the given Enumeration type from a String, returning the default value if the string was invalid.
static EnumValue	parseEnumValue(String string, Enumeration enumeration) Parse an enumeration value of the given Enumeration type from a String.
static EnumValue	parseEnumValue(String string, Enumeration enumeration, EnumValue defaultValue) Parse an enumeration value of the given Enumeration type from a String, returning the default value if the string was invalid.
static File	parseFile(File defaultValue, String string) Parse a File value from a String, returning the default value if the string was invalid.
static File	parseFile(File defaultValue, String string, File relativeToFolder) Parse a File value from a String, returning the default value if the string was invalid.
static File	parseFile(String string) Parse a File value from a String.
static File	parseFile(String string, File defaultValue) Parse a File value from a String, returning the default value if the string was invalid.
static File	parseFile(String string, File relativeToFolder, File defaultValue) Parse a File value from a String, returning the default value if the string was invalid.
static File	parseFolder(File defaultValue, String string) Parse a File value from a String, returning the default value if the string was invalid.
static File	parseFolder(File defaultValue, String string, File relativeToFolder) Parse a File value from a String, returning the default value if the string was invalid.
static File	parseFolder(String string) Parse a File value from a String.
static File	parseFolder(String string, File defaultValue) Parse a File value from a String, returning the default value if the string was invalid.
static File	parseFolder(String string, File relativeToFolder, File defaultValue) Parse a File value from a String, returning the default value if the string was invalid.
static int[]	parseInts(String string) Parse a list of integer values from a given string.
static int[]	parseInts(String string, int minValue, int maxValue) Parse a list of integer values from a given string.
static int[]	parseInts(String string, String delimiters) Parse a list of integer values from a given string.
static int[]	parseInts(String string, String delimiters, int minValue, int maxValue) Parse a list of integer values from a given string.
static Long	parseLong(Long defaultValue, String string) Parse a Long value from a String, returning the default value if the string was invalid.
static Long	parseLong(String string) Parse a Long value from a String.
static long	parseLong(String string, long defaultValue) Parse a Long value from a String, returning the default value if the string was invalid.
static Long	parseLong(String string, Long defaultValue) Parse a Long value from a String, returning the default value if the string was invalid.
static Object	parseObject(Object defaultValue, String string, Collection validObjects) Parse an object from a String, returning the default value if the string was invalid.
static Object	parseObject(String string, Collection validObjects) Parse an object from a String.
static Object	parseObject(String string, Collection validObjects, Object defaultValue) Parse an object from a String, returning the default value if the string was invalid.
static String	rightAlign(String string, int length) Right-align a text string, padding the left portion of the string with spaces and truncating the string if necessary.
static String	rightAlign(String string, int length, boolean truncate) Right-align a text string, padding the left portion of the string with spaces.
static String	rightAlign(String string, int length, char pad) Right-align a text string, padding the left portion of the string with the specified padding character and truncating the string if necessary.
static String	rightAlign(String string, int length, char pad, boolean truncate) Right-align a text string, padding the left portion of the string with the specified padding character.
static String	serializeColor(Color value) Serialize a Color as a String.

Methods inherited from class java.lang.Object

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

Field Detail

BOOLEAN_MUST_BE_VALID

public static final Boolean BOOLEAN_MUST_BE_VALID

Special default value that ensures a valid Boolean value is parsed (i.e. to be used when no default value is applicable).

See Also:

parseBoolean(Boolean,String)

LONG_MUST_BE_VALID

public static final Long LONG_MUST_BE_VALID

Special default value that ensures a valid Integer value is parsed (i.e. to be used when no default value is applicable).

See Also:

parseLong(Long, String)

DOUBLE_MUST_BE_VALID

public static final Double DOUBLE_MUST_BE_VALID

Special default value that ensures a valid floating-point value is parsed (i.e. to be used when no default value is applicable).

See Also:

parseDouble(Double, String)

FILE_MUST_EXIST

public static final File FILE_MUST_EXIST

Special default value that ensures a valid File is parsed and references a file that already exists on the file system.

See Also:

parseFile(File, String)

ENSURE_FILE_EXISTS

public static final File ENSURE_FILE_EXISTS

Special default value that ensures a valid File is parsed and references an existing file or a location where a new file can be created.

See Also:

parseFile(File, String)

FOLDER_MUST_EXIST

public static final File FOLDER_MUST_EXIST

Special default value that ensures a valid File is parsed and references a folder that already exists on the file system.

See Also:

parseFolder(File, String)

ENSURE_FOLDER_EXISTS

public static final File ENSURE_FOLDER_EXISTS

Special default value that ensures a valid File is parsed and references an existing folder or a location where a new folder can be created.

See Also:

parseFolder(File, String)

PARENT_FOLDER_MUST_EXIST

public static final File PARENT_FOLDER_MUST_EXIST

Special default value that ensures a valid File is parsed and references a location within an existing folder on the file system.

See Also:

parseFile(File, String), parseFolder(File, String)

ENSURE_PARENT_FOLDER_EXISTS

public static final File ENSURE_PARENT_FOLDER_EXISTS

Special default value that ensures a valid File is parsed and references a location within an existing folder or in a folder that can be created.

See Also:

parseFile(File, String), parseFolder(File, String)

CLASS_MUST_BE_VALID

public static final Class CLASS_MUST_BE_VALID

Special default value that ensures a valid Class is parsed (i.e. to be used when no default value is applicable).

See Also:

parseClass(Class, String)

ENUM_VALUE_MUST_BE_VALID

public static final EnumValue ENUM_VALUE_MUST_BE_VALID

Special default value that ensures a valid Enumeration value is parsed (i.e. to be used when no default value is applicable).

See Also:

parseEnumValue(EnumValue, String, Enumeration)

OBJECT_MUST_BE_VALID

public static final Object OBJECT_MUST_BE_VALID

Special default value that ensures a valid Object is parsed (i.e. to be used when no default value is applicable).

See Also:

parseObject(Object, String, Collection)

COLOR_MUST_BE_VALID

public static final Color COLOR_MUST_BE_VALID

Special default value that ensures a valid Color is parsed (i.e. to be used when no default value is applicable).

See Also:

parseColor(Color, String)

COLOR_ALPHA_MASK

public static final long COLOR_ALPHA_MASK

Bitmask for extracting the alpha component from a argb value.

See Also:

Constant Field Values

COLOR_HEX_PREFIX

public static final char COLOR_HEX_PREFIX

The character used to prefix hex colour codes.

See Also:

Constant Field Values

COLOR_HEX_LENGTH_WITHOUT_ALPHA

public static final char COLOR_HEX_LENGTH_WITHOUT_ALPHA

The maximum length of a hex colour string (exlucing '#' prefix) without an alpha component.

See Also:

Constant Field Values

WHITESPACE_CHARS

public static final String WHITESPACE_CHARS

A string containing all the characters Java treats as whitespace.

See Also:

Constant Field Values

Constructor Detail

Strings

protected Strings()

The default constructor is protected to prevent instantiation.

Method Detail

parseBoolean

public static Boolean parseBoolean(String string)
                            throws ParseValueException

Parse a Boolean value from a String.
If the string is invalid then an exception will be thrown.
The return value is guaranteed to be non-null. Thus, the following line of code will never cause a NullPointerException:
boolean value = Strings.parseBoolean( string ).booleanValue();
Although it may throw a ParseValueException if the string is invalid.

Parameters:

string - the String containing the Boolean value

Returns:

the Boolean value represented by the string

Throws:

ParseValueException - if the String value could not be parsed as a valid Boolean value

parseBoolean

public static Boolean parseBoolean(Boolean defaultValue,
                                   String string)
                            throws ParseValueException

Parse a Boolean value from a String, returning the default value if the string was invalid.
If the string is invalid and the defaultValue is set to the constant Strings.BOOLEAN_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed to be non-null, provided the defaultValue is not null. Thus, none of the following lines of code will cause a NullPointerException:
Boolean value = Strings.parseBoolean( default, string );
boolean value = Strings.parseBoolean( default, string ).booleanValue();
boolean value = Strings.parseBoolean( Strings.BOOLEAN_MUST_BE_VALID, string ).booleanValue();
Although the last line may throw a ParseValueException if the string is invalid.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String containing the Boolean value

Returns:

the Boolean value represented by the string, or the default value if the string is invalid

Throws:

ParseValueException - if the String value must be valid but could not be parsed as a valid Boolean value

parseBoolean

public static Boolean parseBoolean(String string,
                                   Boolean defaultValue)

Parse a Boolean value from a String, returning the default value if the string was invalid.
The return value is guaranteed to be non-null, provided the defaultValue is not null. Thus, none of the following lines of code will cause a NullPointerException:
Boolean value = Strings.parseBoolean( string, default );
boolean value = Strings.parseBoolean( string, default ).booleanValue();

Parameters:

string - the String containing the Boolean value

defaultValue - the default value to be used if the string is not valid

Returns:

the Boolean value represented by the string, or the default value if the string is invalid

parseBoolean

public static boolean parseBoolean(String string,
                                   boolean defaultValue)

Parse a boolean value from a String, returning the default value if the string was invalid.

Parameters:

string - the String containing the Boolean value

defaultValue - the default value to be used if the string is not valid

Returns:

the boolean value represented by the string, or the default value if the string is invalid

parseLong

public static Long parseLong(String string)
                      throws ParseValueException

Parse a Long value from a String.
If the string is invalid then an exception will be thrown.
The return value is guaranteed to be non-null. Thus, the following line of code will never cause a NullPointerException:
long value = Strings.parseLong( string ).longValue();
int value = Strings.parseLong( string ).intValue();
Although they may throw a ParseValueException if the string is invalid.

Parameters:

string - the String containing the numeric, integer value

Returns:

the Long value represented by the string

Throws:

ParseValueException - if the String could not be parsed as a valid Long value

parseLong

public static Long parseLong(Long defaultValue,
                             String string)
                      throws ParseValueException

Parse a Long value from a String, returning the default value if the string was invalid.
If the string is invalid and the defaultValue is set to the constant Strings.LONG_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed to be non-null, provided the defaultValue is not null. Thus, none of the following lines of code will cause a NullPointerException:
Long value = Strings.parseLong( default, string );
long value = Strings.parseLong( default, string ).longValue();
int value = Strings.parseLong( default, string ).intValue();
int value = Strings.parseLong( Strings.LONG_MUST_BE_VALID, string ).intValue();
Although the last line may throw a ParseValueException if the string is invalid.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String containing the numeric, integer value

Returns:

the Long value represented by the string, or the default value if the string is invalid

Throws:

ParseValueException - if the String value must be valid but could not be parsed as a valid Long value

parseLong

public static Long parseLong(String string,
                             Long defaultValue)

Parse a Long value from a String, returning the default value if the string was invalid.
If the string is invalid and the defaultValue is set to the constant Strings.LONG_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed to be non-null, provided the defaultValue is not null. Thus, none of the following lines of code will cause a NullPointerException:
Long value = Strings.parseLong( string, default );
long value = Strings.parseLong( string, default ).longValue();
int value = Strings.parseLong( string, default ).intValue();

Parameters:

string - the String containing the numeric, integer value

defaultValue - the default value to be used if the string is not valid

Returns:

the Long value represented by the string, or the default value if the string is invalid

parseLong

public static long parseLong(String string,
                             long defaultValue)

Parse a Long value from a String, returning the default value if the string was invalid.

Parameters:

string - the String containing the numeric integer value

defaultValue - the default value to be used if the string is not valid

Returns:

the long value represented by the string, or the default value if the string is invalid

parseDouble

public static Double parseDouble(String string)
                          throws ParseValueException

Parse a Double value from a String.
If the string is invalid then an exception will be thrown.
The return value is guaranteed to be non-null. Thus, the following line of code will never cause a NullPointerException:
double value = Strings.parseDouble( string ).doubleValue();
float value = Strings.parseDouble( string ).floatValue();
Although they may throw a ParseValueException if the string is invalid.

Parameters:

string - the String containing the numeric, floating-point value

Returns:

the Double value represented by the string

Throws:

ParseValueException - if the String could not be parsed as a valid Double value

parseDouble

public static Double parseDouble(Double defaultValue,
                                 String string)
                          throws ParseValueException

Parse a Double value from a String, returning the default value if the string was invalid.
If the string is invalid and the defaultValue is set to the constant Strings.DOUBLE_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed to be non-null, provided the defaultValue is not null. Thus, none of the following lines of code will cause a NullPointerException:
Double value = Strings.parseDouble( default, string );
double value = Strings.parseDouble( default, string, ).doubleValue();
float value = Strings.parseDouble( default, string ).floatValue();
float value = Strings.parseDouble( Strings.DOUBLE_MUST_BE_VALID, string ).floatValue();
Although the last line may throw a ParseValueException if the string is invalid.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String containing the numeric, floating-point value

Returns:

the Double value represented by the string, or the default value if the string is invalid

Throws:

ParseValueException - if the String value must be valid but could not be parsed as a valid Double value

parseDouble

public static Double parseDouble(String string,
                                 Double defaultValue)

Parse a Double value from a String, returning the default value if the string was invalid.
The return value is guaranteed to be non-null, provided the defaultValue is not null. Thus, none of the following lines of code will cause a NullPointerException:
Double value = Strings.parseDouble( string, default );
double value = Strings.parseDouble( string, default ).doubleValue();
float value = Strings.parseDouble( string, default ).floatValue();

Parameters:

string - the String containing the numeric, floating-point value

defaultValue - the default value to be used if the string is not valid

Returns:

the Double value represented by the string, or the default value if the string is invalid

parseDouble

public static double parseDouble(String string,
                                 double defaultValue)

Parse a Double value from a String, returning the default value if the string was invalid.

Parameters:

string - the String containing the numeric, floating-point value

defaultValue - the default value to be used if the string is not valid

Returns:

the Double value represented by the string, or the default value if the string is invalid

parseFile

public static File parseFile(String string)
                      throws ParseValueException

Parse a File value from a String.
If the path does not reference a file then an exception will be thrown.
The return value is guaranteed to be non-null.

Parameters:

string - the String value containing the file path

Returns:

the File at the system path specified by the string

Throws:

ParseValueException - if a File could not be found at the location specified in the String

parseFile

public static File parseFile(File defaultValue,
                             String string,
                             File relativeToFolder)
                      throws ParseValueException

Parse a File value from a String, returning the default value if the string was invalid.
The input string should specify the path to a file, either absolute or relative to the given folder.
If the path does not reference a file and the defaultValue is set to the constant Strings.FILE_MUST_EXIST, an exception will be thrown.
If the path does not reference a file and the defaultValue is set to the constant Strings.ENSURE_FILE_EXISTS, a new, empty file will be created and a reference to that new file returned.
If the path references a file in a folder that does not exist and the defaultValue is set to the constant Strings.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the path references a file in a folder that does not exist and the defaultValue is set to the constant Strings.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant file (in a existant folder) will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String value containing the file path

relativeToFolder - the base location to use if the file path defined by the string is relative, rather than an absolute path

Returns:

the File referenced by the path in the string, or the default value if the string is invalid

Throws:

ParseValueException - if the path specified by the string value must be valid but could not be parsed as a valid File

parseFile

public static File parseFile(File defaultValue,
                             String string)
                      throws ParseValueException

Parse a File value from a String, returning the default value if the string was invalid.
The input string should specify the path to a file, either absolute or relative to the current working folder.
If the path does not reference a file and the defaultValue is set to the constant Strings.FILE_MUST_EXIST, an exception will be thrown.
If the path does not reference a file and the defaultValue is set to the constant Strings.ENSURE_FILE_EXISTS, a new, empty file will be created and a reference to that new file returned.
If the path references a file in a folder that does not exist and the defaultValue is set to the constant Strings.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the path references a file in a folder that does not exist and the defaultValue is set to the constant Strings.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant file (in a existant folder) will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String value containing the file path

Returns:

the File referenced by the path in the string, or the default value if the string is invalid

Throws:

ParseValueException - if the path specified by the string value must be valid but could not be parsed as a valid File

parseFile

public static File parseFile(String string,
                             File relativeToFolder,
                             File defaultValue)

Parse a File value from a String, returning the default value if the string was invalid.
The input string should specify the path to a file, either absolute or relative to the given folder.
If the path does not reference a file and the defaultValue is set to the constant Strings.ENSURE_FILE_EXISTS, a new, empty file will be created and a reference to that new file returned. Otherwise, if the path does not reference a file, the default value will be returned.
If the path references a file in a folder that does not exist and the defaultValue is set to the constant Strings.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant file (in a existant folder) will be returned. Otherwise, if the path references a file in a folder that does not exist, the default value will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

string - the String value containing the file path

relativeToFolder - the base location to use if the file path defined by the string is relative, rather than an absolute path

defaultValue - the default value to be used if the string is not valid

Returns:

the File referenced by the path in the string, or the default value if the string is invalid

parseFile

public static File parseFile(String string,
                             File defaultValue)

Parse a File value from a String, returning the default value if the string was invalid.
The input string should specify the path to a file, either absolute or relative to the current working folder.
If the path does not reference a file and the defaultValue is set to the constant Strings.ENSURE_FILE_EXISTS, a new, empty file will be created and a reference to that new file returned. Otherwise, if the path does not reference a file, the default value will be returned.
If the path references a file in a folder that does not exist and the defaultValue is set to the constant Strings.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant file (in a existant folder) will be returned. Otherwise, if the path references a file in a folder that does not exist, the default value will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

string - the String value containing the file path

defaultValue - the default value to be used if the string is not valid

Returns:

a File referencing the location of the path in the string, or the default value if the string is invalid

parseFolder

public static File parseFolder(String string)
                        throws ParseValueException

Parse a File value from a String.
If the path does not reference a folder then an exception will be thrown.
The return value is guaranteed to be non-null.

Parameters:

string - the String value containing the folder path

Returns:

the File at the system path specified by the string

Throws:

ParseValueException - if a File could not be found at the location specified in the String

parseFolder

public static File parseFolder(File defaultValue,
                               String string,
                               File relativeToFolder)
                        throws ParseValueException

Parse a File value from a String, returning the default value if the string was invalid.
The input string should specify the path to a folder, either absolute or relative to the given folder.
If the path does not reference a folder and the defaultValue is set to the constant Strings.FOLDER_MUST_EXIST, an exception will be thrown.
If the path does not reference a folder and the defaultValue is set to the constant Strings.ENSURE_FOLDER_EXISTS, the folder will be created and a reference to that new folder returned.
If the path references a sub-folder of a folder that does not exist and the defaultValue is set to the constant Strings.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the path references a sub-folder of a folder that does not exist and the defaultValue is set to the constant Strings.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant folder (in a existant folder) will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String value containing the folder path

relativeToFolder - the base location to use if the folder path defined by the string is relative, rather than an absolute path

Returns:

a File referencing the location of the path in the string, or the default value if the string is invalid

Throws:

ParseValueException - if the path specified by the string value must be valid but could not be parsed as a valid File

parseFolder

public static File parseFolder(File defaultValue,
                               String string)
                        throws ParseValueException

Parse a File value from a String, returning the default value if the string was invalid.
The input string should specify the path to a folder, either absolute or relative to the current working folder.
If the path does not reference a folder and the defaultValue is set to the constant Strings.FOLDER_MUST_EXIST, an exception will be thrown.
If the path does not reference a folder and the defaultValue is set to the constant Strings.ENSURE_FOLDER_EXISTS, the folder will be created and a reference to that new folder returned.
If the path references a sub-folder of a folder that does not exist and the defaultValue is set to the constant Strings.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the path references a sub-folder of a folder that does not exist and the defaultValue is set to the constant Strings.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant folder (in a existant folder) will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String value containing the folder path

Returns:

a File referencing the location of the path in the string, or the default value if the string is invalid

Throws:

ParseValueException - if the path specified by the string value must be valid but could not be parsed as a valid File

parseFolder

public static File parseFolder(String string,
                               File relativeToFolder,
                               File defaultValue)

Parse a File value from a String, returning the default value if the string was invalid.
The input string should specify the path to a folder, either absolute or relative to the given folder.
If the path does not reference a folder and the defaultValue is set to the constant Strings.ENSURE_FOLDER_EXISTS, the folder will be created and a reference to that new folder returned. Otherwise, if the path does not reference a folder, the default value will be returned.
If the path references a sub-folder of a folder that does not exist and the defaultValue is set to the constant Strings.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant folder (in a existant folder) will be returned. Otherwise, if the path references a sub-folder of a folder that does not exist, the default value will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

string - the String value containing the folder path

relativeToFolder - the base location to use if the folder path defined by the string is relative, rather than an absolute path

defaultValue - the default value to be used if the string is not valid

Returns:

a File referencing the location of the path in the string, or the default value if the string is invalid

parseFolder

public static File parseFolder(String string,
                               File defaultValue)

Parse a File value from a String, returning the default value if the string was invalid.
The input string should specify the path to a folder, either absolute or relative to the current working folder.
If the path does not reference a folder and the defaultValue is set to the constant Strings.ENSURE_FOLDER_EXISTS, the folder will be created and a reference to that new folder returned. Otherwise, if the path does not reference a folder, then the default value will be returned.
If the path references a sub-folder of a folder that does not exist and the defaultValue is set to the constant Strings.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant folder (in a existant folder) will be returned. Otherwise, if the path references a sub-folder of a folder that does not exist, the default value will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String value containing the folder path

Returns:

a File referencing the location of the path in the string, or the default value if the string is invalid

parseClass

public static Class parseClass(String string)
                        throws ParseValueException

Parse a Java Class from a String.
The input string should specify the full, absolute name of a class.
If the class name does not reference a class then an exception will be thrown.
The return value is guaranteed to be non-null.

Parameters:

string - the String value containing the class name

Returns:

a Java Class found at the given location defined in the string

Throws:

ParseValueException - if the path specified by the string value could not be parsed as a valid Class

parseClass

public static Class parseClass(Class defaultValue,
                               String string,
                               String relativeToPackage)
                        throws ParseValueException

Parse a Java Class from a String, returning the default value if the string was invalid.
The input string should specify the name of a class, with the package path, either absolute or relative to the given package.
If the class name does not reference a class and the defaultValue is set to the constant Strings.CLASS_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String value containing the class name

relativeToPackage - the base location to use if the class name defined by the string is not an absolute path

Returns:

a Java Class found at the given location defined in the string, or the default value if the string is invalid

Throws:

ParseValueException - if the path specified by the string value must be valid but could not be parsed as a valid Class

parseClass

public static Class parseClass(Class defaultValue,
                               String string)
                        throws ParseValueException

Parse a Java Class from a String, returning the default value if the string was invalid.
The input string should specify the full, absolute name of a class.
If the class name does not reference a class and the defaultValue is set to the constant Strings.CLASS_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String value containing the class name

Returns:

a Java Class found at the given location defined in the string, or the default value if the string is invalid

Throws:

ParseValueException - if the path specified by the string value must be valid but could not be parsed as a valid Class

parseClass

public static Class parseClass(String string,
                               String relativeToPackage,
                               Class defaultValue)

Parse a Java Class from a String, returning the default value if the string was invalid.
The input string should specify the name of a class, with the package path, either absolute or relative to the given package.
If the class name does not reference a class then the default value will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

string - the String value containing the class name

relativeToPackage - the base location to use if the class name defined by the string is not an absolute path

defaultValue - the default value to be used if the string is not valid

Returns:

a Java Class found at the given location defined in the string, or the default value if the string is invalid

parseClass

public static Class parseClass(String string,
                               Class defaultValue)

Parse a Java Class from a String, returning the default value if the string was invalid.
The input string should specify the full, absolute name of a class.
If the class name does not reference a class then the default value will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

string - the String value containing the class name

defaultValue - the default value to be used if the string is not valid

Returns:

a Java Class found at the given location defined in the string, or the default value if the string is invalid

parseEnumValue

public static EnumValue parseEnumValue(String string,
                                       Enumeration enumeration)
                                throws ParseValueException

Parse an enumeration value of the given Enumeration type from a String.
The input string should specify one of the values in the enumeration.
If the string is not valid then an exception will be thrown.
The return value is guaranteed to be non-null.

Parameters:

string - the String value containing the enum value

enumeration - the enumeration type

Returns:

the EnumValue referenced by the string

Throws:

ParseValueException - if the string could not be parsed as a valid EnumValue

parseEnumValue

public static EnumValue parseEnumValue(EnumValue defaultValue,
                                       String string,
                                       Enumeration enumeration)
                                throws ParseValueException

Parse an enumeration value of the given Enumeration type from a String, returning the default value if the string was invalid.
The input string should specify one of the values in the enumeration.
If the string is not valid and the defaultValue is set to the constant Strings.ENUM_VALUE_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String value containing the enum value

enumeration - the enumeration type

Returns:

the EnumValue referenced by the string, or the default value if the string is invalid

Throws:

ParseValueException - if the string must reference an enumeration value but could not be parsed as a valid EnumValue

parseEnumValue

public static EnumValue parseEnumValue(String string,
                                       Enumeration enumeration,
                                       EnumValue defaultValue)

Parse an enumeration value of the given Enumeration type from a String, returning the default value if the string was invalid.
The input string should specify one of the values in the enumeration.
If the string is not valid then the default value will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

string - the String value containing the enum value

enumeration - the enumeration type

defaultValue - the default value to be used if the string is not valid

Returns:

the EnumValue referenced by the string, or the default value if the string is invalid

parseObject

public static Object parseObject(String string,
                                 Collection validObjects)
                          throws ParseValueException

Parse an object from a String.
The input string should relate to one of the objects in the a collection of accepted values.
If the string is not valid then an exception will be thrown.
The return value is guaranteed to be non-null.

Parameters:

string - the String value

validObjects - a collection of acceptable objects

Returns:

one of the Objects from the validValues collection, referenced by the string

Throws:

ParseValueException - if the string could not be parsed as a valid Object

parseObject

public static Object parseObject(Object defaultValue,
                                 String string,
                                 Collection validObjects)
                          throws ParseValueException

Parse an object from a String, returning the default value if the string was invalid.
The input string should relate to one of the objects in the a collection of accepted values.
If the string is not valid and the defaultValue is set to the constant Strings.OBJECT_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

defaultValue - the default value to be used if the string is not valid

string - the String value

validObjects - a collection of acceptable objects

Returns:

one of the Objects from the validValues collection, referenced by the string, or the default value if the string is invalid

Throws:

ParseValueException - if the string must reference one of the valid values but could not be parsed as a valid Object

parseObject

public static Object parseObject(String string,
                                 Collection validObjects,
                                 Object defaultValue)

Parse an object from a String, returning the default value if the string was invalid.
The input string should relate to one of the objects in the a collection of accepted values.
If the string is not valid, the default value will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

string - the String value

validObjects - a collection of acceptable objects

defaultValue - the default value to be used if the string is not valid

Returns:

one of the Objects from the validValues collection, referenced by the string, or the default value if the string is invalid

parseColor

public static Color parseColor(String string)
                        throws ParseValueException

Parse a Color from a String, returning the default value if the string was invalid.

The input string should specify a colour in either:
• decimal format: "[AAA] RRR GGG BBB" where AAA, RRR, GGG and BBB are 16-bit decimal values (0-255) for the alpha, red, green and blue components of the colour (alpha optional) each separated by one or more whitespace characters
• hexadecimal format: "#[AA]RRGGBB" where AA, RR, GG and BB are 16-bit hex values for the alpha, red, green and blue components of the colour (alpha optional)
• equivalent decimal value: a single decimal value that equates to a hexadecimal value in "#[AA]RRGGBB" format

If the string does not conform to this format then an exception will be thrown.
The return value is guaranteed to be non-null.

Parameters:

string - the String value containing the color specification

Returns:

a Color object for the color specified by the string

Throws:

ParseValueException - if the string does not conform to the required format

parseColor

public static Color parseColor(Color defaultValue,
                               String string)
                        throws ParseValueException

Parse a Color from a String, returning the default value if the string was invalid.

The input string should specify a colour in either:
• decimal format: "[AAA] RRR GGG BBB" where AAA, RRR, GGG and BBB are 16-bit decimal values (0-255) for the alpha, red, green and blue components of the colour (alpha optional) each separated by one or more whitespace characters
• hexadecimal format: "#[AA]RRGGBB" where AA, RR, GG and BB are 16-bit hex values for the alpha, red, green and blue components of the colour (alpha optional)
• equivalent decimal value: a single decimal value that equates to a hexadecimal value in "#[AA]RRGGBB" format

If the string does not conform to this format and the defaultValue is set to the constant Strings.COLOR_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

string - the String value containing the color specification

defaultValue - the default value to be used if the string does not specify a color

Returns:

a Color object for the color specified by the string, or the default value if the string is invalid

Throws:

ParseValueException - if the color specified by the string value must be valid but the string does not conform to the required format

parseColor

public static Color parseColor(String string,
                               Color defaultValue)

Parse a Color from a String, returning the default value if the string was invalid.

The input string should specify a colour in either:
• decimal format: "[AAA] RRR GGG BBB" where AAA, RRR, GGG and BBB are 16-bit decimal values (0-255) for the alpha, red, green and blue components of the colour (alpha optional) each separated by one or more whitespace characters
• hexadecimal format: "#[AA]RRGGBB" where AA, RR, GG and BB are 16-bit hex values for the alpha, red, green and blue components of the colour (alpha optional)
• equivalent decimal value: a single decimal value that equates to a hexadecimal value in "#[AA]RRGGBB" format

If the string does not conform to this format then the default value will be returned.
The return value is guaranteed to be non-null, provided the defaultValue is not null.

Parameters:

string - the String value containing the color specification

defaultValue - the default value to be used if the string does not specify a color

Returns:

a Color object for the color specified by the string, or the default value if the string is invalid

serializeColor

public static String serializeColor(Color value)

Serialize a Color as a String.
The colour components are encoded into a hex string in the following format: #[AA]RRGGBB (alpha, red, green, blue).

Parameters:

value - the Color value

Returns:

a String representing the given colour

parseInts

public static final int[] parseInts(String string)
                             throws ParseValueException

Parse a list of integer values from a given string.
Each value will be separated by one or more whitespace characters.
The string must only contain numeric values. Any text will cause a parse exception.

Parameters:

string - the string to be parsed

Returns:

an array of integer values parsed from the string

Throws:

ParseValueException - if any value is outside the specified range or the string contains any non-numeric text

parseInts

public static final int[] parseInts(String string,
                                    String delimiters)
                             throws ParseValueException

Parse a list of integer values from a given string.
Each value will be separated by one or more of the characters in the delimiters string.
The string must only contain numeric values. Any text will cause a parse exception.

Parameters:

string - the string to be parsed

delimiters - a list of characters, any of which may separate the integer values in the input string

Returns:

an array of integer values parsed from the string

Throws:

ParseValueException - if any value is outside the specified range or the string contains any non-numeric text

parseInts

public static final int[] parseInts(String string,
                                    int minValue,
                                    int maxValue)
                             throws ParseValueException

Parse a list of integer values from a given string.
Each value will be separated by one or more whitespace characters.
Each integer value must be within the specified range, otherwise an exception will be thrown.
The string must only contain numeric values. Any text will cause a parse exception.

Parameters:

string - the string to be parsed

minValue - the minimum value for each individual number

maxValue - the maximum value for each individual number

Returns:

an array of integer values parsed from the string

Throws:

ParseValueException - if any value is outside the specified range or the string contains any non-numeric text

parseInts

public static final int[] parseInts(String string,
                                    String delimiters,
                                    int minValue,
                                    int maxValue)
                             throws ParseValueException

Parse a list of integer values from a given string.
Each value will be separated by one or more of the characters in the delimiters string.
Each integer value must be within the specified range, otherwise an exception will be thrown.
The string must only contain numeric values. Any text will cause a parse exception.

Parameters:

string - the string to be parsed

delimiters - a list of characters, any of which may separate the integer values in the input string

minValue - the minimum value for each individual number

maxValue - the maximum value for each individual number

Returns:

an array of integer values parsed from the string

Throws:

ParseValueException - if any value is outside the specified range or the string contains any non-numeric text

rightAlign

public static String rightAlign(String string,
                                int length,
                                char pad,
                                boolean truncate)

Right-align a text string, padding the left portion of the string with the specified padding character.

Parameters:

string - the original piece of text

length - the length of the resultant string

pad - the character to be used to pad the string to the desired length

truncate - set to true if the original string should be truncated to the desired length

Returns:

the padded string

rightAlign

public static String rightAlign(String string,
                                int length,
                                boolean truncate)

Right-align a text string, padding the left portion of the string with spaces.

Parameters:

string - the original piece of text

length - the length of the resultant string

truncate - set to true if the original string should be truncated to the desired length

Returns:

the padded string

rightAlign

public static String rightAlign(String string,
                                int length,
                                char pad)

Right-align a text string, padding the left portion of the string with the specified padding character and truncating the string if necessary.

Parameters:

string - the original piece of text

length - the length of the resultant string

pad - the character to be used to pad the string to the desired length

Returns:

the padded string

rightAlign

public static String rightAlign(String string,
                                int length)

Right-align a text string, padding the left portion of the string with spaces and truncating the string if necessary.

Parameters:

string - the original piece of text

length - the length of the resultant string

Returns:

the padded string

containsAny

public static boolean containsAny(String string,
                                  String chars)

Check if a string contains any of a given set of characters.
This method will look for each of the characters in turn. Thus, for optimisation you may want to order the characters in the chars string such that the characters more likely to match appear towards the start.

Parameters:

string - the string to test

chars - the characters to look for

Returns:

true if the string contains any of the characters

containsAll

public static boolean containsAll(String string,
                                  String chars)

Check if a string contains all of a given set of characters.
This method will look for each of the characters in turn. Thus, for optimisation you may want to order the characters in the chars string such that the characters least likely to match appear towards the start.

Parameters:

string - the string to test

chars - the characters to look for

Returns:

true if the string contains all of the characters

firstLine

public static String firstLine(String text)

Extract the first line from a text string.
The line will be terminated by a new-line or form-feed character - or the end of the string.

Parameters:

text - the text to be sampled

Returns:

the first line in the text string

Since:

1.3

nextLine

public static String nextLine(String text,
                              int fromIndex)

Extract a line from a text string.
The line will begin at the specified index and be terminated by a new-line or form-feed character - or the end of the string.

Parameters:

text - the text to be sampled

fromIndex - the index of the start of the line within the text string

Returns:

the next line in the text string

Since:

1.3