Strings (Java Utilities 2.4 API)

java.lang.Object
- net.pwall.util.Strings

```
public class Strings
extends Object
```
String utility functions.

Author:

Peter Wall

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`append2Digits(Appendable a, int i)` Append an `int` to an `Appendable` as two decimal digits.
`static void`	`append3Digits(Appendable a, int i)` Append an `int` to an `Appendable` as three decimal digits.
`static Appendable`	`appendEnglish(Appendable a, int n)` Append a number converted to words in English to an `Appendable`.
`static void`	`appendEscaped(Appendable a, CharSequence s, CharMapper mapper)` Append characters to an `Appendable`, mapping them to their "escaped" equivalents specified in the provided `CharMapper` instance.
`static void`	`appendEscaped(Appendable a, CharSequence s, int index, int end, CharMapper mapper)` Append characters to an `Appendable`, mapping them to their "escaped" equivalents specified in the provided `CharMapper` instance.
`static void`	`appendEscapedUTF16(Appendable a, CharSequence s, CharMapper mapper)` Append characters to an `Appendable`, mapping them to their "escaped" equivalents specified in the provided `CharMapper` instance.
`static void`	`appendEscapedUTF16(Appendable a, CharSequence s, int index, int end, CharMapper mapper)` Append characters to an `Appendable`, mapping them to their "escaped" equivalents specified in the provided `CharMapper` instance.
`static void`	`appendHex(Appendable a, byte b)` Append a byte value as hexadecimal to an `Appendable`.
`static void`	`appendHex(Appendable a, char ch)` Append a character value as hexadecimal to an `Appendable`.
`static void`	`appendHex(Appendable a, int i)` Append an integer value as hexadecimal to an `Appendable`.
`static void`	`appendHex(Appendable a, int i, int digits)` Append an integer value as hexadecimal to an `Appendable`, specifying the number of output digits.
`static void`	`appendHex(Appendable a, long n)` Append a long value as hexadecimal to an `Appendable`.
`static void`	`appendHex(Appendable a, long n, int digits)` Append a long value as hexadecimal to an `Appendable`, specifying the number of output digits.
`static void`	`appendInt(Appendable a, int i)` Append an `int` to an `Appendable`.
`static void`	`appendLong(Appendable a, long n)` Append a `long` to an `Appendable`.
`static void`	`appendPositiveInt(Appendable a, int i)` Append a positive `int` to an `Appendable`.
`static void`	`appendPositiveLong(Appendable a, long n)` Append a positive `long` to an `Appendable`.
`static void`	`appendUTF16(Appendable a, int codePoint)` Append a Unicode code point to an `Appendable`.
`static void`	`appendUTF8(ByteArrayBuilder bab, int codepoint)` Append a codepoint to a `ByteArrayBuilder` as UTF-8.
`static StringBuilder`	`build()` Convenience method to create a `StringBuilder`.
`static StringBuilder`	`build(CharSequence cs)` Convenience method to create a `StringBuilder`.
`static String`	`capitalise(String str)` Capitalise the first letter of a string.
`static int`	`convertDecDigit(char ch)` Convert a decimal digit to the integer value of the digit.
`static int`	`convertHexDigit(char ch)` Convert a hexadecimal digit to the integer value of the digit.
`static int`	`convertHexToInt(CharSequence text, int start, int end)` Convert a group of hexadecimal digits in a `CharSequence` to an `int`.
`static long`	`convertHexToLong(CharSequence text, int start, int end)` Convert a group of hexadecimal digits in a `CharSequence` to a `long`.
`static int`	`convertToInt(CharSequence text, int start, int end)` Convert a group of digits in a `CharSequence` to an `int`.
`static long`	`convertToLong(CharSequence text, int start, int end)` Convert a group of digits in a `CharSequence` to a `long`.
`static CharSequence`	`escape(CharSequence s, CharMapper mapper)` Replace certain characters in a `CharSequence` with their mapped equivalents, as specified in the provided `CharMapper` instance.
`static String`	`escape(String s, CharMapper mapper)` Replace certain characters in a string with their mapped equivalents, as specified in the provided `CharMapper` instance.
`static CharSequence`	`escapeUTF16(CharSequence s, CharMapper mapper)` Replace certain characters in a `CharSequence` with their mapped equivalents, as specified in the provided `CharMapper` instance.
`static String`	`escapeUTF16(String s, CharMapper mapper)` Replace certain characters in a string with their mapped equivalents, as specified in the provided `CharMapper` instance.
`static String`	`fromUTF8(byte[] bytes)` Convert a byte array from UTF-8 encoding to a UTF-16 string.
`static String`	`fromUTF8(byte[] bytes, int start, int end)` Convert a portion of a byte array from UTF-8 encoding to a UTF-16 string.
`static String`	`fromUTF8(ByteBuffer byteBuffer)` Convert a sequence of bytes in a `ByteBuffer` from UTF-8 encoding to a UTF-16 string.
`static String`	`fromUTF8(ByteBuffer[] byteBuffers)` Convert a sequence of bytes in an array of `ByteBuffer`s from UTF-8 encoding to a UTF-16 string.
`static String`	`fromUTF8(Iterator<Byte> byteIterator)` Convert a sequence of bytes described by an `Iterator` from UTF-8 encoding to a UTF-16 string.
`static <E> String`	`join(E[] array)` Join the string representations of the members of an array.
`static <E> String`	`join(E[] array, char separator)` Join the string representations of the members of an array, with the specified character separator.
`static <E> String`	`join(E[] array, String separator)` Join the string representations of the members of an array, with the specified string separator.
`static <E> String`	`join(Enumeration<E> e)` Join the string representations of the members of an `Enumeration`.
`static <E> String`	`join(Enumeration<E> e, char separator)` Join the string representations of the members of an `Enumeration`, with the specified character separator.
`static <E> String`	`join(Enumeration<E> e, String separator)` Join the string representations of the members of an `Enumeration`, with the specified string separator.
`static <E> String`	`join(Iterable<E> collection)` Join the string representations of the members of a collection.
`static <E> String`	`join(Iterable<E> collection, char separator)` Join the string representations of the members of a collection, with the specified character separator.
`static <E> String`	`join(Iterable<E> collection, String separator)` Join the string representations of the members of a collection, with the specified string separator.
`static <E> String`	`join(Iterator<E> it)` Join the string representations of the members of an `Iterator`.
`static <E> String`	`join(Iterator<E> it, char separator)` Join the string representations of the members of an `Iterator`, with the specified character separator.
`static <E> String`	`join(Iterator<E> it, String separator)` Join the string representations of the members of an `Iterator`, with the specified string separator.
`static boolean`	`multiWildcardCompare(String pattern, CharSequence target)` Perform multi-wildcard comparison.
`static String`	`plural(String noun, int n)` Create a string consisting of a number, space, and the singular or plural form of a given noun (using standard English plural forms, i.e. add the letter "s").
`static String`	`plural(String singularNoun, String pluralNoun, int n)` Create a string consisting of a number, space, and the singular or plural noun (for use with irregular plurals).
`static String[]`	`split(String s)` Split a string into white space delimited tokens, where white space is determined by `Character.isWhitespace(char)`.
`static String[]`	`split(String s, char separator)` Split a string on a given separator.
`static String[]`	`split(String s, char separator, boolean skipEmpty, IntPredicate spaceTest)` Split a string on a given separator character.
`static String[]`	`split(String s, int start, int end)` Split a portion of a string into white space delimited tokens, where white space is determined by `Character.isWhitespace(char)`.
`static String[]`	`split(String s, int start, int end, char separator, boolean skipEmpty, IntPredicate spaceTest)` Split a portion of a string on a given separator character.
`static String[]`	`split(String s, int start, int end, IntPredicate spaceTest)` Split a portion of a string into white space delimited tokens, where white space is determined by a supplied `IntPredicate` function.
`static String[]`	`split(String s, IntPredicate spaceTest)` Split a string into white space delimited tokens, where white space is determined by a supplied `IntPredicate` function.
`static String[]`	`split(String s1, String s2)` Split a string on a given string separator.
`static CharSequence`	`strip(CharSequence cs, IntPredicate test)` Strip characters from a `CharSequence`, where those characters match a supplied `IntPredicate` function.
`static String`	`strip(String s, IntPredicate test)` Strip characters from a string, where those characters match a supplied `IntPredicate` function.
`static String`	`stripUTF16(String s, IntPredicate test)` Strip code points from a UTF16 string, where those code points match a supplied `IntPredicate` function.
`static String`	`toEnglish(int n)` Convert a number to words in English.
`static String`	`toHex(byte b)` Convert a byte to hexadecimal.
`static String`	`toHex(byte[] bytes)` Convert a byte array to hexadecimal.
`static String`	`toHex(byte[] bytes, char separator)` Convert a byte array to hexadecimal, with a separator between bytes for easier reading.
`static String`	`toHex(char ch)` Convert a character to hexadecimal.
`static String`	`toHex(CharSequence s)` Convert a `CharSequence` to hexadecimal.
`static String`	`toHex(CharSequence s, char separator)` Convert a `CharSequence` to hexadecimal, with a separator between bytes for easier reading.
`static String`	`toHex(int i)` Convert an integer to hexadecimal.
`static String`	`toHex(long n)` Convert a long to hexadecimal.
`static String`	`toIdentifier(int i)` Convert an integer to a spreadsheet-style column identifier ("A", "B", ...
`static String`	`toUTF16(int codePoint)` Convert a Unicode code point to a one- or two-character string.
`static String`	`toUTF16(int[] codePoints)` Convert an array of Unicode code points to a string.
`static byte[]`	`toUTF8(String str)` Convert a string to UTF-8 encoding.
`static byte[]`	`toUTF8(String str, int start, int end)` Convert a portion of a string to UTF-8 encoding.
`static CharSequence`	`trim(CharSequence cs)` Trim leading and trailing whitespace from a `CharSequence`, where white space is determined by `Character.isWhitespace(char)`.
`static CharSequence`	`trim(CharSequence cs, IntPredicate test)` Trim leading and trailing characters from a `CharSequence`, where those characters match a supplied `IntPredicate` function.
`static String`	`trim(String s)` Trim leading and trailing whitespace from a string, where white space is determined by `Character.isWhitespace(char)`.
`static String`	`trim(String s, IntPredicate test)` Trim leading and trailing characters from a string, where those characters match a supplied `IntPredicate` function.
`static CharSequence`	`trimLeading(CharSequence cs)` Trim leading whitespace from a `CharSequence`, where white space is determined by `Character.isWhitespace(char)`.
`static CharSequence`	`trimLeading(CharSequence cs, IntPredicate test)` Trim leading characters from a `CharSequence`, where those characters match a supplied `IntPredicate` function.
`static String`	`trimLeading(String s)` Trim leading whitespace from a string, where white space is determined by `Character.isWhitespace(char)`.
`static String`	`trimLeading(String s, IntPredicate test)` Trim leading characters from a string, where those characters match a supplied `IntPredicate` function.
`static CharSequence`	`trimTrailing(CharSequence cs)` Trim trailing whitespace from a `CharSequence`, where white space is determined by `Character.isWhitespace(char)`.
`static CharSequence`	`trimTrailing(CharSequence cs, IntPredicate test)` Trim leading characters from a `CharSequence`, where those characters match a supplied `IntPredicate` function.
`static String`	`trimTrailing(String s)` Trim trailing whitespace from a string, where white space is determined by `Character.isWhitespace(char)`.
`static String`	`trimTrailing(String s, IntPredicate test)` Trim trailing characters from a string, where those characters match a supplied `IntPredicate` function.
`static String`	`trimUTF16(String s, IntPredicate test)` Trim leading and trailing code points from a UTF16 string, where those code points match a supplied `IntPredicate` function.
`static CharSequence`	`unescape(CharSequence s, CharUnmapper unmapper)` Scan a `CharSequence` for escape sequences and replace them by the original characters.
`static String`	`unescape(String s, CharUnmapper unmapper)` Scan a string for escape sequences and replace them by the original characters.
`static boolean`	`wildcardCompare(String pattern, CharSequence target)` Perform wildcard comparison.
`static boolean`	`wildcardCompare(String pattern, int patIndex, int patEnd, CharSequence target)` Perform wildcard comparison.

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

- Method Detail
  - toEnglish
```
public static String toEnglish(int n)
```
    Convert a number to words in English.
    
    Parameters:
    
    n - the number
    
    Returns:
    
    a string containing the number in words
  - appendEnglish
```
public static Appendable appendEnglish(Appendable a,
                                       int n)
                                throws IOException
```
    Append a number converted to words in English to an Appendable.
    
    Parameters:
    
    a - the Appendable
    
    n - the number
    
    Returns:
    
    the Appendable (for chaining)
    
    Throws:
    
    IOException - if thrown by the Appendable
  - capitalise
```
public static String capitalise(String str)
```
    Capitalise the first letter of a string. If the first character is not a lower-case letter the string is returned unmodified.
    
    Parameters:
    
    str - the input string
    
    Returns:
    
    the string, with the first letter capitalised
  - plural
```
public static String plural(String noun,
                            int n)
```
    Create a string consisting of a number, space, and the singular or plural form of a given noun (using standard English plural forms, i.e. add the letter "s"). For example:
```
     Strings.plural("file", 23);
 
```
    will return:
```
     "23 files"
 
```
    Parameters:
    
    noun - the noun
    
    n - the number
    
    Returns:
    
    the string
  - plural
```
public static String plural(String singularNoun,
                            String pluralNoun,
                            int n)
```
    Create a string consisting of a number, space, and the singular or plural noun (for use with irregular plurals). For example:
```
     Strings.plural("axis", "axes", 2);
 
```
    will return:
```
     "2 axes"
 
```
    Parameters:
    
    singularNoun - the singular noun
    
    pluralNoun - the plural noun
    
    n - the number
    
    Returns:
    
    the string
  - split
```
public static String[] split(String s)
```
    Split a string into white space delimited tokens, where white space is determined by Character.isWhitespace(char).
    
    Parameters:
    
    s - the string to be split
    
    Returns:
    
    an array of tokens (possibly empty)
    
    Throws:
    
    NullPointerException - if the input string is null
  - split
```
public static String[] split(String s,
                             int start,
                             int end)
```
    Split a portion of a string into white space delimited tokens, where white space is determined by Character.isWhitespace(char).
    
    Parameters:
    
    s - the string to be split
    
    start - the start index of the portion to be examined
    
    end - the end index (exclusive) of the portion to be examined
    
    Returns:
    
    an array of tokens (possibly empty)
    
    Throws:
    
    NullPointerException - if the input string is null
    
    IndexOutOfBoundsException - if start or end is invalid
  - split
```
public static String[] split(String s,
                             IntPredicate spaceTest)
```
    Split a string into white space delimited tokens, where white space is determined by a supplied IntPredicate function. In lambda notation, this may be called by:
```
     String[] array = Strings.split("a b c d e", Character::isWhitespace);
 
```
    Parameters:
    
    s - the string to be split
    
    spaceTest - the space test function
    
    Returns:
    
    an array of tokens (possibly empty)
    
    Throws:
    
    NullPointerException - if the input string is null
  - split
```
public static String[] split(String s,
                             int start,
                             int end,
                             IntPredicate spaceTest)
```
    Split a portion of a string into white space delimited tokens, where white space is determined by a supplied IntPredicate function.
    
    Parameters:
    
    s - the string to be split
    
    start - the start index of the portion to be examined
    
    end - the end index (exclusive) of the portion to be examined
    
    spaceTest - the space test function
    
    Returns:
    
    an array of tokens (possibly empty)
    
    Throws:
    
    NullPointerException - if the input string is null
    
    IndexOutOfBoundsException - if start or end is invalid
  - split
```
public static String[] split(String s1,
                             String s2)
```
    Split a string on a given string separator.
    
    Parameters:
    
    s1 - the string to be split
    
    s2 - the separator
    
    Returns:
    
    an array of items (possibly empty)
    
    Throws:
    
    NullPointerException - if either string is null
  - split
```
public static String[] split(String s,
                             char separator)
```
    Split a string on a given separator.
    
    Parameters:
    
    s - the string to be split
    
    separator - the separator
    
    Returns:
    
    an array of items (possibly empty)
    
    Throws:
    
    NullPointerException - if the input string is null
  - split
```
public static String[] split(String s,
                             char separator,
                             boolean skipEmpty,
                             IntPredicate spaceTest)
```
    Split a string on a given separator character. Spaces may optionally be trimmed from both ends of the items using the supplied space test, and zero-length items (after optional trimming) may optionally be dropped.
    
    Parameters:
    
    s - the string to be split
    
    separator - the separator
    
    skipEmpty - if true, ignore zero-length items (possibly after trimming)
    
    spaceTest - if not null, use to trim spaces off both ends of each item
    
    Returns:
    
    an array of items (possibly empty)
    
    Throws:
    
    NullPointerException - if the input string is null
  - split
```
public static String[] split(String s,
                             int start,
                             int end,
                             char separator,
                             boolean skipEmpty,
                             IntPredicate spaceTest)
```
    Split a portion of a string on a given separator character. Spaces may optionally be trimmed from both ends of the items using the supplied space test, and zero-length items (after optional trimming) may optionally be dropped.
    
    Parameters:
    
    s - the string to be split
    
    start - the start index of the portion to be examined
    
    end - the end index (exclusive) of the portion to be examined
    
    separator - the separator
    
    skipEmpty - if true, ignore zero-length items (possibly after trimming)
    
    spaceTest - if not null, use to trim spaces off both ends of each item
    
    Returns:
    
    an array of items (possibly empty)
    
    Throws:
    
    NullPointerException - if the input string is null
    
    IndexOutOfBoundsException - if start or end is invalid
  - join
```
public static <E> String join(Iterable<E> collection)
```
    Join the string representations of the members of a collection.
    
    Type Parameters:
    
    E - class of collection item
    
    Parameters:
    
    collection - the collection (strictly speaking, an Iterable)
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the collection is empty)
  - join
