Evaluating Software Design Patterns
— the "Gang of Four" patterns implemented in Java 6

dk.rode.thesis.meta.util
Class Strings

java.lang.Object
  extended by dk.rode.thesis.meta.util.Strings

public class Strings
extends Object

Various string utilities.

When ever possible, the supplied char sequence arguments are used as is in order to avoid copying into strings. Supplied char sequence arguments are never modified!

Author:
Gunni Rode / rode.dk

Constructor Summary
private Strings()
          Private off-limit constructor.
 
Method Summary
static int count(CharSequence cs, char c)
          Returns the number of times the char c is present in the char sequence cs.
static boolean empty(CharSequence cs)
          Returns true if cs only contains white space characters, false if not.
static int indexOf(CharSequence cs, char c)
          Finds the first index where c is present in cs, or -1 if c cannot be found.
static int indexOf(CharSequence cs, char c, int index)
          Finds the first index where c is present in cs after the index supplied, or -1 if c cannot be found.
static int indexOfIgnoreCase(CharSequence cs, char c)
          Finds the first index where c is present in cs, regardless of case, or -1 if c cannot be found.
static int indexOfIgnoreCase(CharSequence cs, char c, int index)
          Finds the first index where c is present in cs after the index supplied, regardless of case, or -1 if c cannot be found.
static int indexOfIgnoreCase(CharSequence cs, CharSequence token)
          Finds the first index where token is present in cs, regardless of case, or -1 if token cannot be found.
static int indexOfIgnoreCase(CharSequence cs, CharSequence token, int index)
          Finds the first index where token is present in cs after the index supplied, regardless of case, or -1 if token cannot be found.
static int indexOfIgnoreCase(CharSequence cs, CharSequence token, int index, Locale locale)
          Finds the first index where token is present in cs after the index supplied, regardless of case, or -1 if token cannot be found.
static int indexOfIgnoreCase(CharSequence cs, CharSequence token, Locale locale)
          Finds the first index where token is present in cs, regardless of case, or -1 if token cannot be found.
static boolean isEscaped(CharSequence cs, char escape, int index)
          Returns true if the char at index index in the char sequence cs is escaped, false if not.
static boolean isEscaped(CharSequence cs, int index)
          Returns true if the char at index index in the char sequence cs is escaped, false if not.
static CharSequence lowerCaseFirst(CharSequence cs)
          Lower-cases the first char in the char sequence cs and returns the modified string using the default locale.
static CharSequence lowerCaseFirst(CharSequence cs, Locale locale)
          Lower-cases the first char in the char sequence cs and returns the modified string using the supplied locale.
static CharSequence postfix(CharSequence cs, char c, int length)
          Postfixes the string value represented by cs with c length times.
static CharSequence prefix(CharSequence cs, char c, int length)
          Prefixes the string value represented by cs with c length times.
static CharSequence[] split(CharSequence cs, char c)
          Splits the char sequence cs on the char c.
static CharSequence upperCaseFirst(CharSequence cs)
          Upper-cases the first char in the char sequence cs and returns the modified string using the default locale.
static CharSequence upperCaseFirst(CharSequence cs, Locale locale)
          Upper-cases the first char in the char sequence cs and returns the modified string using the supplied locale.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Strings

private Strings()
Private off-limit constructor.

Method Detail

count

public static final int count(CharSequence cs,
                              char c)
Returns the number of times the char c is present in the char sequence cs.

Parameters:
cs - The char sequence; cannot be null.
c - The character to test.
Returns:
The number of times c is present in cs.
Throws:
NullPointerException - If cs is null.

empty

public static final boolean empty(CharSequence cs)
Returns true if cs only contains white space characters, false if not.

Parameters:
cs - The char sequence to test; cannot be null.
Returns:
True if empty, false if not.
Throws:
NullPointerException - If cs is null.

indexOf

public static final int indexOf(CharSequence cs,
                                char c)
Finds the first index where c is present in cs, or -1 if c cannot be found.

Parameters:
cs - The char sequence; cannot be null.
c - The char to find.
Returns:
The first index of c, or -1 if not found.
Throws:
NullPointerException - If cs is null.

