org.josef.util

Class CString

java.lang.Object

org.josef.util.CString

@Status(stage=PRODUCTION,
        unitTests=PARTIAL)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
public final class CString
extends Object

Collection of String methods.

Version:

2.0 $Revision: 6298 $

Author:

Kees Schotanus

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CString.StringLengthComparator A generic String comparator that compares two Strings based upon their length.

Method Summary

Modifier and Type	Method and Description
static String	alignLeft(String input, int length, char pad) Left aligns the supplied input String in a String with a length equal to the supplied length.
static String	alignRight(String input, int length, char pad) Right aligns the supplied input String in a String with a length equal to the supplied length.
static String	arrayToPlainCsv(Object... values) Converts the supplied array of values to a string of comma separated values.
static void	checkMatchingCharacters(String input, char opening, char closing) Checks that the supplied input has matching opening and closing characters, where opening and closing characters may not be nested.
static int	count(String source, String find) Counts the number of occurrences of the supplied string to find in the supplied source string.
static String	escapeControlCharacters(String input) Replaces control characters in the range 00-1F with escape characters.
static String	findMatch(String inputText, String regularExpression) Finds the text within the supplied inputText that matches the supplied regularExpression.
static String	getEscapedControlCharacter(int ordinal) Gets the escape sequence for the control character with the supplied ordinal.
static String	getRight(String string, int length) Gets the supplied length number of characters from the right of the supplied string.
static boolean	isAlphabetic(String input) Determines whether the supplied input string consists of alphabetic characters (letters) only.
static boolean	isAlphaNumeric(String input) Determines whether the supplied input String consists of alphabetic letters and numeric characters (digits) only.
static boolean	isHexaDecimal(String input) Determines whether the supplied input String consists of hexadecimal characters only.
static boolean	isNotEmpty(String input) Determines whether the supplied input string is not empty.
static boolean	isNullOrEmpty(String input) Determines whether the supplied input String is null or empty.
static boolean	isNumeric(String input) Determines whether the supplied input string consists of numeric characters (digits) only.
static boolean	isWhiteSpace(String input) Determines whether the supplied input String consists of whitespace characters only.
static <T> String	iterableToString(Iterable<T> iterable) Creates a String representation of the supplied iterable.
static String	removeEndOfLineCharacters(String input) Removes all the end of line characters from the supplied input String.
static String	removePrefixCharacters(String input, char prefix) Removes all the supplied prefix characters from the supplied input.
static String	repeat(String input, int repeat) Creates a String that consists of a repetition, determined by the supplied repeat count, of the supplied input String.
static String	replace(String input, String oldString, String newString) Replaces all occurrences of oldString with newString in the supplied input String.
static String[]	tokenize(String input) Tokenizes a String.
static String[]	tokenize(String input, String delimiters) Tokenizes a String.
static String	trim(Trim trim, String input) Trims whitespace from the supplied input.
static String	trimAll(String input) Trims all whitespace characters from the supplied input, no matter where they are located.
static String	trimLeft(String input) Trims whitespace from the left of the supplied input.
static String	trimRight(String input) Trims whitespace from the right of the supplied input.

Methods inherited from class java.lang.Object

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

Method Detail

tokenize

public static String[] tokenize(String input)

Tokenizes a String.
That is to say that the supplied input String is split into tokens. This method assumes the following delimiter set: space, tab, newline, carriage-return and the form-feed character.

Parameters:

input - Input string to split into tokens.

Returns:

Array where each element contains a token.

See Also:

StringTokenizer.StringTokenizer(String)

tokenize

public static String[] tokenize(String input,
                                String delimiters)

Tokenizes a String.
That is to say that the supplied input String is split into tokens.

Parameters:

input - Input string to split into tokens.

delimiters - The delimiters to split the supplied input into separate tokens.
Every character in this String is a delimiter.

Returns:

Array where each element contains a token.

Throws:

NullPointerException - When the supplied delimiters is null.

IllegalArgumentException - When the supplied delimiters is empty.

See Also:

StringTokenizer.StringTokenizer(String,String)

getRight

public static String getRight(String string,
                              int length)

Gets the supplied length number of characters from the right of the supplied string.

Parameters:

string - The string to get the characters from the right from.

length - The number of characters to get from the right of the supplied string.

Returns:

The supplied length number of characters from the right of the supplied string.

Throws:

IllegalArgumentException - When the supplied length is less than zero.

NullPointerException - When the supplied string is null.

StringIndexOutOfBoundsException - When the supplied length is larger than the length of the supplied string.

replace

public static String replace(String input,
                             String oldString,
                             String newString)

Replaces all occurrences of oldString with newString in the supplied input String.
Note: As of jdk 1.2 you can use a replace method on a StringBuffer and as of jdk 1.4 you can use replaceAll on a String (using regular expressions).

Parameters:

