StringUtil (ch-commons-util 6.0.2 API)

java.lang.Object
- com.cloudhopper.commons.util.StringUtil

```
public class StringUtil
extends Object
```
A set of String utilities.

Author:

joelauer (twitter: @jjlauer or http://twitter.com/jjlauer)

Field Summary

Fields
Modifier and Type Field and Description

static char[] HEX_TABLE

Fields
Modifier and Type	Field and Description
`static char[]`	`HEX_TABLE`

Constructor Summary

Constructors
Constructor and Description

StringUtil()

Constructors
Constructor and Description
`StringUtil()`

Method Summary

Methods
Modifier and Type	Method and Description
`static String`	`capitalize(String string0)` Safely capitalizes a string by converting the first character to upper case.
`static String`	`compressQuotes(String source, String quotes)` Compress 2 adjacent (single or double) quotes into a single (s or d) quote when found in the middle of a String.
`static boolean`	`contains(String[] strings, String targetString)` Checks if the targetString is contained within the array of strings.
`static boolean`	`containsOnlyDigits(String string0)` Checks if a string contains only digits.
`static String`	`escapeXml(String value)` Escapes the characters in a String using XML entities.
`static String`	`formatForPrint(String input)` Used to print out a string for error messages, chops is off at 60 chars for historical reasons.
`static byte[]`	`fromHexString(String hexString)` Deprecated. Please use new utility class HexUtil
`static byte[]`	`fromHexString(String hexString, int offset, int length)` Deprecated. Please use new utility class HexUtil
`static byte[]`	`getAsciiBytes(String input)` Get 7-bit ASCII character array from input String.
`static String`	`getAsciiString(byte[] input)`
`static String`	`hexDump(String prefix, byte[] data)` Convert a byte array to a human-readable String for debugging purposes.
`static int`	`indexOf(String[] strings, String targetString)` Finds the first occurrence of the targetString in the array of strings.
`static boolean`	`isEmpty(String string0)` Checks if the string is an empty value which is true if the string is null or if the string represents an empty string of "".
`static boolean`	`isEqual(String string0, String string1)`
`static boolean`	`isEqual(String string0, String string1, boolean caseSensitive)` Checks if both strings are equal to each other.
`static boolean`	`isPrintableChar(char ch)` Return true if the character is printable in ASCII.
`static boolean`	`isSafeChar(char ch)` Returns true if the char is considered a "safe" char.
`static boolean`	`isSafeString(String string0)` Returns true if the String is considered a "safe" string where only specific characters are allowed to be used.
`static String`	`normalizeSQLIdentifier(String id)` Normalize a SQL identifer, up-casing if , and handling of (SQL 2003, section 5.2).
`static String`	`quoteStringLiteral(String string)` Quote a string so that it can be used as a string literal in an SQL statement.
`static String`	`readToString(InputStream in)`
`static String`	`removeAllCharsExceptDigits(String str0)` Removes all other characters from a string except digits.
`static String`	`slice(String value, int beginOffset, int endOffset, boolean trim)` Return a slice (substring) of the passed in value, optionally trimmed.
`static String[]`	`split(String str, char delim)` Splits a string around matches of the given delimiter character.
`static boolean`	`SQLEqualsIgnoreCase(String s1, String s2)` Compares two strings Strings will be uppercased in english and compared equivalent to s1.equalsIgnoreCase(s2) throws NPE if s1 is null
`static String`	`SQLToUpperCase(String s)` Convert string to uppercase Always use the java.util.ENGLISH locale
`static String`	`stringify(int[] raw)` Turn an array of ints into a printable string.
`static String`	`stripQuotes(String string0)` If present, this method will strip off the leading and trailing " character in the string parameter.
`static String`	`substituteWithEnvironment(String string0)` Searches the string for occurrences of the pattern $ENV{key} and attempts to replace this pattern with a value from the System environment obtained using the 'key'.
`static String`	`substituteWithProperties(String string0, String startStr, String endStr, Properties properties)` Searches string for occurrences of a pattern, extracts out a key name between the startStr and endStr tokens, then attempts to replace the property value into the string.
`static byte[]`	`toHexByte(String hexString, int offset, int length)` Deprecated. Please use new utility class HexUtil
`static String`	`toHexString(byte[] bytes)` Deprecated. Please use new utility class HexUtil
`static String`	`toHexString(byte[] bytes, int offset, int length)` Deprecated. Please use new utility class HexUtil
`static String[]`	`toStringArray(Object[] objArray)` A method that receive an array of Objects and return a String array representation of that array.
`static String`	`toStringWithNullAsEmpty(Object obj)` Returns the value from calling "toString()" on the object, but is a safe version that gracefully handles NULL objects by returning a String of "".
`static String`	`toStringWithNullAsNull(Object obj)` Returns the value from calling "toString()" on the object, but is a safe version that gracefully handles NULL objects by returning null (rather than causing a NullPointerException).
`static String`	`toStringWithNullAsReplaced(Object obj)` Returns the value from calling "toString()" on the object, but is a safe version that gracefully handles NULL objects by returning a String of "".
`static String`	`trimTrailing(String str)` Trim off trailing blanks but not leading blanks
`static String`	`truncate(String value, int length)` Truncate a String to the given length with no warnings or error raised if it is bigger.
`static String`	`uncapitalize(String string0)` Safely uncapitalizes a string by converting the first character to lower case.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - HEX_TABLE
```
public static char[] HEX_TABLE
```
- Constructor Detail
  - StringUtil
```
public StringUtil()
```
- Method Detail
  - substituteWithEnvironment
```
public static String substituteWithEnvironment(String string0)
                                        throws SubstitutionException
```
    Searches the string for occurrences of the pattern $ENV{key} and attempts to replace this pattern with a value from the System environment obtained using the 'key'. For example, including "$ENV{USERNAME}" in a string and calling this method would then attempt to replace the entire pattern with the value of the environment variable "USERNAME". The System environment is obtained in Java with a call to System.getenv(). An environment variable is typically defined in the Linux shell or Windows property tabs. NOTE: A Java System property is not the same as an environment variable.
    
    Parameters:
    string0 - The string to perform substitution on such as "Hello $ENV{USERNAME}". This string may be null, empty, or contain one or more substitutions.
    
    Returns:
    A string with all occurrences of keys substituted with their values obtained from the System environment. Can be null if the original string was null.
    
    Throws:
    
    SubstitutionException - Thrown if a starting string was found, but the ending string was not. Also, thrown if a key value was empty such as using "$ENV{}". Finally, thrown if the property key was not found in the properties object (could not be replaced).
    See Also:
    substituteWithProperties(java.lang.String, java.lang.String, java.lang.String, java.util.Properties)
  - substituteWithProperties
```
public static String substituteWithProperties(String string0,
                              String startStr,
                              String endStr,
                              Properties properties)
                                       throws SubstitutionException
```
    Searches string for occurrences of a pattern, extracts out a key name between the startStr and endStr tokens, then attempts to replace the property value into the string. This method is useful for merging property values into configuration strings/settings. For examle, the system environment Map could be converted into a Properties object then have its values merged into a String so that users can access environment variables.
    
    Parameters:
    string0 - The string to perform substitution on such as "Hello $ENV{TEST}". This string may be null, empty, or contain one or more substitutions.
    startStr - The string that marks the start of a replacement key such as "$ENV{" if the final search pattern you wanted was "$ENV{}".
    endStr - The string that marks the end of a replacement key such as "}" if the final search pattern you wanted was "$ENV{}".
    properties - The property keys and associated values to use for replacement.
    
    Returns:
    A string with all occurrences of keys substituted with their values obtained from the properties object. Can be null if the original string was null.
    
    Throws:
    
    SubstitutionException - Thrown if a starting string was found, but the ending string was not. Also, thrown if a key value was empty such as using "$ENV{}". Finally, thrown if the property key was not found in the properties object (could not be replaced).
    See Also:
    substituteWithEnvironment(java.lang.String)
  - isSafeString
```
public static boolean isSafeString(String string0)
```
    Returns true if the String is considered a "safe" string where only specific characters are allowed to be used. Useful for checking passwords or other information you don't want a user to be able to type just anything in. This method does not allow any whitespace characters, newlines, carriage returns. Primarily allows [a-z] [A-Z] [0-9] and a few other useful ASCII characters such as ":~!@#$%^*()-_+=/\\,.[]{}|?<>" (but not the quote chars)
  - isSafeChar
```
public static boolean isSafeChar(char ch)
```
    Returns true if the char is considered a "safe" char. Please see documentation for isSafeString().
    
    See Also:
    isSafeString(java.lang.String)
  - capitalize
```
public static String capitalize(String string0)
```
    Safely capitalizes a string by converting the first character to upper case. Handles null, empty, and strings of length of 1 or greater. For example, this will convert "joe" to "Joe". If the string is null, this will return null. If the string is empty such as "", then it'll just return an empty string such as "".
    
    Parameters:
    string0 - The string to capitalize
    
    Returns:
    A new string with the first character converted to upper case
  - uncapitalize
```
public static String uncapitalize(String string0)
```
    Safely uncapitalizes a string by converting the first character to lower case. Handles null, empty, and strings of length of 1 or greater. For example, this will convert "Joe" to "joe". If the string is null, this will return null. If the string is empty such as "", then it'll just return an empty string such as "".
    
    Parameters:
    string0 - The string to uncapitalize
    
    Returns:
    A new string with the first character converted to lower case
  - contains
```
public static boolean contains(String[] strings,
               String targetString)
```
    Checks if the targetString is contained within the array of strings. This method will return true if a "null" is contained in the array and the targetString is also null.
    
    Parameters:
    strings - The array of strings to search.
    targetString - The string to search for
    
    Returns:
    True if the string is contained within, otherwise false. Also returns false if the strings array is null.
  - indexOf
```
public static int indexOf(String[] strings,
          String targetString)
```
    Finds the first occurrence of the targetString in the array of strings. Returns -1 if an occurrence wasn't found. This method will return true if a "null" is contained in the array and the targetString is also null.
    
    Parameters:
    strings - The array of strings to search.
    targetString - The string to search for
    
    Returns:
    The index of the first occurrence, or -1 if not found. If strings array is null, will return -1;
  - stripQuotes
```
public static String stripQuotes(String string0)
```
    If present, this method will strip off the leading and trailing " character in the string parameter. For example, "10958" will becomes just 10958.
  - containsOnlyDigits
```
public static boolean containsOnlyDigits(String string0)
```
    Checks if a string contains only digits.
    
    Returns:
    True if the string0 only contains digits, or false otherwise.
  - split
```
public static String[] split(String str,
             char delim)
```
    Splits a string around matches of the given delimiter character. Where applicable, this method can be used as a substitute for String.split(String regex), which is not available on a JSR169/Java ME platform.
    
    Parameters:
    str - the string to be split
    delim - the delimiter
    
    Throws:
    
    NullPointerException - if str is null
  - formatForPrint
```
public static final String formatForPrint(String input)
```
    Used to print out a string for error messages, chops is off at 60 chars for historical reasons.
  - toStringArray
```
public static String[] toStringArray(Object[] objArray)
```
    A method that receive an array of Objects and return a String array representation of that array.
  - getAsciiBytes
```
public static byte[] getAsciiBytes(String input)
```
    Get 7-bit ASCII character array from input String. The lower 7 bits of each character in the input string is assumed to be the ASCII character value. Hexadecimal - Character | 00 NUL| 01 SOH| 02 STX| 03 ETX| 04 EOT| 05 ENQ| 06 ACK| 07 BEL| | 08 BS | 09 HT | 0A NL | 0B VT | 0C NP | 0D CR | 0E SO | 0F SI | | 10 DLE| 11 DC1| 12 DC2| 13 DC3| 14 DC4| 15 NAK| 16 SYN| 17 ETB| | 18 CAN| 19 EM | 1A SUB| 1B ESC| 1C FS | 1D GS | 1E RS | 1F US | | 20 SP | 21 ! | 22 " | 23 # | 24 $ | 25 % | 26 & | 27 ' | | 28 ( | 29 ) | 2A * | 2B + | 2C , | 2D - | 2E . | 2F / | | 30 0 | 31 1 | 32 2 | 33 3 | 34 4 | 35 5 | 36 6 | 37 7 | | 38 8 | 39 9 | 3A : | 3B ; | 3C < | 3D = | 3E > | 3F ? | | 40 @ | 41 A | 42 B | 43 C | 44 D | 45 E | 46 F | 47 G | | 48 H | 49 I | 4A J | 4B K | 4C L | 4D M | 4E N | 4F O | | 50 P | 51 Q | 52 R | 53 S | 54 T | 55 U | 56 V | 57 W | | 58 X | 59 Y | 5A Z | 5B [ | 5C \ | 5D ] | 5E ^ | 5F _ | | 60 ` | 61 a | 62 b | 63 c | 64 d | 65 e | 66 f | 67 g | | 68 h | 69 i | 6A j | 6B k | 6C l | 6D m | 6E n | 6F o | | 70 p | 71 q | 72 r | 73 s | 74 t | 75 u | 76 v | 77 w | | 78 x | 79 y | 7A z | 7B { | 7C | | 7D } | 7E ~ | 7F DEL|
  - getAsciiString
```
public static String getAsciiString(byte[] input)
```
  - trimTrailing
```
public static String trimTrailing(String str)
```
    Trim off trailing blanks but not leading blanks
    
    Parameters:
    str -
    
    Returns:
    The input with trailing blanks stipped off
  - truncate
```
public static String truncate(String value,
              int length)
```
    Truncate a String to the given length with no warnings or error raised if it is bigger.
    
    Parameters:
    value - String to be truncated
    length - Maximum length of string
    
    Returns:
    Returns value if value is null or value.length() is less or equal to than length, otherwise a String representing value truncated to length.
  - slice
```
public static String slice(String value,
           int beginOffset,
           int endOffset,
           boolean trim)
```
    Return a slice (substring) of the passed in value, optionally trimmed. WARNING - endOffset is inclusive for historical reasons, unlike String.substring() which has an exclusive ending offset.
    
    Parameters:
    value - Value to slice, must be non-null.
    beginOffset - Inclusive start character
    endOffset - Inclusive end character
    trim - To trim or not to trim
    
    Returns:
    Sliceed value.
  - toHexString
```
@Deprecated
public static String toHexString(byte[] bytes)
```
    Deprecated. Please use new utility class HexUtil
    
    See Also:
    HexUtil.toHexString(byte[])
  - toHexString
```
@Deprecated
public static String toHexString(byte[] bytes,
                            int offset,
                            int length)
```
    Deprecated. Please use new utility class HexUtil
    
    See Also:
    HexUtil.toHexString(byte[], int, int)
  - toHexByte
```
@Deprecated
public static byte[] toHexByte(String hexString,
                          int offset,
                          int length)
```
    Deprecated. Please use new utility class HexUtil
    
    See Also:
    HexUtil.toByteArray(java.lang.CharSequence, int, int)
  - fromHexString
```
@Deprecated
public static byte[] fromHexString(String hexString)
```
    Deprecated. Please use new utility class HexUtil
    
    Converts from a hex string like "FF" to a byte[].
    
    Parameters:
    string0 - The string containing the hex-encoded data.
    
    Returns:
    See Also:
    HexUtil.toByteArray(java.lang.CharSequence)
  - fromHexString
```
@Deprecated
public static byte[] fromHexString(String hexString,
                              int offset,
                              int length)
```
    Deprecated. Please use new utility class HexUtil
    
    Convert a hexidecimal string generated by toHexString() back into a byte array.
    
    Parameters:
    s - String to convert
    offset - starting character (zero based) to convert.
    length - number of characters to convert.
    
    Returns:
    the converted byte array. Returns null if the length is not a multiple of 2.
    See Also:
    HexUtil.toByteArray(java.lang.CharSequence, int, int)
  - isPrintableChar
```
public static boolean isPrintableChar(char ch)
```
    Return true if the character is printable in ASCII. Not using Character.isLetterOrDigit(); applies to all unicode ranges.
  - hexDump
```
public static String hexDump(String prefix,
             byte[] data)
```
    Convert a byte array to a human-readable String for debugging purposes.
  - SQLToUpperCase
```
public static String SQLToUpperCase(String s)
```
    Convert string to uppercase Always use the java.util.ENGLISH locale
    
    Parameters:
    s - string to uppercase
    
    Returns:
    uppercased string
  - SQLEqualsIgnoreCase
```
public static boolean SQLEqualsIgnoreCase(String s1,
                          String s2)
```
    Compares two strings Strings will be uppercased in english and compared equivalent to s1.equalsIgnoreCase(s2) throws NPE if s1 is null
    
    Parameters:
    s1 - first string to compare
    s2 - second string to compare
    
    Returns:
    true if the two upppercased ENGLISH values are equal return false if s2 is null
  - normalizeSQLIdentifier
```
public static String normalizeSQLIdentifier(String id)
```
    Normalize a SQL identifer, up-casing if , and handling of (SQL 2003, section 5.2). The normal form is used internally in Derby.
    
    Parameters:
    id - syntacically correct SQL identifier
  - compressQuotes
```
public static String compressQuotes(String source,
                    String quotes)
```
    Compress 2 adjacent (single or double) quotes into a single (s or d) quote when found in the middle of a String. NOTE: """" or '''' will be compressed into "" or ''. This function assumes that the leading and trailing quote from a string or delimited identifier have already been removed.
    
    Parameters:
    source - string to be compressed
    quotes - string containing two single or double quotes.
    
    Returns:
    String where quotes have been compressed
  - quoteStringLiteral
```
public static String quoteStringLiteral(String string)
```
    Quote a string so that it can be used as a string literal in an SQL statement.
    
    Parameters:
    string - the string to quote
    
    Returns:
    the string surrounded by single quotes and with proper escaping of any single quotes inside the string
  - stringify
```
public static String stringify(int[] raw)
```
    Turn an array of ints into a printable string. Returns what's returned in Java 5 by java.util.Arrays.toString(int[]).
  - isEmpty
```
public static boolean isEmpty(String string0)
```
    Checks if the string is an empty value which is true if the string is null or if the string represents an empty string of "". Please note that a string with just a space " " would not be considered empty.
    
    Parameters:
    string0 - The string to check
    
    Returns:
    True if null or "", otherwise false.
  - isEqual
```
public static boolean isEqual(String string0,
              String string1)
```
  - toStringWithNullAsEmpty
```
public static String toStringWithNullAsEmpty(Object obj)
```
    Returns the value from calling "toString()" on the object, but is a safe version that gracefully handles NULL objects by returning a String of "".
    
    Parameters:
    obj - The object to call toString() on. Safely handles a null object.
    
    Returns:
    The value from obj.toString() or "" if the object is null.
    See Also:
    toStringWithNullAsNull(java.lang.Object)
  - toStringWithNullAsReplaced
```
public static String toStringWithNullAsReplaced(Object obj)
```
    Returns the value from calling "toString()" on the object, but is a safe version that gracefully handles NULL objects by returning a String of "".
    
    Parameters:
    obj - The object to call toString() on. Safely handles a null object.
    
    Returns:
    The value from obj.toString() or "" if the object is null.
    See Also:
    toStringWithNullAsEmpty(java.lang.Object)
  - toStringWithNullAsNull
```
public static String toStringWithNullAsNull(Object obj)
```
    Returns the value from calling "toString()" on the object, but is a safe version that gracefully handles NULL objects by returning null (rather than causing a NullPointerException).
    
    Parameters:
    obj - The object to call toString() on. Safely handles a null object.
    
    Returns:
    The value from obj.toString() or null if the object is null.
    See Also:
    toStringWithNullAsEmpty(java.lang.Object)
  - isEqual
```
public static boolean isEqual(String string0,
              String string1,
              boolean caseSensitive)
```
    Checks if both strings are equal to each other. Safely handles the case where either string may be null. The strings are evaluated as equal if they are both null or if they actually equal each other. One string that is null while the other one isn't (even if its an empty string) will be considered as NOT equal. Case sensitive comparisons are optional.
    
    Parameters:
    string0 - The string to compare
    string1 - The other string to compare with
    caseSensitive - If true a case sensitive comparison will be made, otherwise equalsIgnoreCase will be used.
    
    Returns:
    True if the strings are both null or equal to each other, otherwise false.
  - readToString
```
public static String readToString(InputStream in)
                           throws IOException
```
    Throws:
    
    IOException
  - escapeXml
```
public static String escapeXml(String value)
```
    Escapes the characters in a String using XML entities. For example: "bread" & "butter'ed" => "bread" & "butter'ed" Supports the five basic XML entities (gt, lt, quot, amp, apos) and also supports a newline and carriage return character. A newline is escaped to and a carriage return to
    
    Parameters:
    value - The string to escape
    
    Returns:
    The escaped String that can be used in an XML document.
  - removeAllCharsExceptDigits
```
public static String removeAllCharsExceptDigits(String str0)
```
    Removes all other characters from a string except digits. A good way of cleaing up something like a phone number.
    
    Parameters:
    str0 - The string to clean up
    
    Returns:
    A new String that has all characters except digits removed

Class StringUtil

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

HEX_TABLE

Constructor Detail

StringUtil

Method Detail

substituteWithEnvironment

substituteWithProperties

isSafeString

isSafeChar

capitalize

uncapitalize

contains

indexOf

stripQuotes

containsOnlyDigits

split

formatForPrint

toStringArray

getAsciiBytes

getAsciiString

trimTrailing

truncate

slice

toHexString

toHexString

toHexByte

fromHexString

fromHexString

isPrintableChar

hexDump

SQLToUpperCase

SQLEqualsIgnoreCase

normalizeSQLIdentifier

compressQuotes

quoteStringLiteral

stringify

isEmpty

isEqual

toStringWithNullAsEmpty

toStringWithNullAsReplaced

toStringWithNullAsNull

isEqual

readToString

escapeXml

removeAllCharsExceptDigits