indexOf

public static final int indexOf(CharSequence cs,
                                char c,
                                int index)
Finds the first index where c is present in cs after the index supplied, or -1 if c cannot be found.

index is allowed to be larger than cs.length(), in which case this method returns -1.

Parameters:
cs - The char sequence; cannot be null.
c - The char to find.
index - The index to start at; cannot be negative.
Returns:
The first index of c, or -1 if not found.
Throws:
NullPointerException - If cs is null.
IndexOutOfBoundsException - If index is negative.

indexOfIgnoreCase

public static final int indexOfIgnoreCase(CharSequence cs,
                                          char c)
Finds the first index where c is present in cs, regardless of case, or -1 if c cannot be found.

Parameters:
cs - The char sequence; cannot be null.
c - The char to find.
Returns:
The first index of c, regardless of case, or -1 if not found.
Throws:
NullPointerException - If cs is null.

indexOfIgnoreCase

public static final int indexOfIgnoreCase(CharSequence cs,
                                          char c,
                                          int index)
Finds the first index where c is present in cs after the index supplied, regardless of case, or -1 if c cannot be found.

index is allowed to be larger than cs.length(), in which case this method returns -1.

Parameters:
cs - The char sequence; cannot be null.
c - The char to find.
index - The index to start at; cannot be negative.
Returns:
The first index of c, regardless of case, or -1 if not found.
Throws:
NullPointerException - If cs is null.
IndexOutOfBoundsException - If index is negative.

indexOfIgnoreCase

public static final int indexOfIgnoreCase(CharSequence cs,
                                          CharSequence token)
Finds the first index where token is present in cs, regardless of case, or -1 if token cannot be found.

The default locale is used to perform the case conversion.

Parameters:
cs - The char sequence; cannot be null.
token - The char sequence to find; cannot be null.
Returns:
The first index of token, regardless of case, or -1 if not found.
Throws:
NullPointerException - If either argument is null.

indexOfIgnoreCase

public static final int indexOfIgnoreCase(CharSequence cs,
                                          CharSequence token,
                                          int index)
Finds the first index where token is present in cs after the index supplied, regardless of case, or -1 if token cannot be found.

index is allowed to be larger than cs.length(), in which case this method returns -1. The default locale is used to perform the case conversion.

Parameters:
cs - The char sequence; cannot be null.
token - The char sequence to find; cannot be null.
index - The index to start at; cannot be negative.
Returns:
The first index of token, regardless of case, or -1 if not found.
Throws:
NullPointerException - If cs or token are null.
IndexOutOfBoundsException - If index is negative.

indexOfIgnoreCase

public static final int indexOfIgnoreCase(CharSequence cs,
                                          CharSequence token,
                                          int index,
                                          Locale locale)
Finds the first index where token is present in cs after the index supplied, regardless of case, or -1 if token cannot be found.

index is allowed to be larger than cs.length(), in which case this method returns -1. The supplied locale is used to perform the case conversion.

Parameters:
cs - The char sequence; cannot be null.
token - The char sequence to find; cannot be null.
index - The index to start at; cannot be negative.
locale - The locale to use; can be null, in which case the default locale is used.
Returns:
The first index of token, regardless of case, or -1 if not found.
Throws:
NullPointerException - If cs or token are null.
IndexOutOfBoundsException - If index is negative.

indexOfIgnoreCase

public static final int indexOfIgnoreCase(CharSequence cs,
                                          CharSequence token,
                                          Locale locale)
Finds the first index where token is present in cs, regardless of case, or -1 if token cannot be found.

The supplied locale is used to perform the case conversion.

Parameters:
cs - The char sequence; cannot be null.
token - The char sequence to find; cannot be null.
locale - The locale to use; can be null, in which case the default locale is used.
Returns:
The first index of token, regardless of case, or -1 if not found.
Throws:
NullPointerException - If cs or token are null.

isEscaped

public static final boolean isEscaped(CharSequence cs,
                                      char escape,
                                      int index)
Returns true if the char at index index in the char sequence cs is escaped, false if not.

The escape char used is escape.