input - The input String that contains the Strings (zero or more) that need to be replaced.

oldString - The String in the input String that must be replaced.

newString - The String that replaces all occurrences of the oldString in the supplied input.

Returns:

A String resulting from replacing all occurrences of oldString in the input String with newString.
When oldString does not occur in input or when oldString is null or empty then no new String is constructed, the input String is simply returned.
When input is null then null is returned.

repeat

public static String repeat(String input,
                            int repeat)

Creates a String that consists of a repetition, determined by the supplied repeat count, of the supplied input String.
To create a String of 10 spaces for example, execute: CString.repeat(" ", 10);

Parameters:

input - Input String that will be repeated.

repeat - The number of times the supplied input String will be repeated.
Supplying a value of 0 will result in an empty String.

Returns:

String consisting of a concatenation of repeat times the supplied input String.

Throws:

IllegalArgumentException - When the supplied repeat count is negative.

NullPointerException - When the supplied input String is null.

alignLeft

public static String alignLeft(String input,
                               int length,
                               char pad)

Left aligns the supplied input String in a String with a length equal to the supplied length.
Examples:

Parameters	Returns
"1234", 6, '0'	123400
"1234", 2, '0'	12

Parameters:

input - The input String to align left.

length - The length of the resulting left aligned String.
When this length is less than the length of the supplied input String, the input String is truncated to fit the supplied length.

pad - The pad char used to fill the vacated positions.
Normally you will supply a space or a zero character to fill the vacated positions with spaces or zeroes respectively.

Returns:

The left aligned input String.

Throws:

IllegalArgumentException - When the supplied length is less than one.

NullPointerException - When the supplied input String is null.

alignRight

public static String alignRight(String input,
                                int length,
                                char pad)

Right aligns the supplied input String in a String with a length equal to the supplied length.
Examples:

Parameters	Returns
"1234", 6, '0'	001234
"1234", 2, '0'	34

Parameters:

input - The input String to align right.

length - The length of the resulting right aligned String.
When this length is less than the length of the supplied input String, the input String is truncated to fit the supplied length.

pad - The pad char used to fill the vacated positions.
Normally you will supply a space or a zero character to fill the vacated positions with spaces or zeroes respectively.

Returns:

The right aligned input String.

Throws:

IllegalArgumentException - When the supplied length is less than one.

NullPointerException - When the supplied input String is null.

removePrefixCharacters

public static String removePrefixCharacters(String input,
                                            char prefix)

Removes all the supplied prefix characters from the supplied input.
When the supplied input is null, empty or does not contain any prefix characters, the input is returned as-is.

Parameters:

input - The input String from which to remove the prefix characters.

prefix - The prefix characters to remove.

Returns:

The input String without the supplied prefix characters.

arrayToPlainCsv

public static String arrayToPlainCsv(Object... values)

Converts the supplied array of values to a string of comma separated values.
This method uses no quoting whatsoever, just separates the supplied values by a comma. Null values will be represented as an empty String.

Parameters:

values - The array of values that must be comma separated.

Returns:

A list of comma separated values or an empty string when the supplied array of values is either null or empty.

escapeControlCharacters

public static String escapeControlCharacters(String input)

Replaces control characters in the range 00-1F with escape characters.

Parameters:

input - Input string.

Returns:

Input string but with all control characters replaced with escape sequences.
Null is returned when the input string is null.

getEscapedControlCharacter

public static String getEscapedControlCharacter(int ordinal)

Gets the escape sequence for the control character with the supplied ordinal.

Parameters:

ordinal - The ordinal between 0 and 31 (inclusive) to get the escape sequence for.

Returns:

The escape sequence for the control character with the supplied ordinal.

Throws:

IllegalArgumentException - When the supplied ordinal is not between 0 and 31 (inclusive).

count

public static int count(String source,
                        String find)

Counts the number of occurrences of the supplied string to find in the supplied source string.

Parameters:

source - Input string.

find - String that will be searched for and counted, in the input string.

Returns:

Number of times that the string find occurs in the input string.

isNullOrEmpty

public static boolean isNullOrEmpty(String input)

Determines whether the supplied input String is null or empty.
Input consisting of whitespace only is considered to be empty!

Parameters:

input - Input String to test.

Returns:

True when the supplied input String is null or empty, false otherwise.

isNotEmpty

public static boolean isNotEmpty(String input)

Determines whether the supplied input string is not empty.
Input consisting of whitespace only is considered to be empty!

Parameters:

input - Input string to test.

Returns:

True when the supplied input string is not empty.
A string is not empty when it is not null and does not consist of whitespace characters only. A string containing a tab character is considered empty.

isAlphabetic

public static boolean isAlphabetic(String input)

Determines whether the supplied input string consists of alphabetic characters (letters) only.

Parameters:

input - Input string to test.

Returns:

