StringUtil (FreeMarker 2.3.23 API)
Date: 2015-07-05

freemarker.template.utility

## Class StringUtil

- java.lang.Object
- - freemarker.template.utility.StringUtil

-     public class StringUtil
      extends Object

  Some text related utilities.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `StringUtil()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `capitalize(String s)`
    `static String` | `chomp(String s)` Removes the line-break from the end of the string.
    `static Locale` | `deduceLocale(String input)`
    `static String` | `emptyToNull(String s)` Converts a 0-length string to null, leaves the string as is otherwise.
    `static String` | `ftlQuote(String s)` Creates a quoted FTL string literal from a string, using escaping where necessary.
    `static String` | `FTLStringLiteralDec(String s)` FTL string literal decoding.
    `static String` | `FTLStringLiteralEnc(String s)` Escapes a string according the FTL string literal escaping rules; it doesn't add the quotation marks.
    `static String` | `FTLStringLiteralEnc(String s, char quotation)` Escapes a string according the FTL string literal escaping rules, assuming the literal is quoted with `quotation`; it doesn't add the quotation marks itself.
    `static boolean` | `getYesNo(String s)`
    `static String` | `HTMLEnc(String s)` Deprecated. Use `XHTMLEnc(String)` instead, because it escapes apostrophe-quote too.
    `static boolean` | `isFTLIdentifierPart(char c)` Tells if a character can occur in an FTL identifier expression (without escaping) as other than the first character.
    `static boolean` | `isFTLIdentifierStart(char c)` Tells if a character can occur on the beginning of an FTL identifier expression (without escaping).
    `static boolean` | `isTrimmableToEmpty(char[] text)` Tells if `String.trim()` will return a 0-length string for the `String` equivalent of the argument.
    `static boolean` | `isTrimmableToEmpty(char[] text, int start)` Like `isTrimmableToEmpty(char[])`, but acts on a sub-array that starts at `start` (inclusive index).
    `static boolean` | `isTrimmableToEmpty(char[] text, int start, int end)` Like `isTrimmableToEmpty(char[])`, but acts on a sub-array that starts at `start` (inclusive index) and ends at `end` (exclusive index).
    `static boolean` | `isXMLID(String name)`
    `static String` | `javaScriptStringEnc(String s)` Escapes a `String` to be safely insertable into a JavaScript string literal; for more see `jsStringEnc(s, false)`.
    `static String` | `javaStringEnc(String s)` Escapes the `String` with the escaping rules of Java language string literals, so it's safe to insert the value into a string literal.
    `static String` | `jQuote(Object obj)` Converts the parameter with `toString` (if it's not `null`) and passes it to `jQuote(String)`.
    `static String` | `jQuote(String s)` Quotes string as Java Language string literal.
    `static String` | `jQuoteNoXSS(Object obj)` Converts the parameter with `toString` (if not `null`)and passes it to `jQuoteNoXSS(String)`.
    `static String` | `jQuoteNoXSS(String s)` Same as `jQuoteNoXSS(String)` but also escapes `'<'` as `\``u003C`.
    `static String` | `jsonStringEnc(String s)` Escapes a `String` to be safely insertable into a JSON string literal; for more see `jsStringEnc(s, true)`.
    `static String` | `jsStringEnc(String s, boolean json)` Escapes a `String` to be safely insertable into a JavaScript or a JSON string literal.
    `static String` | `leftPad(String s, int minLength)` Pads the string at the left with spaces until it reaches the desired length.
    `static String` | `leftPad(String s, int minLength, char filling)` Pads the string at the left with the specified character until it reaches the desired length.
    `static String` | `leftPad(String s, int minLength, String filling)` Pads the string at the left with a filling pattern until it reaches the desired length.
    `static boolean` | `matchesName(String qname, String nodeName, String nsURI, Environment env)`
    `static Map` | `parseNameValuePairList(String s, String defaultValue)` Parses a name-value pair list, where the pairs are separated with comma, and the name and value is separated with colon.
    `static String` | `replace(String text, String oldSub, String newSub)` Same as `replace(String, String, String, boolean, boolean)` with two `false` parameters.
    `static String` | `replace(String text, String oldsub, String newsub, boolean caseInsensitive, boolean firstOnly)` Replaces all occurrences of a sub-string in a string.
    `static String` | `rightPad(String s, int minLength)` Pads the string at the right with spaces until it reaches the desired length.
    `static String` | `rightPad(String s, int minLength, char filling)` Pads the string at the right with the specified character until it reaches the desired length.
    `static String` | `rightPad(String s, int minLength, String filling)` Pads the string at the right with a filling pattern until it reaches the desired length.
    `static String` | `RTFEnc(String s)` Rich Text Format encoding (does not replace line breaks).
    `static String[]` | `split(String s, char c)` Splits a string at the specified character.
    `static String[]` | `split(String s, String sep, boolean caseInsensitive)` Splits a string at the specified string.
    `static String` | `toLowerABC(int n)` Same as `toUpperABC(int)`, but produces lower case result, like `"ab"`.
    `static String` | `toUpperABC(int n)` Converts `1`, `2`, `3` and so forth to `"A"`, `"B"`, `"C"` and so fort.
    `static char[]` | `trim(char[] cs)` Behaves exactly like `String.trim()`, but works on arrays.
    `static String` | `tryToString(Object object)` Tries to run `toString()`, but if that fails, returns a `"[com.example.SomeClass.toString() failed: " + e + "]"` instead.
    `static String` | `URLEnc(String s, String charset)` URL encoding (like%20this) for query parameter values, path segments, fragments; this encodes all characters that are reserved anywhere.
    `static String` | `URLPathEnc(String s, String charset)` Like `URLEnc(String, String)` but doesn't escape the slash character (`/`).
    `static int` | `versionStringToInt(String version)` Converts a version number string to an integer for easy comparison.
    `static String` | `XHTMLEnc(String s)` XHTML Encoding.
    `static String` | `XMLEnc(String s)` XML Encoding.
    `static String` | `XMLEncNA(String s)` XML encoding without replacing apostrophes.
    `static String` | `XMLEncNQG(String s)` XML encoding without replacing apostrophes and quotation marks and greater-thans (except in `]]>`).
    `static String` | `XMLEncQAttr(String s)` XML encoding for attributes values quoted with `"` (not with `'`!).

    - ### 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

    - #### HTMLEnc

          public static String HTMLEnc(String s)

      Deprecated. Use `XHTMLEnc(String)` instead, because it escapes apostrophe-quote too.
      HTML encoding (does not convert line breaks and apostrophe-quote). Replaces all '>' '<' '&' and '"' with entity reference, but not "'" (apostrophe-quote). The last is not escaped as back then when this was written some user agents didn't understood "&apos;" nor "&#39;".

    - #### XMLEnc

          public static String XMLEnc(String s)

      XML Encoding. Replaces all '>' '<' '&', "'" and '"' with entity reference

    - #### XHTMLEnc

          public static String XHTMLEnc(String s)

      XHTML Encoding. Replaces all '>' '<' '&', "'" and '"' with entity reference suitable for XHTML decoding in common user agents (including legacy user agents, which do not decode "&apos;" to "'", so "&#39;" is used instead [see http://www.w3.org/TR/xhtml1/#C_16])

    - #### XMLEncNA

          public static String XMLEncNA(String s)

      XML encoding without replacing apostrophes.
      See Also:
        `XMLEnc(String)`

    - #### XMLEncQAttr

          public static String XMLEncQAttr(String s)

      XML encoding for attributes values quoted with `"` (not with `'`!). Also can be used for HTML attributes that are quoted with `"`.
      See Also:
        `XMLEnc(String)`

    - #### XMLEncNQG

          public static String XMLEncNQG(String s)

      XML encoding without replacing apostrophes and quotation marks and greater-thans (except in `]]>`).
      See Also:
        `XMLEnc(String)`

    - #### RTFEnc

          public static String RTFEnc(String s)

      Rich Text Format encoding (does not replace line breaks). Escapes all '\' '{' '}' and '"'

    - #### URLEnc

          public static String URLEnc(String s,
                                      String charset)
                               throws UnsupportedEncodingException

      URL encoding (like%20this) for query parameter values, path segments, fragments; this encodes all characters that are reserved anywhere.
      Throws:
        `UnsupportedEncodingException`

    - #### URLPathEnc

          public static String URLPathEnc(String s,
                                          String charset)
                                   throws UnsupportedEncodingException

      Like `URLEnc(String, String)` but doesn't escape the slash character (`/`). This can be used to encode a path only if you know that no folder or file name will contain `/` character (not in the path, but in the name itself), which usually stands, as the commonly used OS-es don't allow that.
      Throws:
        `UnsupportedEncodingException`
      Since:
        2.3.21

    - #### FTLStringLiteralEnc

          public static String FTLStringLiteralEnc(String s,
                                                   char quotation)

      Escapes a string according the FTL string literal escaping rules, assuming the literal is quoted with `quotation`; it doesn't add the quotation marks itself.
      Parameters:
        `quotation` - Either `'"'` or `'\''`. It's assumed that the string literal whose part we calculate is enclosed within this kind of quotation mark. Thus, the other kind of quotation character will not be escaped in the result.
      Since:
        2.3.22

    - #### FTLStringLiteralEnc

          public static String FTLStringLiteralEnc(String s)

      Escapes a string according the FTL string literal escaping rules; it doesn't add the quotation marks. As this method doesn't know if the string literal is quoted with reuglar quotation marks or apostrophe quute, it will escape both.
      See Also:
        `FTLStringLiteralEnc(String, char)`

    - #### FTLStringLiteralDec

          public static String FTLStringLiteralDec(String s)
                                            throws ParseException

      FTL string literal decoding. \\, \", \', \n, \t, \r, \b and \f will be replaced according to Java rules. In additional, it knows \g, \l, \a and \{ which are replaced with <, >, & and { respectively. \x works as hexadecimal character code escape. The character codes are interpreted according to UCS basic plane (Unicode). "f\x006Fo", "f\x06Fo" and "f\x6Fo" will be "foo". "f\x006F123" will be "foo123" as the maximum number of digits is 4. All other \X (where X is any character not mentioned above or End-of-string) will cause a ParseException.
      Parameters:
        `s` - String literal without the surrounding quotation marks
      Returns:
        String with all escape sequences resolved
      Throws:
        `ParseException` - if there string contains illegal escapes

    - #### deduceLocale

          public static Locale deduceLocale(String input)

    - #### capitalize

          public static String capitalize(String s)

    - #### getYesNo

          public static boolean getYesNo(String s)

    - #### split

          public static String[] split(String s,
                                       char c)

      Splits a string at the specified character.

    - #### split

          public static String[] split(String s,
                                       String sep,
                                       boolean caseInsensitive)

      Splits a string at the specified string.

    - #### replace

          public static String replace(String text,
                                       String oldSub,
                                       String newSub)

      Same as `replace(String, String, String, boolean, boolean)` with two `false` parameters.
      Since:
        2.3.20

    - #### replace

          public static String replace(String text,
                                       String oldsub,
                                       String newsub,
                                       boolean caseInsensitive,
                                       boolean firstOnly)

      Replaces all occurrences of a sub-string in a string.
      Parameters:
        `text` - The string where it will replace `oldsub` with `newsub`.
      Returns:
        String The string after the replacements.

    - #### chomp

          public static String chomp(String s)

      Removes the line-break from the end of the string.

    - #### emptyToNull

          public static String emptyToNull(String s)

      Converts a 0-length string to null, leaves the string as is otherwise.
      Parameters:
        `s` - maybe `null`.

    - #### jQuote

          public static String jQuote(Object obj)

      Converts the parameter with `toString` (if it's not `null`) and passes it to `jQuote(String)`.

    - #### jQuote

          public static String jQuote(String s)

      Quotes string as Java Language string literal. Returns string `"null"` if `s` is `null`.

    - #### jQuoteNoXSS

          public static String jQuoteNoXSS(Object obj)

      Converts the parameter with `toString` (if not `null`)and passes it to `jQuoteNoXSS(String)`.

    - #### jQuoteNoXSS

          public static String jQuoteNoXSS(String s)

      Same as `jQuoteNoXSS(String)` but also escapes `'<'` as `\``u003C`. This is used for log messages to prevent XSS on poorly written Web-based log viewers.

    - #### ftlQuote

          public static String ftlQuote(String s)

      Creates a quoted FTL string literal from a string, using escaping where necessary. The result either uses regular quotation marks (UCS 0x22) or apostrophe-quotes (UCS 0x27), depending on the string content. (Currently, apostrophe-quotes will be chosen exactly when the string contains regular quotation character and doesn't contain apostrophe-quote character.)
      Parameters:
        `s` - The value that should be converted to an FTL string literal whose evaluated value equals to `s`
      Since:
        2.3.22

    - #### isFTLIdentifierStart

          public static boolean isFTLIdentifierStart(char c)

      Tells if a character can occur on the beginning of an FTL identifier expression (without escaping).
      Since:
        2.3.22

    - #### isFTLIdentifierPart

          public static boolean isFTLIdentifierPart(char c)

      Tells if a character can occur in an FTL identifier expression (without escaping) as other than the first character.
      Since:
        2.3.22

    - #### javaStringEnc

          public static String javaStringEnc(String s)

      Escapes the `String` with the escaping rules of Java language string literals, so it's safe to insert the value into a string literal. The resulting string will not be quoted.

      All characters under UCS code point 0x20 will be escaped. Where they have no dedicated escape sequence in Java, they will be replaced with hexadecimal escape (`\``uXXXX`).

      See Also:
        `jQuote(String)`

    - #### javaScriptStringEnc

          public static String javaScriptStringEnc(String s)

      Escapes a `String` to be safely insertable into a JavaScript string literal; for more see `jsStringEnc(s, false)`.

    - #### jsonStringEnc

          public static String jsonStringEnc(String s)

      Escapes a `String` to be safely insertable into a JSON string literal; for more see `jsStringEnc(s, true)`.

    - #### jsStringEnc

          public static String jsStringEnc(String s,
                                           boolean json)

      Escapes a `String` to be safely insertable into a JavaScript or a JSON string literal. The resulting string will not be quoted; the caller must ensure that they are there in the final output. Note that for JSON, the quotation marks must be `"`, not `'`, because JSON doesn't escape `'`.

      The escaping rules guarantee that if the inside of the literal is from one or more touching sections of strings escaped with this, no character sequence will occur that closes the string literal or has special meaning in HTML/XML that can terminate the script section. (If, however, the escaped section is preceded by or followed by strings from other sources, this can't be guaranteed in some rare cases. Like `x = "</${a?js_string}"` might closes the "script" element if `a` is is `"script>"`.) The escaped characters are:

      Input | Output
      --- | ---
      `"` | `\"`
      `'` if not in JSON-mode | `\'`
      `\` | `\\`
      `/` if the method can't know that it won't be directly after `<` | `\/`
      `>` if the method can't know that it won't be directly after `]]` or `--` | JavaScript: `\>`; JSON: `\``u003E`
      `<` if the method can't know that it won't be directly followed by `!` or `?` | ``\`u003C`
      u0000-u001f (UNICODE control characters - disallowed by JSON) u007f-u009f (UNICODE control characters - disallowed by JSON) | `\n`, `\r` and such, or if there's no such dedicated escape: JavaScript: `\xXX`, JSON: `\`u`XXXX`
      u2028 (Line separator - source code line-break in ECMAScript) u2029 (Paragraph separator - source code line-break in ECMAScript) | `\`u`XXXX`

      Since:
        2.3.20

    - #### parseNameValuePairList

          public static Map parseNameValuePairList(String s,
                                                   String defaultValue)
                                            throws ParseException

      Parses a name-value pair list, where the pairs are separated with comma, and the name and value is separated with colon. The keys and values can contain only letters, digits and `_`. They can't be quoted. White-space around the keys and values are ignored. The value can be omitted if `defaultValue` is not null. When a value is omitted, then the colon after the key must be omitted as well. The same key can't be used for multiple times.
      Parameters:
        `s` - the string to parse. For example: `"strong:100, soft:900"`.
        `defaultValue` - the value used when the value is omitted in a key-value pair.
      Returns:
        the map that contains the name-value pairs.
      Throws:
        `ParseException` - if the string is not a valid name-value pair list.

    - #### isXMLID

          public static boolean isXMLID(String name)

      Returns:
        whether the name is a valid XML tagname. (This routine might only be 99% accurate. Should maybe REVISIT)

    - #### matchesName

          public static boolean matchesName(String qname,
                                            String nodeName,
                                            String nsURI,
                                            Environment env)

      Returns:
        whether the qname matches the combination of nodeName, nsURI, and environment prefix settings.

    - #### leftPad

          public static String leftPad(String s,
                                       int minLength)

      Pads the string at the left with spaces until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string.
      Parameters:
        `s` - the string that will be padded.
        `minLength` - the length to reach.

    - #### leftPad

          public static String leftPad(String s,
                                       int minLength,
                                       char filling)

      Pads the string at the left with the specified character until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string.
      Parameters:
        `s` - the string that will be padded.
        `minLength` - the length to reach.
        `filling` - the filling pattern.

    - #### leftPad

          public static String leftPad(String s,
                                       int minLength,
                                       String filling)

      Pads the string at the left with a filling pattern until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string. For example: `leftPad('ABC', 9, '1234')` returns `"123412ABC"`.
      Parameters:
        `s` - the string that will be padded.
        `minLength` - the length to reach.
        `filling` - the filling pattern. Must be at least 1 characters long. Can't be `null`.

    - #### rightPad

          public static String rightPad(String s,
                                        int minLength)

      Pads the string at the right with spaces until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string.
      Parameters:
        `s` - the string that will be padded.
        `minLength` - the length to reach.

    - #### rightPad

          public static String rightPad(String s,
                                        int minLength,
                                        char filling)

      Pads the string at the right with the specified character until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string.
      Parameters:
        `s` - the string that will be padded.
        `minLength` - the length to reach.
        `filling` - the filling pattern.

    - #### rightPad

          public static String rightPad(String s,
                                        int minLength,
                                        String filling)

      Pads the string at the right with a filling pattern until it reaches the desired length. If the string is longer than this length, then it returns the unchanged string. For example: `rightPad('ABC', 9, '1234')` returns `"ABC412341"`. Note that the filling pattern is started as if you overlay `"123412341"` with the left-aligned `"ABC"`, so it starts with `"4"`.
      Parameters:
        `s` - the string that will be padded.
        `minLength` - the length to reach.
        `filling` - the filling pattern. Must be at least 1 characters long. Can't be `null`.

    - #### versionStringToInt

          public static int versionStringToInt(String version)

      Converts a version number string to an integer for easy comparison. The version number must start with numbers separated with dots. There can be any number of such dot-separated numbers, but only the first three will be considered. After the numbers arbitrary text can follow, and will be ignored. The string will be trimmed before interpretation.
      Returns:
        major * 1000000 + minor * 1000 + micro

    - #### tryToString

          public static String tryToString(Object object)

      Tries to run `toString()`, but if that fails, returns a `"[com.example.SomeClass.toString() failed: " + e + "]"` instead. Also, it returns `null` for `null` parameter.
      Since:
        2.3.20

    - #### toUpperABC

          public static String toUpperABC(int n)

      Converts `1`, `2`, `3` and so forth to `"A"`, `"B"`, `"C"` and so fort. When reaching `"Z"`, it continues like `"AA"`, `"AB"`, etc. The lowest supported number is 1, but there's no upper limit.
      Throws:
        `IllegalArgumentException` - If the argument is 0 or less.
      Since:
        2.3.22

    - #### toLowerABC

          public static String toLowerABC(int n)

      Same as `toUpperABC(int)`, but produces lower case result, like `"ab"`.
      Since:
        2.3.22

    - #### trim

          public static char[] trim(char[] cs)

      Behaves exactly like `String.trim()`, but works on arrays. If the resulting array would have the same content after trimming, it returns the original array instance. Otherwise it returns a new array instance (or `CollectionUtils.EMPTY_CHAR_ARRAY`).
      Since:
        2.3.22

    - #### isTrimmableToEmpty

          public static boolean isTrimmableToEmpty(char[] text)

      Tells if `String.trim()` will return a 0-length string for the `String` equivalent of the argument.
      Since:
        2.3.22

    - #### isTrimmableToEmpty

          public static boolean isTrimmableToEmpty(char[] text,
                                                   int start)

      Like `isTrimmableToEmpty(char[])`, but acts on a sub-array that starts at `start` (inclusive index).
      Since:
        2.3.23

    - #### isTrimmableToEmpty

          public static boolean isTrimmableToEmpty(char[] text,
                                                   int start,
                                                   int end)

      Like `isTrimmableToEmpty(char[])`, but acts on a sub-array that starts at `start` (inclusive index) and ends at `end` (exclusive index).
      Since:
        2.3.23