Parameters:
cs - The char sequence; cannot be null.
escape - The escape char.
index - The index to check.
Returns:
True if escaped, false if not.
Throws:
NullPointerException - If cs is null.
IndexOutOfBoundsException - If index is illegal.

isEscaped

public static final boolean isEscaped(CharSequence cs,
                                      int index)
Returns true if the char at index index in the char sequence cs is escaped, false if not.

The escape char used is backslash (\).

Parameters:
cs - The char sequence; cannot be null.
index - The index to check.
Returns:
True if escaped, false if not.
Throws:
NullPointerException - If cs is null.
IndexOutOfBoundsException - If index is illegal.

lowerCaseFirst

public static final CharSequence lowerCaseFirst(CharSequence cs)
Lower-cases the first char in the char sequence cs and returns the modified string using the default locale.

The returned string might not be the same length as cs as explained under String.toLowerCase(Locale).

Parameters:
cs - The char sequence; cannot be null.
Returns:
A char sequence representing the modification; never null.
Throws:
NullPointerException - If cs is null.

lowerCaseFirst

public static final CharSequence lowerCaseFirst(CharSequence cs,
                                                Locale locale)
Lower-cases the first char in the char sequence cs and returns the modified string using the supplied locale.

The returned string might not be the same length as cs as explained under String.toLowerCase(Locale).

Parameters:
cs - The char sequence; cannot be null.
locale - The locale to use; can be null, in which case the default locale is used.
Returns:
A char sequence representing the modification; never null.
Throws:
NullPointerException - If cs is null.

postfix

public static final CharSequence postfix(CharSequence cs,
                                         char c,
                                         int length)
Postfixes the string value represented by cs with c length times.

Parameters:
cs - The char sequence; cannot be null.
c - The char to postfix.
length - The number of times to postfix c.
Returns:
A new prefixed char sequence; never null.
Throws:
NullPointerException - If cs is null.
IllegalArgumentException - If length is less than zero.

prefix

public static final CharSequence prefix(CharSequence cs,
                                        char c,
                                        int length)
Prefixes the string value represented by cs with c length times.

Parameters:
cs - The char sequence; cannot be null.
c - The char to prefix.
length - The number of times to prefix c.
Returns:
A new prefixed char sequence; never null.
Throws:
NullPointerException - If cs is null.
IllegalArgumentException - If length is less than zero.

split

public static final CharSequence[] split(CharSequence cs,
                                         char c)
Splits the char sequence cs on the char c.

Note, that this method does not always yield the same result as string.split() using the same split value (a single char)! The string.split() method does not include "empty parts in the end of the string" in the returned array, for example:

 String foo = "##a#b##c###";
 
 String[] bar = foo.split("#");          // [, , a, b, , c]     = 6 elements
          bar = Strings.split(foo, '#'); // [, , a, b, , c, , ] = 8 elements   
 

Parameters:
cs - The char sequence; cannot be null.
c - The split char.
Returns:
An array containing the parts; never null, and never empty.
Throws:
NullPointerException - If cs is null.

upperCaseFirst

public static final CharSequence upperCaseFirst(CharSequence cs)
Upper-cases the first char in the char sequence cs and returns the modified string using the default locale.

The returned string might not be the same length as cs as explained under String.toUpperCase(Locale).

Parameters:
cs - The char sequence; cannot be null.
Returns:
A char sequence representing the modification; never null.
Throws:
NullPointerException - If cs is null.

upperCaseFirst

public static final CharSequence upperCaseFirst(CharSequence cs,
                                                Locale locale)
Upper-cases the first char in the char sequence cs and returns the modified string using the supplied locale.

The returned string might not be the same length as cs as explained under String.toUpperCase(Locale).

Parameters:
cs - The char sequence; cannot be null.
locale - The locale to use; can be null, in which case the default locale is used.
Returns:
A char sequence representing the modification; never null.
Throws:
NullPointerException - If cs is null.

Gunni Rode / rode.dk

Feel free to use and/or modify the Java 6 source code developed for this thesis AT YOUR OWN RISK, but note that the source code comes WITHOUT ANY — and I do mean WITHOUT ANY — form of warranty WHAT SO EVER!

The original thesis and source code are available at rode.dk/thesis.