```
public static <E> String join(Iterator<E> it)
```
    Join the string representations of the members of an Iterator.
    
    Type Parameters:
    
    E - class of collection item
    
    Parameters:
    
    it - the Iterator
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the Iterator has no members)
  - join
```
public static <E> String join(Enumeration<E> e)
```
    Join the string representations of the members of an Enumeration.
    
    Type Parameters:
    
    E - class of collection item
    
    Parameters:
    
    e - the Enumeration
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the Enumeration has no members)
  - join
```
public static <E> String join(E[] array)
```
    Join the string representations of the members of an array.
    
    Type Parameters:
    
    E - class of array item
    
    Parameters:
    
    array - the array
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the array is empty)
  - join
```
public static <E> String join(Iterable<E> collection,
                              char separator)
```
    Join the string representations of the members of a collection, with the specified character separator.
    
    Type Parameters:
    
    E - class of collection item
    
    Parameters:
    
    collection - the collection (strictly speaking, an Iterable)
    
    separator - the separator
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the collection is empty)
  - join
```
public static <E> String join(Iterator<E> it,
                              char separator)
```
    Join the string representations of the members of an Iterator, with the specified character separator.
    
    Type Parameters:
    
    E - class of collection item
    
    Parameters:
    
    it - the Iterator
    
    separator - the separator
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the Iterator has no members)
  - join
