StringUtil (KDG Commons 1.0.17 API)

java.lang.Object
- net.sf.kdgcommons.lang.StringUtil

```
public class StringUtil
extends Object
```
A collection of static utility methods for working with Strings. All methods are null-safe; in general they treat null as an empty string (but see JavaDoc).

Constructor Summary

Constructors
Constructor and Description

StringUtil()

Constructors
Constructor and Description
`StringUtil()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static boolean`	`contains(String str, String segment)` Determines whether the first string contains the second.
`static boolean`	`containsIgnoreCase(String str, String segment)` Determines whether the first string contains the second, ignoring case of individual letters.
`static boolean`	`equalOrEmpty(String s1, String s2)` Tests for equality, where null is equivalent to an empty string.
`static String`	`extractLeft(String source, String target)` Returns a substring of the source string, from its start up to but not including the first occurrence of the target string.
`static String`	`extractLeftOfLast(String source, String target)` Returns a substring of the source string, from its start up to but not including the last occurrence of the target string.
`static String`	`extractRight(String source, String target)` Returns a substring of the source string, from immediately after the first occurrence of the target string, to the end of the source.
`static String`	`extractRightOfLast(String source, String target)` Returns a substring of the source string, from immediately after the last occurrence of the target string, to the end of the source.
`static String`	`fromUTF8(byte[] bytes)` Converts the passed byte array to a string, using UTF-8 encoding, and turning the checked exception (which should never happen) into a runtime exception.
`static String`	`intern(String str)` Interns a string using a static instance of `StringCanon`.
`static boolean`	`isBlank(String str)` A null-safe check for strings that contain only whitespace (if anything).
`static boolean`	`isEmpty(String str)` A null-safe check for empty strings, where `null` is considered an empty string.
`static boolean`	`isIn(String str, String... targets)` Returns `true` if the passed string is equal to one of the target strings, `false` otherwise.
`static char`	`lastChar(String str)` Returns the last character in the passed string, '\0' if passed null or an empty string.
`static int`	`length(String str)` Returns the length of the passed string, 0 if the string is null.
`static String`	`padLeft(String str, int len, char c)` Pads a string that is < N characters by adding the specified character on the left side.
`static String`	`padRight(String str, int len, char c)` Pads a string that is < N characters by adding the specified character on the right side.
`static int`	`parseDigit(char c, int base)` Parses the passed character as a digit in the specified base, returning its value.
`static String`	`randomAlphaString(int minLength, int maxLength)` Generates a string containing (non-cryptographicaly-) random ASCII alphabetic characters (A-Za-z).
`static String`	`randomString(String chars, int minLength, int maxLength)` Generates a (non-cryptographicaly-) random string consisting of characters from the passed string.
`static String`	`repeat(char c, int count)` Creates a string that consists of a single character, repeated N times.
`static String`	`substr(String src, int off, int len)` A flexible substring that can return left or right substrings, and returns a "best effort" result if offset or length are outside the bounds of the string.
`static byte[]`	`toUTF8(String str)` Converts the string to a UTF-8 byte array, turning the checked exception (which should never happen) into a runtime exception.
`static String`	`trim(String str)` Removes all whitespace characters (per `Character.isWhitespace()`) from either side of a string.
`static String`	`trimToNull(String str)` Invokes `trim(java.lang.String)`, and returns null if the result is an empty string.
`static String`	`unescape(String src)` Un-escapes the passed string, replacing the standard slash escapes with their corresponding unicode character value.
`static String`	`unicodeEscape(String src)` Escapes the passed string, replacing all characters outside the range 32..126, as well as quotes and backslashes, with unicode escapes.
`static String`	`valueOf(Object obj)` A replacement for `String.valueOf()` that returns an empty string for null.

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

- Constructor Detail
  - StringUtil
```
public StringUtil()
```
- Method Detail
  - length
