org.parboiled.common
Class StringUtils

java.lang.Object
  extended by org.parboiled.common.StringUtils

public final class StringUtils
extends java.lang.Object

General utility methods for string manipulation.


Method Summary
static boolean equalsIgnoreCase(java.lang.String str1, java.lang.String str2)
          Compares two Strings, returning true if they are equal ignoring the case.
static java.lang.String escape(char c)
          Replaces carriage returns, newlines, tabs, formfeeds and the special chars defined in Characters with their respective escape sequences.
static java.lang.String escape(java.lang.String string)
          Replaces carriage returns, newlines, tabs, formfeeds and the special chars defined in Characters with their respective escape sequences.
static boolean isEmpty(java.lang.String str)
          Checks if a String is empty ("") or null.
static boolean isNotEmpty(java.lang.String str)
          Checks if a String is not empty ("") and not null.
static java.lang.String join(java.util.Collection collection, java.lang.String separator)
          Joins the elements of the provided Collection into a single String containing the provided elements.
static java.lang.String join(java.util.Iterator iterator, java.lang.String separator)
          Joins the elements of the provided Iterator into a single String containing the provided elements.
static java.lang.String join(java.lang.Object[] array, java.lang.String separator)
          Joins the elements of the provided array into a single String containing the provided list of elements.
static java.lang.String join(java.lang.Object[] array, java.lang.String separator, int startIndex, int endIndex)
          Joins the elements of the provided array into a single String containing the provided list of elements.
static java.lang.String left(java.lang.String str, int len)
          Gets the leftmost len characters of a String.
static int length(java.lang.String str)
          Gets a String's length or 0 if the String is null.
static java.lang.String mid(java.lang.String str, int pos, int len)
          Gets len characters from the middle of a String.
static java.lang.String repeat(char c, int n)
          Creates a string consisting of n times the given character.
static java.lang.String right(java.lang.String str, int len)
          Gets the rightmost len characters of a String.
static boolean startsWith(java.lang.String string, java.lang.String prefix)
          Test whether a string starts with a given prefix, handling null values without exceptions.
static java.lang.String substring(java.lang.String str, int start)
          Gets a substring from the specified String avoiding exceptions.
static java.lang.String substring(java.lang.String str, int start, int end)
          Gets a substring from the specified String avoiding exceptions.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

escape

public static java.lang.String escape(java.lang.String string)
Replaces carriage returns, newlines, tabs, formfeeds and the special chars defined in Characters with their respective escape sequences.

Parameters:
string - the string
Returns:
the escaped string

escape

public static java.lang.String escape(char c)
Replaces carriage returns, newlines, tabs, formfeeds and the special chars defined in Characters with their respective escape sequences.

Parameters:
c - the character to escape
Returns:
the escaped string

repeat

public static java.lang.String repeat(char c,
                                      int n)
Creates a string consisting of n times the given character.

Parameters:
c - the char
n - the number of times to repeat
Returns:
the string

join

public static java.lang.String join(java.util.Collection collection,
                                    java.lang.String separator)

Joins the elements of the provided Collection into a single String containing the provided elements.

No delimiter is added before or after the list. A null separator is the same as an empty String ("").

Parameters:
collection - the Collection of values to join together, may be null
separator - the separator character to use, null treated as ""
Returns:
the joined String, null if null iterator input

join

public static java.lang.String join(java.util.Iterator iterator,
                                    java.lang.String separator)

Joins the elements of the provided Iterator into a single String containing the provided elements.

No delimiter is added before or after the list. A null separator is the same as an empty String ("").

Parameters:
iterator - the Iterator of values to join together, may be null
separator - the separator character to use, null treated as ""
Returns:
the joined String, null if null iterator input

join