```
public static <E> String join(Enumeration<E> e,
                              char separator)
```
    Join the string representations of the members of an Enumeration, with the specified character separator.
    
    Type Parameters:
    
    E - class of collection item
    
    Parameters:
    
    e - the Enumeration
    
    separator - the separator
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the Enumeration has no members)
  - join
```
public static <E> String join(E[] array,
                              char separator)
```
    Join the string representations of the members of an array, with the specified character separator.
    
    Type Parameters:
    
    E - class of array item
    
    Parameters:
    
    array - the array
    
    separator - the separator
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the array is empty)
  - join
```
public static <E> String join(Iterable<E> collection,
                              String separator)
```
    Join the string representations of the members of a collection, with the specified string separator.
    
    Type Parameters:
    
    E - class of collection item
    
    Parameters:
    
    collection - the collection (strictly speaking, an Iterable)
    
    separator - the separator
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the collection is empty)
  - join
```
public static <E> String join(Iterator<E> it,
                              String separator)
```
    Join the string representations of the members of an Iterator, with the specified string separator.
    
    Type Parameters:
    
    E - class of collection item
    
    Parameters:
    
    it - the Iterator
    
    separator - the separator
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the Iterator has no members)
  - join
```
public static <E> String join(Enumeration<E> e,
                              String separator)
```
    Join the string representations of the members of an Enumeration, with the specified string separator.
    
    Type Parameters:
    
    E - class of collection item
    
    Parameters:
    
    e - the Enumeration
    
    separator - the separator
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the Enumeration has no members)
  - join