```
public static int length(String str)
```
    Returns the length of the passed string, 0 if the string is null.
    
    Since:
    
    1.0.12
  - equalOrEmpty
```
public static boolean equalOrEmpty(String s1,
                                   String s2)
```
    Tests for equality, where null is equivalent to an empty string.
  - lastChar
```
public static char lastChar(String str)
```
    Returns the last character in the passed string, '\0' if passed null or an empty string.
  - isEmpty
```
public static boolean isEmpty(String str)
```
    A null-safe check for empty strings, where null is considered an empty string.
  - isBlank
```
public static boolean isBlank(String str)
```
    A null-safe check for strings that contain only whitespace (if anything).
  - trim
```
public static String trim(String str)
```
    Removes all whitespace characters (per Character.isWhitespace()) from either side of a string. If passed null, will return an empty string. Will return the original string if it doesn't need trimming.
  - trimToNull
```
public static String trimToNull(String str)
```
    Invokes trim(java.lang.String), and returns null if the result is an empty string. Otherwise returns the trimmed string. This is useful to create flag values.
    
    Since:
    
    1.0.9
  - padLeft
```
public static String padLeft(String str,
                             int len,
                             char c)
```
    Pads a string that is < N characters by adding the specified character on the left side. Treats null as a zero-length string (ie, returned string will just consist of padding).
  - padRight
```
public static String padRight(String str,
                              int len,
                              char c)
```
    Pads a string that is < N characters by adding the specified character on the right side. Treats null as a zero-length string (ie, returned string will just consist of padding).
  - contains
```
public static boolean contains(String str,
                               String segment)
```
    Determines whether the first string contains the second.
    Returns true if the second string is an empty string or the two strings are equal. Returns false if either of the strings are null. Does not care how many times the second string appears in the first; only that it appears.
  - containsIgnoreCase
```
public static boolean containsIgnoreCase(String str,
                                         String segment)
```
    Determines whether the first string contains the second, ignoring case of individual letters.
    Returns true if the second string is an empty string or the two strings are equal. Returns false if either of the strings are null. Does not care how many times the second string appears in the first; only that it appears.
  - repeat
```
public static String repeat(char c,
                            int count)
```
    Creates a string that consists of a single character, repeated N times.
  - toUTF8
```
public static byte[] toUTF8(String str)
```
    Converts the string to a UTF-8 byte array, turning the checked exception (which should never happen) into a runtime exception.
    If passed null, returns an empty array.
  - fromUTF8
```
public static String fromUTF8(byte[] bytes)
```
    Converts the passed byte array to a string, using UTF-8 encoding, and turning the checked exception (which should never happen) into a runtime exception.
    If passed null, returns an empty string.
  - unicodeEscape
```
public static String unicodeEscape(String src)
```
    Escapes the passed string, replacing all characters outside the range 32..126, as well as quotes and backslashes, with unicode escapes. This is useful for strings written by a code generator.
    If passed null, returns null.
  - unescape
```
public static String unescape(String src)
```
    Un-escapes the passed string, replacing the standard slash escapes with their corresponding unicode character value.
  - parseDigit
```
public static int parseDigit(char c,
                             int base)
```
    Parses the passed character as a digit in the specified base, returning its value. Bases > 10 are represented by ASCII letters in the range A to Z (or a to z). Base 36 is the largest supported.
    
    Returns:
    
    The value, or -1 if the character is not a valid digit in the specified base (this method will typically be used in a loop, so no good reason to force exception checking).
  - intern
```
public static String intern(String str)
```
    Interns a string using a static instance of StringCanon. This is often more useful than creating a task-specific instance.
  - randomString
```
public static String randomString(String chars,
                                  int minLength,
                                  int maxLength)
```
    Generates a (non-cryptographicaly-) random string consisting of characters from the passed string. Useful for generating bogus string fields.
    Warning: not threadsafe; uses a shared instance of java.util.Random.
    
    Parameters:
    
    chars - Defines the set of characters used to create the returned string.
    
    minLength - Minimum length of the returned string.
    
    maxLength - Maximum length of the returned string.
  - randomAlphaString