public static java.lang.String join(java.lang.Object[] array,
                                    java.lang.String separator)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. A null separator is the same as an empty String (""). Null objects or empty strings within the array are represented by empty strings.

 StringUtils.join(null, *)                = null
 StringUtils.join([], *)                  = ""
 StringUtils.join([null], *)              = ""
 StringUtils.join(["a", "b", "c"], "--")  = "a--b--c"
 StringUtils.join(["a", "b", "c"], null)  = "abc"
 StringUtils.join(["a", "b", "c"], "")    = "abc"
 StringUtils.join([null, "", "a"], ',')   = ",,a"
 

Parameters:
array - the array of values to join together, may be null
separator - the separator character to use, null treated as ""
Returns:
the joined String, null if null array input

join

public static java.lang.String join(java.lang.Object[] array,
                                    java.lang.String separator,
                                    int startIndex,
                                    int endIndex)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. A null separator is the same as an empty String (""). Null objects or empty strings within the array are represented by empty strings.

 StringUtils.join(null, *)                = null
 StringUtils.join([], *)                  = ""
 StringUtils.join([null], *)              = ""
 StringUtils.join(["a", "b", "c"], "--")  = "a--b--c"
 StringUtils.join(["a", "b", "c"], null)  = "abc"
 StringUtils.join(["a", "b", "c"], "")    = "abc"
 StringUtils.join([null, "", "a"], ',')   = ",,a"
 

Parameters:
array - the array of values to join together, may be null
separator - the separator character to use, null treated as ""
startIndex - the first index to start joining from. It is an error to pass in an end index past the end of the array
endIndex - the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array
Returns:
the joined String, null if null array input

isEmpty

public static boolean isEmpty(java.lang.String str)

Checks if a String is empty ("") or null.

 StringUtils.isEmpty(null)      = true
 StringUtils.isEmpty("")        = true
 StringUtils.isEmpty(" ")       = false
 StringUtils.isEmpty("bob")     = false
 StringUtils.isEmpty("  bob  ") = false
 

Parameters:
str - the String to check, may be null
Returns:
true if the String is empty or null

isNotEmpty

public static boolean isNotEmpty(java.lang.String str)

Checks if a String is not empty ("") and not null.

 StringUtils.isNotEmpty(null)      = false
 StringUtils.isNotEmpty("")        = false
 StringUtils.isNotEmpty(" ")       = true
 StringUtils.isNotEmpty("bob")     = true
 StringUtils.isNotEmpty("  bob  ") = true
 

Parameters:
str - the String to check, may be null
Returns:
true if the String is not empty and not null

length

public static int length(java.lang.String str)
Gets a String's length or 0 if the String is null.

Parameters:
str - a String or null
Returns:
String length or 0 if the String is null.

equalsIgnoreCase

public static boolean equalsIgnoreCase(java.lang.String str1,
                                       java.lang.String str2)

Compares two Strings, returning true if they are equal ignoring the case.

nulls are handled without exceptions. Two null references are considered equal. Comparison is case insensitive.

 StringUtils.equalsIgnoreCase(null, null)   = true
 StringUtils.equalsIgnoreCase(null, "abc")  = false
 StringUtils.equalsIgnoreCase("abc", null)  = false
 StringUtils.equalsIgnoreCase("abc", "abc") = true
 StringUtils.equalsIgnoreCase("abc", "ABC") = true
 

Parameters:
str1 - the first String, may be null
str2 - the second String, may be null
Returns:
true if the Strings are equal, case insensitive, or both null

startsWith

public static boolean startsWith(java.lang.String string,
                                 java.lang.String prefix)
Test whether a string starts with a given prefix, handling null values without exceptions.

StringUtils.startsWith(null, null) = false StringUtils.startsWith(null, "abc") = false StringUtils.startsWith("abc", null) = true StringUtils.startsWith("abc", "ab") = true StringUtils.startsWith("abc", "abc") = true

Parameters:
string - the string
prefix - the prefix
Returns:
true if string starts with prefix

substring

public static java.lang.String substring(java.lang.String str,
                                         int start)

Gets a substring from the specified String avoiding exceptions.

A negative start position can be used to start n characters from the end of the String.