```
public static <E> String join(E[] array,
                              String separator)
```
    Join the string representations of the members of an array, with the specified string separator.
    
    Type Parameters:
    
    E - class of array item
    
    Parameters:
    
    array - the array
    
    separator - the separator
    
    Returns:
    
    the concatenation of the string representations of the members (an empty string if the array is empty)
  - escape
```
public static String escape(String s,
                            CharMapper mapper)
```
    Replace certain characters in a string with their mapped equivalents, as specified in the provided CharMapper instance. If the string contains no characters to be mapped, the original string is returned unmodified.
    
    Parameters:
    
    s - the string to be converted
    
    mapper - the CharMapper instance
    
    Returns:
    
    the string with characters mapped as required
  - escape
```
public static CharSequence escape(CharSequence s,
                                  CharMapper mapper)
```
    Replace certain characters in a CharSequence with their mapped equivalents, as specified in the provided CharMapper instance. If the sequence contains no characters to be mapped, the original sequence is returned unmodified.
    
    Parameters:
    
    s - the CharSequence to be converted
    
    mapper - the CharMapper instance
    
    Returns:
    
    the sequence with characters mapped as required
  - appendEscaped
```
public static void appendEscaped(Appendable a,
                                 CharSequence s,
                                 int index,
                                 int end,
                                 CharMapper mapper)
                          throws IOException
```
    Append characters to an Appendable, mapping them to their "escaped" equivalents specified in the provided CharMapper instance.
    
    Parameters:
    
    a - the Appendable (e.g. a StringBuilder)
    
    s - the source CharSequence
    
    index - the start index within the source
    
    end - the end index within the source
    
    mapper - the CharMapper
    
    Throws:
    
    IOException - if thrown by the Appendable
  - appendEscaped
```
public static void appendEscaped(Appendable a,
                                 CharSequence s,
                                 CharMapper mapper)
                          throws IOException
```
    Append characters to an Appendable, mapping them to their "escaped" equivalents specified in the provided CharMapper instance.
    
    Parameters:
    
    a - the Appendable (e.g. a StringBuilder)
    
    s - the source CharSequence
    
    mapper - the CharMapper
    
    Throws:
    
    IOException - if thrown by the Appendable
  - escapeUTF16
```
public static String escapeUTF16(String s,
                                 CharMapper mapper)
```
    Replace certain characters in a string with their mapped equivalents, as specified in the provided CharMapper instance. Surrogate sequences are converted to Unicode code points before mapping. If the string contains no characters to be mapped, the original string is returned unmodified.
    
    Parameters:
    
    s - the UTF16 string to be converted
    
    mapper - the CharMapper instance
    
    Returns:
    
    the string with characters mapped as required
  - escapeUTF16
```
public static CharSequence escapeUTF16(CharSequence s,
                                       CharMapper mapper)
```
    Replace certain characters in a CharSequence with their mapped equivalents, as specified in the provided CharMapper instance. Surrogate sequences are converted to Unicode code points before mapping. If the sequence contains no characters to be mapped, the original sequence is returned unmodified.
    
    Parameters:
    
    s - the CharSequence to be converted
    
    mapper - the CharMapper instance
    
    Returns:
    
    the sequence with characters mapped as required
  - appendEscapedUTF16