```
public static String randomAlphaString(int minLength,
                                       int maxLength)
```
    Generates a string containing (non-cryptographicaly-) random ASCII alphabetic characters (A-Za-z). Useful for generating bogus string fields.
    Warning: not threadsafe; uses a shared instance of java.util.Random.
    
    Parameters:
    
    minLength - Minimum length of the returned string.
    
    maxLength - Maximum length of the returned string.
  - extractLeft
```
public static String extractLeft(String source,
                                 String target)
```
    Returns a substring of the source string, from its start up to but not including the first occurrence of the target string. If the target does not exist in the source, returns the source string. If the source or target strings are null, they are treated as empty strings (and an empty target will not exist in the source).
    This method is used to divide a string based on an optional delimiter; for example, dividing "host:port" at ":".
    See also extractLeftOfLast(java.lang.String, java.lang.String).
    
    Since:
    
    1.0.6
  - extractRight
```
public static String extractRight(String source,
                                  String target)
```
    Returns a substring of the source string, from immediately after the first occurrence of the target string, to the end of the source. If the target does not exist in the source, returns an empty string. If the source or target strings are null, they are treated as empty strings (and an empty target will not exist in the source).
    This method is used to divide a string based on an optional delimiter; for example, dividing "host:port" at ":".
    See also extractRightOfLast(java.lang.String, java.lang.String).
    
    Since:
    
    1.0.6
  - extractLeftOfLast
```
public static String extractLeftOfLast(String source,
                                       String target)
```
    Returns a substring of the source string, from its start up to but not including the last occurrence of the target string. If the target does not exist in the source, returns the source string. If the source or target strings are null, they are treated as empty strings (and an empty target will not exist in the source).
    This method is used to incrementally partition a string, for example, extracting components from a filepath (eg: "/foo/bar/baz.txt", with a target of "/" results in "/foo/bar").
    See also extractLeft(java.lang.String, java.lang.String).
    
    Since:
    
    1.0.6
  - extractRightOfLast
```
public static String extractRightOfLast(String source,
                                        String target)
```
    Returns a substring of the source string, from immediately after the last occurrence of the target string, to the end of the source. If the target does not exist in the source, returns an empty string. If the source or target strings are null, they are treated as empty strings (and an empty target will not exist in the source).
    This method is used to incrementally partition a string, for example, extracting components from a filepath (eg: "/foo/bar/baz.txt", with a target of "/" results in "baz.txt").
    See also extractRight(java.lang.String, java.lang.String).
    
    Since:
    
    1.0.6
  - substr
```
public static String substr(String src,
                            int off,
                            int len)
```
    A flexible substring that can return left or right substrings, and returns a "best effort" result if offset or length are outside the bounds of the string.
    
    Parameters:
    
    src - The source string; null is treated as an empty string.
    
    off - The starting offset of the substring. If negative, offset is measured from the end of the string (where -1 is the last character).
    
    Returns:
    
    A string containing up to len characters.
    
    Since:
    
    1.0.15
  - isIn
```
public static boolean isIn(String str,
                           String... targets)
```
    Returns true if the passed string is equal to one of the target strings, false otherwise. This will typically be invoked with a variable str and literal values for target.
  - valueOf
```
public static String valueOf(Object obj)
```
    A replacement for String.valueOf() that returns an empty string for null.

Class StringUtil

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

StringUtil

Method Detail

length

equalOrEmpty

lastChar

isEmpty

isBlank

trim

trimToNull

padLeft

padRight

contains

containsIgnoreCase

repeat

toUTF8

fromUTF8

unicodeEscape

unescape

parseDigit

intern

randomString

randomAlphaString

extractLeft

extractRight

extractLeftOfLast

extractRightOfLast

substr

isIn

valueOf