com.h3c.util

## Class StringUtils

- java.lang.Object
- - com.h3c.util.StringUtils

-     public final class StringUtils
      extends Object

  Provides useful utilities revolving around strings.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `StringUtils.Align` Enumeration for alignment.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `COMMA` The comma (",") character as a string.
    `static String` | `DEFAULT_JOIN_DELIMITER` Default delimiter for the `join(java.util.Collection<?>)` methods.
    `static String` | `EMPTY` The empty string.
    `static String` | `EOL` The platform dependent line separator (new line character).
    `static String` | `TAB` The tab character.
    `static String` | `UNDERSCORE` The underscore character.
    `static String` | `UTF8` String representing UTF-8 encoding (e.g.
    `static String` | `ZERO` The zero ("0") character as a string.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `columnize(String[] strings)` Formats the supplied strings so that they are arranged in neat columns; maximum line width is 78; space between columns is 2; no indent.
    `static String` | `columnize(String[] strings, int maxWidth)` Formats the supplied strings so that they are arranged in neat columns; space between columns is 2; no indent.
    `static String` | `columnize(String[] strings, int maxWidth, int colSpacing)` Formats the supplied strings so that they are arranged in neat columns, but with no indent.
    `static String` | `columnize(String[] strings, int maxWidth, int colSpacing, int indent)` Formats the supplied strings so that they are arranged in neat columns.
    `static String` | `commaSeparated(Collection<?> items)` Returns a comma-separated string of the items in the collection.
    `static String` | `concat(Object... values)` Concatenates an array of objects using a StringBuilder and its `append()` method.
    `static String` | `emptyIsNull(String s)` Convert the given string to null, if it is already null or is empty.
    `static boolean` | `equals(String one, String two)` Determine if two Strings, considering nulls to be identical, are equal.
    `static String` | `format(String fmt, Object... o)` A simple string formatter that replaces each occurrence of `{}` in the format string with the string representation of each of the subsequent, optional arguments.
    `static String` | `fromCamelCase(String cc)` This method expects an input string consisting of letters and digits in "camelCase" (the standard format for variable names), and converts it to uppercase letters with underscore delimiters between the words.
    `static String` | `getFileContents(String path, ClassLoader classLoader)` Read in the contents of a text file from the given path.
    `static boolean` | `isAlphaNumeric(String value)` This predicate returns true if the specified string is alpha numeric; that is to say, if it begins with a letter and consists only of letters, numbers and underscores.
    `static boolean` | `isAlphaNumeric(String value, boolean allowUnderscores)` This predicate returns true if the specified string is alpha numeric; that is to say, if it begins with a letter and consists only of letters and numbers.
    `static boolean` | `isEmpty(String value)` This predicate returns true if the specified parameter is null, or consists only of whitespace.
    `static boolean` | `isIntegerZeroTo255(String value)` This predicate returns true if the specified string, when converted to an int, lies in the range 0 - 255.
    `static boolean` | `isStandardIdentifier(String id)` This predicate returns true if the supplied string matches the regular expression defined for general identifiers.
    `static String` | `join(Collection<?> values)` Joins a collection of objects' toString() values into a single string, using the default delimiter of ", " (comma-space).
    `static String` | `join(Collection<?> values, String delim)` Joins a collection of objects' toString() values into a single string, using the given delimiter.
    `static String` | `join(Object[] values)` Joins an array of objects' toString() values into a single string, using the default delimiter of ", " (comma-space).
    `static String` | `join(Object[] values, String delim)` Joins an array of objects' toString() values into a single string, using the given delimiter.
    `static String` | `normalizeEOL(String string)` Normalizes any compound line breaks (\r\n or \n\r) to only \n.
    `static String` | `nullIsEmpty(String s)` Convert the given string to an empty string, if it is null.
    `static String` | `pad(String what, int width)` Pads a field to the specified field width.
    `static String` | `pad(String what, int width, char with)` Pads a field to the specified field width.
    `static String` | `pad(String what, int width, char with, StringUtils.Align align)` Pads a field to the specified field width.
    `static String` | `pad(String what, int width, char with, StringUtils.Align align, boolean noTruncate)` Pads a field to the specified field width.
    `static String` | `pad(String what, int width, StringUtils.Align align)` Pads a field to the specified field width.
    `static int` | `parseHex(String hex, int fallback)` Returns either the correctly parsed hex value (as an int) or the supplied fallback value.
    `static int` | `parseInt(String value, int fallback)` Returns either the correctly parsed int value or the supplied fallback value.
    `static String` | `quoted(String value)` Returns the given value wrapped in double-quote characters (") if the value is not null, or the string `"null"` if it is null.
    `static String` | `safeToString(Object o)` Safely invokes `toString` on the specified entity and returns the result, unless the specified object is null, in which case it will return null.
    `static String` | `spaces(int length)` Returns a string of spaces of the specified length.
    `static String` | `stripCommentLines(String s)` Removes all lines that begin with the '#' character.
    `static String` | `toCamelCase(Enum<?> e)` A convenience overloaded method for `toCamelCase(String)` which takes enumeration constants as the parameter.
    `static String` | `toCamelCase(String s)` This method expects an input string consisting of uppercase letters, digits, and underscores (the standard format for constant names), and converts it to "camelCase".
    `static String` | `toCamelCase(String prefix, Enum<?> e)` A convenience overloaded method for `toCamelCase(String, String)`, which uses `e.name()`.
    `static String` | `toCamelCase(String prefix, String s)` This method expects a string consisting of uppercase letters, digits, and underscores (the standard format for constant names), and converts it to "camelCase".
    `static String` | `trimmedEmptyIsNull(String s)` Convert the given string to null, if it is already null or is empty if trimmed.
    `static String` | `trimPunct(String value)` Removes any punctuation in the passed in string.
    `static String` | `trimPunctAndSpaceWith(String value, String replace)` Removes any punctuation and whitespace in the passed in string.
    `static void` | `validateStandardIdentifier(String id)` This method checks the supplied string to see that it matches the regular expression defined for general identifiers.
    `static String` | `zeroFill(int value, int fieldWidth)` Returns a zero-filled string.

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

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

- - ### Field Detail

    - #### EOL

          public static final String EOL

      The platform dependent line separator (new line character).

    - #### TAB

          public static final String TAB

      The tab character.
      See Also:
        Constant Field Values

    - #### EMPTY

          public static final String EMPTY

      The empty string.
      See Also:
        Constant Field Values

    - #### UNDERSCORE

          public static final String UNDERSCORE

      The underscore character.
      See Also:
        Constant Field Values

    - #### ZERO

          public static final String ZERO

      The zero ("0") character as a string.
      See Also:
        Constant Field Values

    - #### COMMA

          public static final String COMMA

      The comma (",") character as a string.
      See Also:
        Constant Field Values

    - #### UTF8

          public static final String UTF8

      String representing UTF-8 encoding (e.g. String.getBytes(UTF8))
      See Also:
        Constant Field Values

    - #### DEFAULT_JOIN_DELIMITER

          public static final String DEFAULT_JOIN_DELIMITER

      Default delimiter for the `join(java.util.Collection<?>)` methods.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### isEmpty

          public static boolean isEmpty(String value)

      This predicate returns true if the specified parameter is null, or consists only of whitespace.
      Parameters:
        `value` - the string value to test
      Returns:
        true if the value is null, or empty

    - #### safeToString

          public static String safeToString(Object o)

      Safely invokes `toString` on the specified entity and returns the result, unless the specified object is null, in which case it will return null.
      Parameters:
        `o` - object on which to invoke toString
      Returns:
        result of `o.toString()` invocation or null if the object is null

    - #### isAlphaNumeric

          public static boolean isAlphaNumeric(String value,
                               boolean allowUnderscores)

      This predicate returns true if the specified string is alpha numeric; that is to say, if it begins with a letter and consists only of letters and numbers. Underscores are allowed if the second parameter is set true.
      Parameters:
        `value` - the string value to test
        `allowUnderscores` - if true, underscores are allowed
      Returns:
        true if the value is alphanumeric
      Throws:
        `NullPointerException` - if value is null

    - #### isAlphaNumeric

          public static boolean isAlphaNumeric(String value)

      This predicate returns true if the specified string is alpha numeric; that is to say, if it begins with a letter and consists only of letters, numbers and underscores.
      Parameters:
        `value` - the string value to test
      Returns:
        true if the value is alphanumeric
      Throws:
        `NullPointerException` - if value is null

    - #### quoted

          public static String quoted(String value)

      Returns the given value wrapped in double-quote characters (") if the value is not null, or the string `"null"` if it is null.
      Parameters:
        `value` - the value
      Returns:
        the string quoted (if not null), or "null"

    - #### toCamelCase

          public static String toCamelCase(Enum<?> e)

      A convenience overloaded method for `toCamelCase(String)` which takes enumeration constants as the parameter.
      Parameters:
        `e` - the enum constant
      Returns:
        the name of the enum constant, camel-cased

    - #### toCamelCase

          public static String toCamelCase(String s)

      This method expects an input string consisting of uppercase letters, digits, and underscores (the standard format for constant names), and converts it to "camelCase".

      For example, `"LORD_OF_THE_RINGS"` becomes `"lordOfTheRings"`.

      Parameters:
        `s` - the uppercase words delimited by underscores input string
      Returns:
        the input string converted to camelCase
      Throws:
        `NullPointerException` - if the parameter is null
        `IllegalArgumentException` - if s has unexpected (or no) characters in it

    - #### toCamelCase

          public static String toCamelCase(String prefix,
                           Enum<?> e)

      A convenience overloaded method for `toCamelCase(String, String)`, which uses `e.name()`.
      Parameters:
        `prefix` - optional prefix
        `e` - the enum constant
      Returns:
        the name of the enum constant, camel-cased

    - #### toCamelCase

          public static String toCamelCase(String prefix,
                           String s)

      This method expects a string consisting of uppercase letters, digits, and underscores (the standard format for constant names), and converts it to "camelCase". If a prefix is specified, i.e. is not null or empty string, it will be prepended as-is.

      For example:

           "LORD_OF_THE_RINGS" --> "lordOfTheRings"
           "LORD_OF_THE_RINGS" and prefix "prequelTo" --> "prequelToLordOfTheRings"

      Parameters:
        `prefix` - optional prefix
        `s` - the uppercase words delimited by underscores input string
      Returns:
        the input string converted to camelCase
      Throws:
        `NullPointerException` - if the parameter is null
        `IllegalArgumentException` - if s has unexpected (or no) characters in it

    - #### fromCamelCase

          public static String fromCamelCase(String cc)

      This method expects an input string consisting of letters and digits in "camelCase" (the standard format for variable names), and converts it to uppercase letters with underscore delimiters between the words.

      For example, `"lordOfTheRings"` becomes `"LORD_OF_THE_RINGS"`.

      Parameters:
        `cc` - the camelCase input string
      Returns:
        the input string converted to uppercase words delimited by underscores
      Throws:
        `NullPointerException` - if the parameter is null
        `IllegalArgumentException` - if s has unexpected (or no) characters in it

    - #### isIntegerZeroTo255

          public static boolean isIntegerZeroTo255(String value)

      This predicate returns true if the specified string, when converted to an int, lies in the range 0 - 255. Leading zeroes are allowed.
      Parameters:
        `value` - the string value to test
      Returns:
        true if the value is "0" - "255"
      Throws:
        `NullPointerException` - if value is null

    - #### isStandardIdentifier

          public static boolean isStandardIdentifier(String id)

      This predicate returns true if the supplied string matches the regular expression defined for general identifiers. That is to say, the string starts with letter, and is followed by zero or more letters, numbers, underscores, and/or dots.
      Parameters:
        `id` - the identifier
      Returns:
        true if it is well-formed

    - #### validateStandardIdentifier

          public static void validateStandardIdentifier(String id)

      This method checks the supplied string to see that it matches the regular expression defined for general identifiers. That is to say, the string starts with letter, and is followed by zero or more letters, numbers, underscores, and/or dots. If it matches, the method silently returns. If it does not match, an exception is thrown.
      Parameters:
        `id` - the identifier
      Throws:
        `IllegalArgumentException` - if the string does not match the pattern for standard identifiers.

    - #### equals

          public static boolean equals(String one,
                       String two)

      Determine if two Strings, considering nulls to be identical, are equal.
      Parameters:
        `one` - the first String to compare
        `two` - the second String to compare
      Returns:
        true if the Strings are identical, including if both are null, and false otherwise

    - #### parseHex

          public static int parseHex(String hex,
                     int fallback)

      Returns either the correctly parsed hex value (as an int) or the supplied fallback value.
      Parameters:
        `hex` - String to parse as a hex value
        `fallback` - The int to return if the supplied hex string is invalid
      Returns:
        the hex value

    - #### parseInt

          public static int parseInt(String value,
                     int fallback)

      Returns either the correctly parsed int value or the supplied fallback value.
      Parameters:
        `value` - String to parse as an int
        `fallback` - The int to return if the supplied string is invalid
      Returns:
        the int value

    - #### zeroFill

          public static String zeroFill(int value,
                        int fieldWidth)

      Returns a zero-filled string. For example:

           StringUtils.zeroFill(45, 6);

      returns the string `"000045"`.
      Parameters:
        `value` - the value
        `fieldWidth` - the field width
      Returns:
        the zero filled string

    - #### format

          public static String format(String fmt,
                      Object... o)

      A simple string formatter that replaces each occurrence of `{}` in the format string with the string representation of each of the subsequent, optional arguments. For example:

               StringUtils.format("{} => {}", "Foo", 123);
               // returns "Foo => 123"

      Parameters:
        `fmt` - the format string
        `o` - arguments to be inserted into the output string
      Returns:
        a formatted string

    - #### columnize

          public static String columnize(String[] strings,
                         int maxWidth,
                         int colSpacing,
                         int indent)

      Formats the supplied strings so that they are arranged in neat columns.
      Parameters:
        `strings` - the array of strings to format
        `maxWidth` - the maximum number of characters any single line can be
        `colSpacing` - the number of spaces between columns
        `indent` - number of spaces to indent the whole thing by
      Returns:
        a string (with embedded newlines) that is the columnized result

    - #### columnize

          public static String columnize(String[] strings,
                         int maxWidth,
                         int colSpacing)

      Formats the supplied strings so that they are arranged in neat columns, but with no indent.
      Parameters:
        `strings` - the array of strings to format
        `maxWidth` - the maximum number of characters any single line can be
        `colSpacing` - the number of spaces between columns
      Returns:
        the columnized strings

    - #### columnize

          public static String columnize(String[] strings,
                         int maxWidth)

      Formats the supplied strings so that they are arranged in neat columns; space between columns is 2; no indent.
      Parameters:
        `strings` - the array of strings to format
        `maxWidth` - the maximum number of characters any single line can be
      Returns:
        the columnized strings

    - #### columnize

          public static String columnize(String[] strings)

      Formats the supplied strings so that they are arranged in neat columns; maximum line width is 78; space between columns is 2; no indent.
      Parameters:
        `strings` - the array of strings to format
      Returns:
        the columnized strings

    - #### pad

          public static String pad(String what,
                   int width,
                   char with,
                   StringUtils.Align align,
                   boolean noTruncate)

      Pads a field to the specified field width. If what is longer than width, it is truncated, unless the noTruncate flag is set true.
      Parameters:
        `what` - the string to be padded
        `width` - the width of the padded (truncated) field
        `with` - the character to pad with
        `align` - the alignment
        `noTruncate` - do not truncate the string if it is longer than width
      Returns:
        the padded string

    - #### pad

          public static String pad(String what,
                   int width,
                   char with,
                   StringUtils.Align align)

      Pads a field to the specified field width. If what is longer than width, it is truncated.
      Parameters:
        `what` - the string to be padded
        `width` - the width of the padded (truncated) field
        `with` - the character to pad with
        `align` - the alignment
      Returns:
        the padded string

    - #### pad

          public static String pad(String what,
                   int width,
                   char with)

      Pads a field to the specified field width. If what is longer than width, it is truncated. The text is LEFT justified.
      Parameters:
        `what` - the string to be padded
        `width` - the width of the padded (truncated) field
        `with` - the character to pad with
      Returns:
        the padded string

    - #### pad

          public static String pad(String what,
                   int width,
                   StringUtils.Align align)

      Pads a field to the specified field width. If what is longer than width, it is truncated. Space is used as the padding character.
      Parameters:
        `what` - the string to be padded
        `width` - the width of the padded (truncated) field
        `align` - one of LEFT, CENTER or RIGHT
      Returns:
        the padded string

    - #### pad

          public static String pad(String what,
                   int width)

      Pads a field to the specified field width. If what is longer than width, it is truncated. The text is LEFT justified. Space is used as the padding character.
      Parameters:
        `what` - the string to be padded
        `width` - the width of the padded (truncated) field
      Returns:
        the padded string

    - #### spaces

          public static String spaces(int length)

      Returns a string of spaces of the specified length.
      Parameters:
        `length` - the length
      Returns:
        a string of spaces

    - #### commaSeparated

          public static String commaSeparated(Collection<?> items)

      Returns a comma-separated string of the items in the collection. The individual tokens within the string are produced using `Object#toString()` on each item in the collection.
      Parameters:
        `items` - collection of items
      Returns:
        comma-separated string of items in the collection; empty string if the collection is empty; null if the collection is null

    - #### emptyIsNull

          public static String emptyIsNull(String s)

      Convert the given string to null, if it is already null or is empty.
      Parameters:
        `s` - string to be verified
      Returns:
        null if the string is null or empty; otherwise the unmodified string

    - #### trimmedEmptyIsNull

          public static String trimmedEmptyIsNull(String s)

      Convert the given string to null, if it is already null or is empty if trimmed.
      Parameters:
        `s` - string to be verified
      Returns:
        null if the string is null or empty; otherwise the unmodified string

    - #### nullIsEmpty

          public static String nullIsEmpty(String s)

      Convert the given string to an empty string, if it is null.
      Parameters:
        `s` - string to be verified
      Returns:
        empty string if the string is null; otherwise the unmodified string

    - #### trimPunct

          public static String trimPunct(String value)

      Removes any punctuation in the passed in string.
      Parameters:
        `value` - the original string value that may contain punctuation
      Returns:
        true new string with the punctuation removed
      Throws:
        `NullPointerException` - if value is null

    - #### trimPunctAndSpaceWith

          public static String trimPunctAndSpaceWith(String value,
                                     String replace)

      Removes any punctuation and whitespace in the passed in string.
      Parameters:
        `value` - the original string value that may contain punctuation
        `replace` - string to be replaced instead of punctuation and white space
      Returns:
        true new string with the punctuation removed
      Throws:
        `NullPointerException` - if value is null

    - #### join

          public static String join(Collection<?> values)

      Joins a collection of objects' toString() values into a single string, using the default delimiter of ", " (comma-space).
      Parameters:
        `values` - the values
      Returns:
        the delimiter-separated string

    - #### join

          public static String join(Object[] values)

      Joins an array of objects' toString() values into a single string, using the default delimiter of ", " (comma-space).
      Parameters:
        `values` - the values
      Returns:
        the delimiter-separated string

    - #### join

          public static String join(Collection<?> values,
                    String delim)

      Joins a collection of objects' toString() values into a single string, using the given delimiter. If the collection is null, null is returned.
      Parameters:
        `values` - the values
        `delim` - the delimiter
      Returns:
        the delimiter-separated string

    - #### join

          public static String join(Object[] values,
                    String delim)

      Joins an array of objects' toString() values into a single string, using the given delimiter. If the array is null, null is returned.
      Parameters:
        `values` - the values
        `delim` - the delimiter
      Returns:
        the delimiter-separated string

    - #### concat

          public static String concat(Object... values)

      Concatenates an array of objects using a StringBuilder and its `append()` method. This convenience method reduces something like:

           String s = new StringBuilder().append(e1).append(e2).append(e3).toString();

      to

           String s = StringUtils.concat(e1, e2, e3);

      Parameters:
        `values` - the values to concatenate
      Returns:
        the concatentated string

    - #### normalizeEOL

          public static String normalizeEOL(String string)

      Normalizes any compound line breaks (\r\n or \n\r) to only \n.
      Parameters:
        `string` - string to be normalized
      Returns:
        normalized string

    - #### stripCommentLines

          public static String stripCommentLines(String s)

      Removes all lines that begin with the '#' character.
      Parameters:
        `s` - the multiline input
      Returns:
        multiline output with "comment" lines removed

    - #### getFileContents

          public static String getFileContents(String path,
                               ClassLoader classLoader)
                                        throws IOException

      Read in the contents of a text file from the given path. If the resource cannot be found, null is returned.
      Parameters:
        `path` - path of resource containing the data
        `classLoader` - class-loader to be used for locating resource
      Returns:
        the contents of the file as a string
      Throws:
        `IOException` - if there is a problem reading the file.

Copyright © 2014. All Rights Reserved.