```
public static void appendEscapedUTF16(Appendable a,
                                      CharSequence s,
                                      int index,
                                      int end,
                                      CharMapper mapper)
                               throws IOException
```
    Append characters to an Appendable, mapping them to their "escaped" equivalents specified in the provided CharMapper instance. Surrogate sequences are converted to Unicode code points before mapping.
    
    Parameters:
    
    a - the Appendable (e.g. a StringBuilder)
    
    s - the source CharSequence
    
    index - the start index within the source
    
    end - the end index within the source
    
    mapper - the CharMapper
    
    Throws:
    
    IOException - if thrown by the Appendable
  - appendEscapedUTF16
```
public static void appendEscapedUTF16(Appendable a,
                                      CharSequence s,
                                      CharMapper mapper)
                               throws IOException
```
    Append characters to an Appendable, mapping them to their "escaped" equivalents specified in the provided CharMapper instance. Surrogate sequences are converted to Unicode code points before mapping.
    
    Parameters:
    
    a - the Appendable (e.g. a StringBuilder)
    
    s - the source CharSequence
    
    mapper - the CharMapper
    
    Throws:
    
    IOException - if thrown by the Appendable
  - unescape
```
public static String unescape(String s,
                              CharUnmapper unmapper)
```
    Scan a string for escape sequences and replace them by the original characters. For example, in Java code the backslash character indicates the start of an escape sequence representing a character that may not appear in its raw form in a string. If the string contains no escape sequences to be unmapped, the original sequence is returned unmodified.
    
    Parameters:
    
    s - the string to be converted
    
    unmapper - an instance of the CharUnmapper class, which will perform the actual escape sequence mapping
    
    Returns:
    
    the "unescaped" string
  - unescape
```
public static CharSequence unescape(CharSequence s,
                                    CharUnmapper unmapper)
```
    Scan a CharSequence for escape sequences and replace them by the original characters. For example, in Java code the backslash character indicates the start of an escape sequence representing a character that may not appear in its raw form in a string.
    
    Parameters:
    
    s - the CharSequence to be converted
    
    unmapper - an instance of the CharUnmapper class, which will perform the actual escape sequence mapping
    
    Returns:
    
    the "unescaped" CharSequence
  - toUTF16
```
public static String toUTF16(int codePoint)
```
    Convert a Unicode code point to a one- or two-character string.
    
    Parameters:
    
    codePoint - the Unicode code point
    
    Returns:
    
    the string equivalent
  - toUTF16
```
public static String toUTF16(int[] codePoints)
```
    Convert an array of Unicode code points to a string.
    
    Parameters:
    
    codePoints - the Unicode code points
    
    Returns:
    
    the string equivalent
  - appendUTF16
```
public static void appendUTF16(Appendable a,
                               int codePoint)
                        throws IOException
```
    Append a Unicode code point to an Appendable. Code points outside the BMP are appended as surrogate sequences.
    
    Parameters:
    
    a - the Appendable (e.g. a StringBuilder)
    
    codePoint - the Unicode code point
    
    Throws:
    
    IOException - if thrown by the Appendable
  - toUTF8
```
public static byte[] toUTF8(String str)
```
    Convert a string to UTF-8 encoding.
    
    Parameters:
    
    str - the string
    
    Returns:
    
    the UTF-8 form of the string (as a byte array)
  - fromUTF8
```
public static String fromUTF8(byte[] bytes)
```
    Convert a byte array from UTF-8 encoding to a UTF-16 string.
    
    Parameters:
    
    bytes - the byte array
    
    Returns:
    
    the decoded string
    
    Throws:
    
    IllegalArgumentException - if the byte array is null, or if the byte array contains an invalid UTF-8 sequence
  - toUTF8
```
public static byte[] toUTF8(String str,
                            int start,
                            int end)
```
    Convert a portion of a string to UTF-8 encoding.
    
    Parameters:
    
    str - the string
    
    start - the start index
    
    end - the end index
    
    Returns:
    
    the UTF-8 form of the string (as a byte array)
    
    Throws:
    
    IllegalArgumentException - if the string is null, or if the string contains an invalid UTF-16 sequence
  - appendUTF8
```
public static void appendUTF8(ByteArrayBuilder bab,
                              int codepoint)
```
    Append a codepoint to a ByteArrayBuilder as UTF-8.
    
    Parameters:
    
    bab - the ByteArrayBuilder
    
    codepoint - the codepoint
  - fromUTF8
```
public static String fromUTF8(ByteBuffer byteBuffer)
```
    Convert a sequence of bytes in a ByteBuffer from UTF-8 encoding to a UTF-16 string.
    
    Parameters:
    
    byteBuffer - the ByteBuffer
    
    Returns:
    
    the decoded string
    
    Throws:
    
    IllegalArgumentException - if the byte array is null, if the start or end index is invalid, or if the byte array contains an invalid UTF-8 sequence
  - fromUTF8
```
public static String fromUTF8(ByteBuffer[] byteBuffers)
```
    Convert a sequence of bytes in an array of ByteBuffers from UTF-8 encoding to a UTF-16 string.
    
    Parameters:
    
    byteBuffers - the ByteBuffer array
    
    Returns:
    
    the decoded string
    
    Throws:
    
    IllegalArgumentException - if the byte array is null, if the start or end index is invalid, or if the byte array contains an invalid UTF-8 sequence
  - fromUTF8
```
public static String fromUTF8(Iterator<Byte> byteIterator)
```
    Convert a sequence of bytes described by an Iterator from UTF-8 encoding to a UTF-16 string.
    
    Parameters:
    
    byteIterator - an Iterator over a sequence of bytes
    
    Returns:
    
    the decoded string
    
    Throws:
    
    IllegalArgumentException - if the byte array is null, if the start or end index is invalid, or if the byte array contains an invalid UTF-8 sequence
  - fromUTF8
```
public static String fromUTF8(byte[] bytes,
                              int start,
                              int end)
```
    Convert a portion of a byte array from UTF-8 encoding to a UTF-16 string.
    
    Parameters:
    
    bytes - the byte array
    
    start - the start index
    
    end - the end index
    
    Returns:
    
    the decoded string
    
    Throws:
    
    IllegalArgumentException - if the byte array is null, if the start or end index is invalid, or if the byte array contains an invalid UTF-8 sequence
  - toHex
```
public static String toHex(CharSequence s)
```
    Convert a CharSequence to hexadecimal.
    
    Parameters:
    
    s - the CharSequence
    
    Returns:
    
    the converted string
    
    Throws:
    
    IllegalArgumentException - if the CharSequence is null
  - toHex
