Package com.xmlmind.util

## Class StringUtil

- java.lang.Object
- - com.xmlmind.util.StringUtil

-     public final class StringUtil
      extends Object

  A collection of utility functions (static methods) operating on Strings.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String[]` | `EMPTY_LIST` | A ready-to-use empty list of Strings.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static String` | `capitalize​(String string)` | Returns the specified string with its first character converted to upper case.
    `static String` | `escape​(char c)` | Returns the `\\uXXXX` Java escape sequence corresponding to specified character.
    `static void` | `escape​(char c, StringBuilder buffer)` | Same as `escape(char)` expect that the `\\uXXXX` Java escape sequence is appended to specified buffer.
    `static String` | `escape​(String string)` | Returns the specified string with all non-ASCII characters and non-printable ASCII characters replaced by the corresponding Java escape sequences (that is `'\n'`, `'é'`, etc).
    `static void` | `escape​(String string, StringBuilder buffer)` | Same as `escape(String)` except that the escaped string is appended to specified buffer.
    `static String` | `join​(char separatorChar, String... strings)` | Equivalent to `join(Character.toString(separatorChar), strings)`.
    `static String` | `join​(String separator, String... strings)` | Joins the items of the specified list of Strings using specified separator.
    `static String` | `joinArguments​(String... args)` | Inverse operation of `splitArguments(java.lang.String)`.
    `static String` | `quote​(String string)` | Like `escape(java.lang.String)` but puts a double quote character (`'\"'`) around the escaped string.
    `static String` | `quoteArgument​(String arg)` | Quotes specified string using `'\"'` if needed to.
    `static String` | `replaceAll​(String string, String oldSub, String newSub)` | Replaces substring `oldSub` by substring `newSub` inside String `string`.
    `static String` | `shortenText​(String text, int maxLength)` | Returns specified text after ensuring that it's shorter than specified maximum length.
    `static String[]` | `split​(String s)` | Splits specified string at whitespace character boundaries.
    `static String[]` | `split​(String string, char separatorChar)` | Splits String `string` at occurrences of char `separatorChar`.
    `static String[]` | `splitArguments​(String string)` | Splits specified string in a manner which is similar to what is done for command line arguments.
    `static String` | `substituteVars​(String text, char[] names, Object[] values)` | Equivalent to `substituteVars(text, names, values, null, null, false)`.
    `static String` | `substituteVars​(String text, char[] names, Object[] values, String[] args, String allArgs)` | Equivalent to `substituteVars(text, names, values, args, allArgs, false)`.
    `static String` | `substituteVars​(String text, char[] names, Object[] values, String[] args, String allArgs, boolean allowForeignVars)` | Returns specified text where %0, %1, ..., %9, %* and %X, %Y, etc, variables have been subsituted by specified values.
    `static String` | `uncapitalize​(String string)` | Returns the specified string with its first character converted to lower case.
    `static String` | `unescape​(String string)` | Returns the specified string with Java escape sequences (that is `'\n'`, `'é'`, etc) replaced by the corresponding character.
    `static String` | `unquote​(String string)` | Like `unescape(java.lang.String)` but removes the double quote characters (`'\"'`), if any, before unescaping the string.
    `static String[]` | `wordWrap​(String text, int maxLineLength)` | Splits specified string at word boundaries, returning an array of lines having at most specified number of characters.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### EMPTY_LIST

          public static final String[] EMPTY_LIST

      A ready-to-use empty list of Strings.

  - ### Method Detail

    - #### split

          public static String[] split​(String s)

      Splits specified string at whitespace character boundaries. Returns list of parts.
      Parameters:
        `s` - string to be split
      Returns:
        list of parts

    - #### split

          public static String[] split​(String string,
                                       char separatorChar)

      Splits String `string` at occurrences of char `separatorChar`.
      Parameters:
        `string` - the String to be split
        `separatorChar` - the char where to split
      Returns:
        the list of substrings resulting from splitting String `string` at occurrences of char `separatorChar`.

        Note that each occurrence of `separatorChar` specifies the end of a substring. Therefore, the returned list may contain empty substrings if consecutive `separatorChar`s are found in String `string`.

        However, for consistency with all the other split methods, this method returns an empty array for the empty string.

    - #### join

          public static String join​(char separatorChar,
                                    String... strings)

      Equivalent to `join(Character.toString(separatorChar), strings)`.

    - #### join

          public static String join​(String separator,
                                    String... strings)

      Joins the items of the specified list of Strings using specified separator.
      Parameters:
        `separator` - the string used to join items
        `strings` - the list where items are to be joined
      Returns:
        a string where all list items have been joined

    - #### shortenText

          public static String shortenText​(String text,
                                           int maxLength)

      Returns specified text after ensuring that it's shorter than specified maximum length.

      If specified text is longer than specified maximum length, excess characters are removed from the middle of the text and replaced by a single ellipsis character (`U+2026`).

    - #### wordWrap

          public static final String[] wordWrap​(String text,
                                                int maxLineLength)

      Splits specified string at word boundaries, returning an array of lines having at most specified number of characters.
      Parameters:
        `text` - string to be split at word boundaries
        `maxLineLength` - the number of characters contained in a line should not exceed this value
      Returns:
        a (possibly empty) array of lines

    - #### splitArguments

          public static String[] splitArguments​(String string)

      Splits specified string in a manner which is similar to what is done for command line arguments. Returns the list of ``command line arguments''.

      Example: returns `{"one", "two", "three", " \"four\" ", " 'five' "}` for input string:

          one   "two"    'three'   " \"four\" "   " 'five' "

      Note that escaped sequences such as "\n" and "\t" contained in specified string are left as is. The reason for this is that specified string may contain any whitespace character including '\n' and '\t', provided that these characters are contained in a quoted argument.

    - #### joinArguments

          public static String joinArguments​(String... args)

      Inverse operation of `splitArguments(java.lang.String)`. Returns ``command line''.
      See Also:
        `quoteArgument(java.lang.String)`

    - #### quoteArgument

          public static String quoteArgument​(String arg)

      Quotes specified string using `'\"'` if needed to. Returns quoted string.

      Note that whitespace characters such as '\n' and '\t' are not escaped as "\n" and "\t". Instead, the whole string is quoted. This is sufficient to allow it to contain any whitespace character.

      See Also:
        `joinArguments(java.lang.String...)`

    - #### substituteVars

          public static String substituteVars​(String text,
                                              char[] names,
                                              Object[] values)

      Equivalent to `substituteVars(text, names, values, null, null, false)`.

    - #### substituteVars

          public static String substituteVars​(String text,
                                              char[] names,
                                              Object[] values,
                                              String[] args,
                                              String allArgs)

      Equivalent to `substituteVars(text, names, values, args, allArgs, false)`.

    - #### substituteVars

          public static String substituteVars​(String text,
                                              char[] names,
                                              Object[] values,
                                              String[] args,
                                              String allArgs,
                                              boolean allowForeignVars)

      Returns specified text where %0, %1, ..., %9, %* and %X, %Y, etc, variables have been subsituted by specified values.

      "%%" may be used to escape character "%".

      A variable, whether named or not, %X may also be specified as %{X} etc.

      Parameters:
        `text` - text containing variables
        `names` - the one-character long name of named variables %X, %Y, etc.

        May be `null`.

        `values` - the values of named variables %X, %Y, etc.

        These objects are converted to strings using the `toString()` method.

        When there are no enough values, the corresponding variables are not replaced.

        May be `null` if `names` is also `null`.

        `args` - the values of `%0`, `%1`, ..., `%9` variables.

        When there are no enough values, the corresponding variables are replaced by the empty string.

        May be `null`.

        `allArgs` - the values of `%*` variable.

        May be `null`, in which case, `args` are joined using `joinArguments(java.lang.String...)` to form `allArgs`.

        `allowForeignVars` - if `true`, unknown variables specified as %{var_name} are assumed to be system properties or environment variables and are subsituted as such.
      Returns:
        specified text where variables have been subsituted with their values

    - #### replaceAll

          public static String replaceAll​(String string,
                                          String oldSub,
                                          String newSub)

      Replaces substring `oldSub` by substring `newSub` inside String `string`.
      Parameters:
        `string` - the String where replacements are to be performed
        `oldSub` - the substring to replace
        `newSub` - the replacement substring
      Returns:
        a string where all replacements have been performed
      See Also:
        `String.replace(char, char)`

    - #### capitalize

          public static String capitalize​(String string)

      Returns the specified string with its first character converted to upper case.
      Parameters:
        `string` - the String to be processed
      Returns:
        the specified string with its first character converted to upper case

    - #### uncapitalize

          public static String uncapitalize​(String string)

      Returns the specified string with its first character converted to lower case.
      Parameters:
        `string` - the String to be processed
      Returns:
        the specified string with its first character converted to lower case

    - #### quote

          public static String quote​(String string)

      Like `escape(java.lang.String)` but puts a double quote character (`'\"'`) around the escaped string.

    - #### escape

          public static String escape​(String string)

      Returns the specified string with all non-ASCII characters and non-printable ASCII characters replaced by the corresponding Java escape sequences (that is `'\n'`, `'é'`, etc).
      Parameters:
        `string` - the String to be escaped
      Returns:
        the specified string with all non-ASCII characters and non-printable ASCII characters replaced by the corresponding Java escape sequences

    - #### escape

          public static void escape​(String string,
                                    StringBuilder buffer)

      Same as `escape(String)` except that the escaped string is appended to specified buffer.

    - #### escape

          public static String escape​(char c)

      Returns the `\\uXXXX` Java escape sequence corresponding to specified character.
      Parameters:
        `c` - the character to be escaped
      Returns:
        A `\\uXXXX` Java escape sequence

    - #### escape

          public static void escape​(char c,
                                    StringBuilder buffer)

      Same as `escape(char)` expect that the `\\uXXXX` Java escape sequence is appended to specified buffer.

    - #### unquote

          public static String unquote​(String string)

      Like `unescape(java.lang.String)` but removes the double quote characters (`'\"'`), if any, before unescaping the string.

    - #### unescape

          public static String unescape​(String string)

      Returns the specified string with Java escape sequences (that is `'\n'`, `'é'`, etc) replaced by the corresponding character.
      Parameters:
        `string` - the String to be unescaped
      Returns:
        the specified string with Java escape sequences replaced by the corresponding character