True when for every character c in the supplied input string, Character.isLetter(c) == true, otherwise false is returned.
When the supplied input string is empty, true is returned.

Throws:

NullPointerException - When the supplied input is null.

isNumeric

public static boolean isNumeric(String input)

Determines whether the supplied input string consists of numeric characters (digits) only.
Decimal separators and plus or minus signs are not considered to be numeric!

Parameters:

input - Input string to test.

Returns:

True when for every character c in the supplied input String, Character.isDigit(c) == true, otherwise false is returned.
When the supplied input string is empty, true is returned.

Throws:

NullPointerException - When the supplied input is null.

isAlphaNumeric

public static boolean isAlphaNumeric(String input)

Determines whether the supplied input String consists of alphabetic letters and numeric characters (digits) only.
Decimal separators and plus or minus signs are not considered to be alphanumeric!

Parameters:

input - Input string to test.

Returns:

True when for every character c in the supplied input string, (Character.isLetter(c) || Character.isDigit(c)) == true, otherwise false is returned.
When the supplied input string is empty, true is returned.

Throws:

NullPointerException - When the supplied input is null.

isWhiteSpace

public static boolean isWhiteSpace(String input)

Determines whether the supplied input String consists of whitespace characters only.

Parameters:

input - Input string to test.

Returns:

True when for every character c in the supplied input string, Character.isWhiteSpace(c) == true, otherwise false is returned.
When the supplied input string is empty, true is returned.

Throws:

NullPointerException - When the supplied input is null.

isHexaDecimal

public static boolean isHexaDecimal(String input)

Determines whether the supplied input String consists of hexadecimal characters only.

Parameters:

input - Input string to test.

Returns:

True when every character in the supplied input is a hexadecimal character, otherwise false is returned.
False is also returned for empty input.

Throws:

NullPointerException - When the supplied input is null.

See Also:

Long.parseLong(String, int)

trim

public static String trim(Trim trim,
                          String input)

Trims whitespace from the supplied input.

Parameters:

trim - Determines where the whitespace is trimmed from.

input - The input to trim.

Returns:

The trimmed input String.
When the input is null or has zero length, the supplied input is returned as-is.

trimLeft

public static String trimLeft(String input)

Trims whitespace from the left of the supplied input.

Parameters:

input - The input to trim.

Returns:

The trimmed input String.
When the input is null or has zero length, the supplied input is returned as-is.

See Also:

Character.isWhitespace(char)

trimRight

public static String trimRight(String input)

Trims whitespace from the right of the supplied input.

Parameters:

input - The input to trim.

Returns:

The trimmed input String.
When the input is null or has zero length, the supplied input is returned as-is.

See Also:

Character.isWhitespace(char)

trimAll

public static String trimAll(String input)

Trims all whitespace characters from the supplied input, no matter where they are located.

Parameters:

input - The input to trim.

Returns:

The trimmed input String.
When the input is null or has zero length, the supplied input is returned as-is.

See Also:

Character.isWhitespace(char)

iterableToString

public static <T> String iterableToString(Iterable<T> iterable)

Creates a String representation of the supplied iterable.

Type Parameters:

T - The type of the iterable.

Parameters:

iterable - The iterable to create a String representation of.

Returns:

A String representation of the supplied iterable. When the supplied iterable is null, "null" is returned.

findMatch

public static String findMatch(String inputText,
                               String regularExpression)

Finds the text within the supplied inputText that matches the supplied regularExpression.
The regular expression will use Pattern.DOTALL.

Parameters:

inputText - The input text.

regularExpression - The regular expression used for matching.

Returns:

The text within the supplied inputText that matches against the supplied regularExpression or null when no such text exists.

checkMatchingCharacters

public static void checkMatchingCharacters(String input,
                                           char opening,
                                           char closing)

Checks that the supplied input has matching opening and closing characters, where opening and closing characters may not be nested.
CString.checkMatchingCharacters("abc", '[', ']');
CString.checkMatchingCharacters("ab[c]", '[', ']');
CString.checkMatchingCharacters("ab[c}", '[', '}');
Examples that would not match are:
CString.checkMatchingCharacters("abc[", '[', ']');
CString.checkMatchingCharacters("abc][", '[', ']'); // Wrong order
CString.checkMatchingCharacters("abc[[]]", '[', ']'); // Wrong nesting

Parameters:

input - Input to check for matching opening and closing characters.

opening - The opening character.

closing - The closing character.

Throws:

IllegalArgumentException - When either the supplied opening or closing character is 0 or when the supplied input has at least a single opening or closing character and the opening and closing characters do not match.

removeEndOfLineCharacters

public static String removeEndOfLineCharacters(String input)

Removes all the end of line characters from the supplied input String.

Parameters:

input - The input to remove end of line characters from.

Returns:

The supplied input String with all end of line characters removed.
When the supplied input is null or of zero length, the supplied input is returned as-is.