```
public static String toHex(CharSequence s,
                           char separator)
```
    Convert a CharSequence to hexadecimal, with a separator between bytes for easier reading.
    
    Parameters:
    
    s - the CharSequence
    
    separator - the separator
    
    Returns:
    
    the converted string
    
    Throws:
    
    IllegalArgumentException - if the CharSequence is null
  - toHex
```
public static String toHex(byte[] bytes)
```
    Convert a byte array to hexadecimal.
    
    Parameters:
    
    bytes - the byte array
    
    Returns:
    
    the converted string
    
    Throws:
    
    IllegalArgumentException - if the byte array is null
  - toHex
```
public static String toHex(byte[] bytes,
                           char separator)
```
    Convert a byte array to hexadecimal, with a separator between bytes for easier reading.
    
    Parameters:
    
    bytes - the byte array
    
    separator - the separator
    
    Returns:
    
    the converted string
    
    Throws:
    
    IllegalArgumentException - if the byte array is null
  - toHex
```
public static String toHex(byte b)
```
    Convert a byte to hexadecimal.
    
    Parameters:
    
    b - the byte
    
    Returns:
    
    the converted string
  - toHex
```
public static String toHex(char ch)
```
    Convert a character to hexadecimal.
    
    Parameters:
    
    ch - the character
    
    Returns:
    
    the converted string
  - toHex
```
public static String toHex(int i)
```
    Convert an integer to hexadecimal.
    
    Parameters:
    
    i - the integer
    
    Returns:
    
    the converted string
  - toHex
```
public static String toHex(long n)
```
    Convert a long to hexadecimal.
    
    Parameters:
    
    n - the number
    
    Returns:
    
    the converted string
  - appendHex
```
public static void appendHex(Appendable a,
                             byte b)
                      throws IOException
```
    Append a byte value as hexadecimal to an Appendable.
    
    Parameters:
    
    a - the Appendable
    
    b - the byte
    
    Throws:
    
    IOException - if thrown by the Appendable
  - appendHex
```
public static void appendHex(Appendable a,
                             char ch)
                      throws IOException
```
    Append a character value as hexadecimal to an Appendable.
    
    Parameters:
    
    a - the Appendable
    
    ch - the character
    
    Throws:
    
    IOException - if thrown by the Appendable
  - appendHex
```
public static void appendHex(Appendable a,
                             int i)
                      throws IOException
```
    Append an integer value as hexadecimal to an Appendable.
    
    Parameters:
    
    a - the Appendable
    
    i - the number
    
    Throws:
    
    IOException - if thrown by the Appendable
  - appendHex
```
public static void appendHex(Appendable a,
                             int i,
                             int digits)
                      throws IOException
```
    Append an integer value as hexadecimal to an Appendable, specifying the number of output digits.
    
    Parameters:
    
    a - the Appendable
    
    i - the number
    
    digits - the number of digits
    
    Throws:
    
    IOException - if thrown by the Appendable
  - appendHex
```
public static void appendHex(Appendable a,
                             long n)
                      throws IOException
```
    Append a long value as hexadecimal to an Appendable.
    
    Parameters:
    
    a - the Appendable
    
    n - the number
    
    Throws:
    
    IOException - if thrown by the Appendable
  - appendHex
```
public static void appendHex(Appendable a,
                             long n,
                             int digits)
                      throws IOException
```
    Append a long value as hexadecimal to an Appendable, specifying the number of output digits.
    
    Parameters:
    
    a - the Appendable
    
    n - the number
    
    digits - the number of digits
    
    Throws:
    
    IOException - if thrown by the Appendable
  - convertToInt
```
public static int convertToInt(CharSequence text,
                               int start,
                               int end)
```
    Convert a group of digits in a CharSequence to an int.
    
    Parameters:
    
    text - the CharSequence
    
    start - the start offset of the digits
    
    end - the end offset of the digits
    
    Returns:
    
    the result as an int
    
    Throws:
    
    IndexOutOfBoundsException - if start or end invalid
    
    NumberFormatException - if any digit is invalid, or if the value is too big for an int
  - convertToLong
```
public static long convertToLong(CharSequence text,
                                 int start,
                                 int end)
```
    Convert a group of digits in a CharSequence to a long.
    
    Parameters:
    
    text - the CharSequence
    
    start - the start offset of the digits
    
    end - the end offset of the digits
    
    Returns:
    
    the result as a long
    
    Throws:
    
    IndexOutOfBoundsException - if start or end invalid
    
    NumberFormatException - if any digit is invalid, or if the value is too big for a long
  - convertDecDigit
```
public static int convertDecDigit(char ch)
```
    Convert a decimal digit to the integer value of the digit.
    
    Parameters:
    
    ch - the decimal digit
    
    Returns:
    
    the integer value (0 - 9)
    
    Throws:
    
    NumberFormatException - if the digit is not valid
  - convertHexToInt
```
public static int convertHexToInt(CharSequence text,
                                  int start,
                                  int end)
```
    Convert a group of hexadecimal digits in a CharSequence to an int.
    
    Parameters:
    
    text - the CharSequence
    
    start - the start offset of the digits
    
    end - the end offset of the digits
    
    Returns:
    
    the result as an int
    
    Throws:
    
    IndexOutOfBoundsException - if start or end invalid
    
    NumberFormatException - if any digit is invalid, or if the value is too big for an int
  - convertHexToLong
```
public static long convertHexToLong(CharSequence text,
                                    int start,
                                    int end)
```
    Convert a group of hexadecimal digits in a CharSequence to a long.
    
    Parameters:
    
    text - the CharSequence
    
    start - the start offset of the digits
    
    end - the end offset of the digits
    
    Returns:
    
    the result as a long
    
    Throws:
    
    IndexOutOfBoundsException - if start or end invalid
    
    NumberFormatException - if any digit is invalid, or if the value is too big for a long
  - convertHexDigit
```
public static int convertHexDigit(char ch)
```
    Convert a hexadecimal digit to the integer value of the digit.
    
    Parameters:
    
    ch - the hexadecimal digit
    
    Returns:
    
    the integer value (0 - 15)
    
    Throws:
    
    NumberFormatException - if the digit is not valid
  - multiWildcardCompare