A null String will return null. An empty ("") String will return "".

 StringUtils.substring(null, *)   = null
 StringUtils.substring("", *)     = ""
 StringUtils.substring("abc", 0)  = "abc"
 StringUtils.substring("abc", 2)  = "c"
 StringUtils.substring("abc", 4)  = ""
 StringUtils.substring("abc", -2) = "bc"
 StringUtils.substring("abc", -4) = "abc"
 

Parameters:
str - the String to get the substring from, may be null
start - the position to start from, negative means count back from the end of the String by this many characters
Returns:
substring from start position, null if null String input

substring

public static java.lang.String substring(java.lang.String str,
                                         int start,
                                         int end)

Gets a substring from the specified String avoiding exceptions.

A negative start position can be used to start/end n characters from the end of the String.

The returned substring starts with the character in the start position and ends before the end position. All position counting is zero-based -- i.e., to start at the beginning of the string use start = 0. Negative start and end positions can be used to specify offsets relative to the end of the String.

If start is not strictly to the left of end, "" is returned.

 StringUtils.substring(null, *, *)    = null
 StringUtils.substring("", * ,  *)    = "";
 StringUtils.substring("abc", 0, 2)   = "ab"
 StringUtils.substring("abc", 2, 0)   = ""
 StringUtils.substring("abc", 2, 4)   = "c"
 StringUtils.substring("abc", 4, 6)   = ""
 StringUtils.substring("abc", 2, 2)   = ""
 StringUtils.substring("abc", -2, -1) = "b"
 StringUtils.substring("abc", -4, 2)  = "ab"
 

Parameters:
str - the String to get the substring from, may be null
start - the position to start from, negative means count back from the end of the String by this many characters
end - the position to end at (exclusive), negative means count back from the end of the String by this many characters
Returns:
substring from start position to end positon, null if null String input

left

public static java.lang.String left(java.lang.String str,
                                    int len)

Gets the leftmost len characters of a String.

If len characters are not available, or the String is null, the String will be returned without an exception. An exception is thrown if len is negative.

 StringUtils.left(null, *)    = null
 StringUtils.left(*, -ve)     = ""
 StringUtils.left("", *)      = ""
 StringUtils.left("abc", 0)   = ""
 StringUtils.left("abc", 2)   = "ab"
 StringUtils.left("abc", 4)   = "abc"
 

Parameters:
str - the String to get the leftmost characters from, may be null
len - the length of the required String, must be zero or positive
Returns:
the leftmost characters, null if null String input

right

public static java.lang.String right(java.lang.String str,
                                     int len)

Gets the rightmost len characters of a String.

If len characters are not available, or the String is null, the String will be returned without an an exception. An exception is thrown if len is negative.

 StringUtils.right(null, *)    = null
 StringUtils.right(*, -ve)     = ""
 StringUtils.right("", *)      = ""
 StringUtils.right("abc", 0)   = ""
 StringUtils.right("abc", 2)   = "bc"
 StringUtils.right("abc", 4)   = "abc"
 

Parameters:
str - the String to get the rightmost characters from, may be null
len - the length of the required String, must be zero or positive
Returns:
the rightmost characters, null if null String input

mid

public static java.lang.String mid(java.lang.String str,
                                   int pos,
                                   int len)

Gets len characters from the middle of a String.

If len characters are not available, the remainder of the String will be returned without an exception. If the String is null, null will be returned. An exception is thrown if len is negative.

 StringUtils.mid(null, *, *)    = null
 StringUtils.mid(*, *, -ve)     = ""
 StringUtils.mid("", 0, *)      = ""
 StringUtils.mid("abc", 0, 2)   = "ab"
 StringUtils.mid("abc", 0, 4)   = "abc"
 StringUtils.mid("abc", 2, 4)   = "c"
 StringUtils.mid("abc", 4, 2)   = ""
 StringUtils.mid("abc", -2, 2)  = "ab"
 

Parameters:
str - the String to get the characters from, may be null
pos - the position to start from, negative treated as zero
len - the length of the required String, must be zero or positive
Returns:
the middle characters, null if null String input