```
public static boolean multiWildcardCompare(String pattern,
                                           CharSequence target)
```
    Perform multi-wildcard comparison. The pattern string consists of multiple wildcard patterns (using ? for single character matches and * for multiple character matches) separated by vertical bar (logical or) characters. The comparison returns true if any of the patterns match the target.
    
    Parameters:
    
    pattern - the pattern string as described above
    
    target - the target CharSequence (String, StringBuilder, StringBuffer etc.)
    
    Returns:
    
    true if the target string matches the pattern
    
    See Also:
    
    wildcardCompare(String, int, int, CharSequence)
  - wildcardCompare
```
public static boolean wildcardCompare(String pattern,
                                      CharSequence target)
```
    Perform wildcard comparison. The method returns true if the target string matches the pattern, according to the common wildcard rules:
    
    “*”
    
    matches zero or more variable characters
    
    “?”
    
    matches a single variable character
    
    anything else
    
    matches the same character exactly
    
    Parameters:
    
    pattern - the pattern string, which may include wildcard characters as described above
    
    target - the target CharSequence (String, StringBuilder, StringBuffer etc.)
    
    Returns:
    
    true if the target string matches the pattern
  - wildcardCompare
```
public static boolean wildcardCompare(String pattern,
                                      int patIndex,
                                      int patEnd,
                                      CharSequence target)
```
    Perform wildcard comparison. The method returns true if the target string matches the pattern, according to the common wildcard rules:
    
    “*”
    
    matches zero or more variable characters
    
    “?”
    
    matches a single variable character
    
    anything else
    
    matches the same character exactly
    
    This version allows a substring of the pattern string to be specified, removing the necessity for a separate String.substring(int, int) operation.
    
    Parameters:
    
    pattern - the pattern string, which may include wildcard characters as described above
    
    patIndex - the start index within the pattern string
    
    patEnd - the end index within the pattern string
    
    target - the target CharSequence (String, StringBuilder, StringBuffer etc.)
    
    Returns:
    
    true if the target string matches the pattern
  - trim
```
public static String trim(String s,
                          IntPredicate test)
```
    Trim leading and trailing characters from a string, where those characters match a supplied IntPredicate function.
    
    Parameters:
    
    s - the string to be trimmed
    
    test - the test function
    
    Returns:
    
    the trimmed string
    
    Throws:
    
    NullPointerException - if either argument is null
  - trimLeading
```
public static String trimLeading(String s,
                                 IntPredicate test)
```
    Trim leading characters from a string, where those characters match a supplied IntPredicate function.
    
    Parameters:
    
    s - the string to be trimmed
    
    test - the test function
    
    Returns:
    
    the trimmed string
    
    Throws:
    
    NullPointerException - if either argument is null
  - trimTrailing
```
public static String trimTrailing(String s,
                                  IntPredicate test)
```
    Trim trailing characters from a string, where those characters match a supplied IntPredicate function.
    
    Parameters:
    
    s - the string to be trimmed
    
    test - the test function
    
    Returns:
    
    the trimmed string
    
    Throws:
    
    NullPointerException - if either argument is null
  - trim
```
public static CharSequence trim(CharSequence cs,
                                IntPredicate test)
```
    Trim leading and trailing characters from a CharSequence, where those characters match a supplied IntPredicate function.
    
    Parameters:
    
    cs - the CharSequence to be trimmed
    
    test - the test function
    
    Returns:
    
    the trimmed CharSequence
    
    Throws:
    
    NullPointerException - if either argument is null
  - trimLeading
```
public static CharSequence trimLeading(CharSequence cs,
                                       IntPredicate test)
```
    Trim leading characters from a CharSequence, where those characters match a supplied IntPredicate function.
    
    Parameters:
    
    cs - the CharSequence to be trimmed
    
    test - the test function
    
    Returns:
    
    the trimmed CharSequence
    
    Throws:
    
    NullPointerException - if either argument is null
  - trimTrailing
```
public static CharSequence trimTrailing(CharSequence cs,
                                        IntPredicate test)
```
    Trim leading characters from a CharSequence, where those characters match a supplied IntPredicate function.
    
    Parameters:
    
    cs - the CharSequence to be trimmed
    
    test - the test function
    
    Returns:
    
    the trimmed CharSequence
    
    Throws:
    
    NullPointerException - if either argument is null
  - trim
```
public static String trim(String s)
```
    Trim leading and trailing whitespace from a string, where white space is determined by Character.isWhitespace(char).
    
    Parameters:
    
    s - the string to be trimmed
    
    Returns:
    
    the trimmed string
    
    Throws:
    
    NullPointerException - if the input string is null
  - trimLeading
```
public static String trimLeading(String s)
```
    Trim leading whitespace from a string, where white space is determined by Character.isWhitespace(char).
    
    Parameters:
    
    s - the string to be trimmed
    
    Returns:
    
    the trimmed string
    
    Throws:
    
    NullPointerException - if the input string is null
  - trimTrailing
```
public static String trimTrailing(String s)
```
    Trim trailing whitespace from a string, where white space is determined by Character.isWhitespace(char).
    
    Parameters:
    
    s - the string to be trimmed
    
    Returns:
    
    the trimmed string
    
    Throws:
    
    NullPointerException - if the input string is null
  - trim
```
public static CharSequence trim(CharSequence cs)
```
    Trim leading and trailing whitespace from a CharSequence, where white space is determined by Character.isWhitespace(char).
    
    Parameters:
    
    cs - the CharSequence to be trimmed
    
    Returns:
    
    the trimmed CharSequence
    
    Throws:
    
    NullPointerException - if the input CharSequence is null
  - trimLeading
```
public static CharSequence trimLeading(CharSequence cs)
```
    Trim leading whitespace from a CharSequence, where white space is determined by Character.isWhitespace(char).
    
    Parameters:
    
    cs - the CharSequence to be trimmed
    
    Returns:
    
    the trimmed CharSequence
    
    Throws:
    
    NullPointerException - if the input CharSequence is null
  - trimTrailing
```
public static CharSequence trimTrailing(CharSequence cs)
```
    Trim trailing whitespace from a CharSequence, where white space is determined by Character.isWhitespace(char).
    
    Parameters:
    
    cs - the CharSequence to be trimmed
    
    Returns:
    
    the trimmed CharSequence
    
    Throws:
    
    NullPointerException - if the input CharSequence is null
  - trimUTF16
```
public static String trimUTF16(String s,
                               IntPredicate test)
```
    Trim leading and trailing code points from a UTF16 string, where those code points match a supplied IntPredicate function.
    
    Parameters:
    
    s - the string to be trimmed
    
    test - the test function
    
    Returns:
    
    the trimmed string
    
    Throws:
    
    NullPointerException - if either argument is null
  - strip
```
public static String strip(String s,
                           IntPredicate test)
```
    Strip characters from a string, where those characters match a supplied IntPredicate function.
    
    Parameters:
    
    s - the string to be stripped
    
    test - the test function
    
    Returns:
    
    the stripped string
    
    Throws:
    
    NullPointerException - if either argument is null
  - strip
```
public static CharSequence strip(CharSequence cs,
                                 IntPredicate test)
```
    Strip characters from a CharSequence, where those characters match a supplied IntPredicate function.
    
    Parameters:
    
    cs - the CharSequence to be stripped
    
    test - the test function
    
    Returns:
    
    the stripped CharSequence
    
    Throws:
    
    NullPointerException - if either argument is null
  - stripUTF16
```
public static String stripUTF16(String s,
                                IntPredicate test)
```
    Strip code points from a UTF16 string, where those code points match a supplied IntPredicate function.
    
    Parameters:
    
    s - the string to be stripped
    
    test - the test function
    
    Returns:
    
    the stripped string
    
    Throws:
    
    NullPointerException - if either argument is null
  - build
```
public static StringBuilder build()
```
    Convenience method to create a StringBuilder. Supports the idiom:
```
     String str = Strings.build().append('(').append(n).append(')').toString();
 
```
    Returns:
    
    the new StringBuilder
  - build
```
public static StringBuilder build(CharSequence cs)
```
    Convenience method to create a StringBuilder. Supports the idiom:
```
     String str = Strings.build("(").append(n).append(')').toString();
 
```
    Parameters:
    
    cs - the initial contents
    
    Returns:
    
    the new StringBuilder
  - toIdentifier
```
public static String toIdentifier(int i)
```
    Convert an integer to a spreadsheet-style column identifier ("A", "B", ... "Z", "AA" etc.).
    
    Parameters:
    
    i - the number to convert
    
    Returns:
    
    the identifier
  - appendInt
```
public static void appendInt(Appendable a,
                             int i)
                      throws IOException
```
    Append an int to an Appendable. This method outputs the digits left to right, avoiding the need to allocate a separate buffer.
    
    Parameters:
    
    a - the Appendable
    
    i - the int
    
    Throws:
    
    IOException - if thrown by the Appendable
  - appendPositiveInt
```
public static void appendPositiveInt(Appendable a,
                                     int i)
                              throws IOException
```
    Append a positive int to an Appendable. This method outputs the digits left to right, avoiding the need to allocate a separate buffer.
    
    Parameters:
    
    a - the Appendable
    
    i - the int
    
    Throws:
    
    IOException - if thrown by the Appendable
  - appendLong
```
public static void appendLong(Appendable a,
                              long n)
                       throws IOException
```
    Append a long to an Appendable. This method outputs the digits left to right, avoiding the need to allocate a separate buffer.
    
    Parameters:
    
    a - the Appendable
    
    n - the long
    
    Throws:
    
    IOException - if thrown by the Appendable
  - appendPositiveLong
```
public static void appendPositiveLong(Appendable a,
                                      long n)
                               throws IOException
```
    Append a positive long to an Appendable. This method outputs the digits left to right, avoiding the need to allocate a separate buffer.
    
    Parameters:
    
    a - the Appendable
    
    n - the long
    
    Throws:
    
    IOException - if thrown by the Appendable
  - append2Digits
```
public static void append2Digits(Appendable a,
                                 int i)
                          throws IOException
```
    Append an int to an Appendable as two decimal digits. There is often a requirement to output a number as 2 digits, for example the cents value in dollars and cents, or hours, minutes and seconds in a time string. Note that there is no range check on the input value; to use this method in cases where the value is not guaranteed to be in the range 00-99, use:
```
     Strings.append2Digits(a, Math.abs(i) % 100);
 
```
    Parameters:
    
    a - the Appendable
    
    i - the int
    
    Throws:
    
    IOException - if thrown by the Appendable
  - append3Digits
```
public static void append3Digits(Appendable a,
                                 int i)
                          throws IOException
```
    Append an int to an Appendable as three decimal digits. There is less frequently a requirement to output a number as 3 digits, for example the milliseconds in a time string. Note that there is no range check on the input value; to use this method in cases where the value is not guaranteed to be in the range 000-999, use:
```
     Strings.append3Digits(a, Math.abs(i) % 1000);
 
```
    Parameters:
    
    a - the Appendable
    
    i - the int
    
    Throws:
    
    IOException - if thrown by the Appendable

Class Strings

Method Summary

Methods inherited from class java.lang.Object

Method Detail

toEnglish

appendEnglish

capitalise

plural

plural

split

split

split

split

split

split

split

split

join

join

join

join

join

join

join

join

join

join

join

join

escape

escape

appendEscaped

appendEscaped

escapeUTF16

escapeUTF16

appendEscapedUTF16

appendEscapedUTF16

unescape

unescape

toUTF16

toUTF16

appendUTF16

toUTF8

fromUTF8

toUTF8

appendUTF8

fromUTF8

fromUTF8

fromUTF8

fromUTF8

toHex

toHex

toHex

toHex

toHex

toHex

toHex

toHex

appendHex

appendHex

appendHex

appendHex

appendHex

appendHex

convertToInt

convertToLong

convertDecDigit

convertHexToInt

convertHexToLong

convertHexDigit

multiWildcardCompare

wildcardCompare

wildcardCompare

trim

trimLeading

trimTrailing

trim

trimLeading

trimTrailing

trim