org.modeshape.common.util

## Class StringUtil

- java.lang.Object
- - org.modeshape.common.util.StringUtil

-     @Immutable
      public class StringUtil
      extends Object

  Utilities for string processing and manipulation.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `StringUtil.Justify`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String[]` | `EMPTY_STRING_ARRAY`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `combineLines(String[] lines)` Combine the lines into a single string, using the new line character as the delimiter.
    `static String` | `combineLines(String[] lines, char separator)` Combine the lines into a single string, using the supplied separator as the delimiter.
    `static boolean` | `containsAnyOf(String str, char... chars)` Return whether the supplied string contains any of the supplied characters.
    `static String` | `createString(char charToRepeat, int numberOfRepeats)` Create a new string containing the specified character repeated a specific number of times.
    `static String` | `createString(String pattern, Object... parameters)` Create a string by substituting the parameters into all key occurrences in the supplied format.
    `static byte[]` | `fromHexString(String hexadecimal)`
    `static String` | `getHexString(byte[] bytes)` Get the hexadecimal string representation of the supplied byte array.
    `static String` | `getStackTrace(Throwable throwable)` Get the stack trace of the supplied exception.
    `static boolean` | `isBlank(String str)` Returns true if the given string is null or represents the empty string
    `static boolean` | `isHexCharacter(char c)`
    `static boolean` | `isHexString(String hexadecimal)`
    `static String` | `join(Iterable<?> values, String delimiter)` Combine the supplied values into a single string, using the supplied string to delimit values.
    `static String` | `join(Object[] values, String delimiter)` Combine the supplied values into a single string, using the supplied string to delimit values.
    `static String` | `justify(StringUtil.Justify justify, String str, int width, char padWithChar)` Justify the contents of the string.
    `static String` | `justifyCenter(String str, int width, char padWithChar)` Center the contents of the string.
    `static String` | `justifyLeft(String str, int width, char padWithChar)` Left justify the contents of the string, ensuring that the supplied string begins at the first character and that the resulting string is of the desired length.
    `protected static String` | `justifyLeft(String str, int width, char padWithChar, boolean trimWhitespace)`
    `static String` | `justifyRight(String str, int width, char padWithChar)` Right justify the contents of the string, ensuring that the string ends at the last character.
    `static String` | `normalize(String text)` Removes leading and trailing whitespace from the supplied text, and reduces other consecutive whitespace characters to a single space.
    `static String` | `read(InputStream stream)` Read and return the entire contents of the supplied `InputStream`.
    `static String` | `read(Reader reader)` Read and return the entire contents of the supplied `Reader`.
    `static String` | `setLength(String original, int length, char padChar)` Set the length of the string, padding with the supplied character if the supplied string is shorter than desired, or truncating the string if it is longer than desired.
    `static List<String>` | `splitLines(String content)` Split the supplied content into lines, returning each line as an element in the returned list.
    `static String` | `truncate(Object obj, int maxLength)` Truncate the supplied string to be no more than the specified length.
    `static String` | `truncate(Object obj, int maxLength, String suffix)` Truncate the supplied string to be no more than the specified length.
    `static void` | `write(String content, OutputStream stream)` Write the entire contents of the supplied string to the given stream.
    `static void` | `write(String content, Writer writer)` Write the entire contents of the supplied string to the given writer.

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

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

- - ### Field Detail

    - #### EMPTY_STRING_ARRAY

          public static final String[] EMPTY_STRING_ARRAY

  - ### Method Detail

    - #### combineLines

          public static String combineLines(String[] lines)

      Combine the lines into a single string, using the new line character as the delimiter. This is compatible with `splitLines(String)`.
      Parameters:
        `lines` - the lines to be combined
      Returns:
        the combined lines, or an empty string if there are no lines

    - #### combineLines

          public static String combineLines(String[] lines,
                            char separator)

      Combine the lines into a single string, using the supplied separator as the delimiter.
      Parameters:
        `lines` - the lines to be combined
        `separator` - the separator character
      Returns:
        the combined lines, or an empty string if there are no lines

    - #### splitLines

          public static List<String> splitLines(String content)

      Split the supplied content into lines, returning each line as an element in the returned list.
      Parameters:
        `content` - the string content that is to be split
      Returns:
        the list of lines; never null but may be an empty (unmodifiable) list if the supplied content is null or empty

    - #### join

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

      Combine the supplied values into a single string, using the supplied string to delimit values.
      Parameters:
        `values` - the values to be combined; may not be null, but may contain null values (which are skipped)
        `delimiter` - the characters to place between each of the values; may not be null
      Returns:
        the joined string; never null
      See Also:
        `String.split(String)`

    - #### join

          public static String join(Iterable<?> values,
                    String delimiter)

      Combine the supplied values into a single string, using the supplied string to delimit values.
      Parameters:
        `values` - the values to be combined; may not be null, but may contain null values (which are skipped)
        `delimiter` - the characters to place between each of the values; may not be null
      Returns:
        the joined string; never null
      See Also:
        `String.split(String)`

    - #### createString

          public static String createString(String pattern,
                            Object... parameters)

      Create a string by substituting the parameters into all key occurrences in the supplied format. The pattern consists of zero or more keys of the form `{n}`, where `n` is an integer starting at 0. Therefore, the first parameter replaces all occurrences of "{0}", the second parameter replaces all occurrences of "{1}", etc.

      If any parameter is null, the corresponding key is replaced with the string "null". Therefore, consider using an empty string when keys are to be removed altogether.

      If there are no parameters, this method does nothing and returns the supplied pattern as is.

      Parameters:
        `pattern` - the pattern
        `parameters` - the parameters used to replace keys
      Returns:
        the string with all keys replaced (or removed)

    - #### createString

          public static String createString(char charToRepeat,
                            int numberOfRepeats)

      Create a new string containing the specified character repeated a specific number of times.
      Parameters:
        `charToRepeat` - the character to repeat
        `numberOfRepeats` - the number of times the character is to repeat in the result; must be greater than 0
      Returns:
        the resulting string

    - #### setLength

          public static String setLength(String original,
                         int length,
                         char padChar)

      Set the length of the string, padding with the supplied character if the supplied string is shorter than desired, or truncating the string if it is longer than desired. Unlike `justifyLeft(String, int, char)`, this method does not remove leading and trailing whitespace.
      Parameters:
        `original` - the string for which the length is to be set; may not be null
        `length` - the desired length; must be positive
        `padChar` - the character to use for padding, if the supplied string is not long enough
      Returns:
        the string of the desired length
      See Also:
        `justifyLeft(String, int, char)`

    - #### justify

          public static String justify(StringUtil.Justify justify,
                       String str,
                       int width,
                       char padWithChar)

      Justify the contents of the string.
      Parameters:
        `justify` - the way in which the string is to be justified
        `str` - the string to be right justified; if null, an empty string is used
        `width` - the desired width of the string; must be positive
        `padWithChar` - the character to use for padding, if needed
      Returns:
        the right justified string

    - #### justifyRight

          public static String justifyRight(String str,
                            int width,
                            char padWithChar)

      Right justify the contents of the string, ensuring that the string ends at the last character. If the supplied string is longer than the desired width, the leading characters are removed so that the last character in the supplied string at the last position. If the supplied string is shorter than the desired width, the padding character is inserted one or more times such that the last character in the supplied string appears as the last character in the resulting string and that the length matches that specified.
      Parameters:
        `str` - the string to be right justified; if null, an empty string is used
        `width` - the desired width of the string; must be positive
        `padWithChar` - the character to use for padding, if needed
      Returns:
        the right justified string

    - #### justifyLeft

          public static String justifyLeft(String str,
                           int width,
                           char padWithChar)

      Left justify the contents of the string, ensuring that the supplied string begins at the first character and that the resulting string is of the desired length. If the supplied string is longer than the desired width, it is truncated to the specified length. If the supplied string is shorter than the desired width, the padding character is added to the end of the string one or more times such that the length is that specified. All leading and trailing whitespace is removed.
      Parameters:
        `str` - the string to be left justified; if null, an empty string is used
        `width` - the desired width of the string; must be positive
        `padWithChar` - the character to use for padding, if needed
      Returns:
        the left justified string
      See Also:
        `setLength(String, int, char)`

    - #### justifyLeft

          protected static String justifyLeft(String str,
                           int width,
                           char padWithChar,
                           boolean trimWhitespace)

    - #### justifyCenter

          public static String justifyCenter(String str,
                             int width,
                             char padWithChar)

      Center the contents of the string. If the supplied string is longer than the desired width, it is truncated to the specified length. If the supplied string is shorter than the desired width, padding characters are added to the beginning and end of the string such that the length is that specified; one additional padding character is prepended if required. All leading and trailing whitespace is removed before centering.
      Parameters:
        `str` - the string to be left justified; if null, an empty string is used
        `width` - the desired width of the string; must be positive
        `padWithChar` - the character to use for padding, if needed
      Returns:
        the left justified string
      See Also:
        `setLength(String, int, char)`

    - #### truncate

          public static String truncate(Object obj,
                        int maxLength)

      Truncate the supplied string to be no more than the specified length. This method returns an empty string if the supplied object is null.
      Parameters:
        `obj` - the object from which the string is to be obtained using `Object.toString()`.
        `maxLength` - the maximum length of the string being returned
      Returns:
        the supplied string if no longer than the maximum length, or the supplied string truncated to be no longer than the maximum length (including the suffix)
      Throws:
        `IllegalArgumentException` - if the maximum length is negative

    - #### truncate

          public static String truncate(Object obj,
                        int maxLength,
                        String suffix)

      Truncate the supplied string to be no more than the specified length. This method returns an empty string if the supplied object is null.
      Parameters:
        `obj` - the object from which the string is to be obtained using `Object.toString()`.
        `maxLength` - the maximum length of the string being returned
        `suffix` - the suffix that should be added to the content if the string must be truncated, or null if the default suffix of "..." should be used
      Returns:
        the supplied string if no longer than the maximum length, or the supplied string truncated to be no longer than the maximum length (including the suffix)
      Throws:
        `IllegalArgumentException` - if the maximum length is negative

    - #### read

          public static String read(Reader reader)
                             throws IOException

      Read and return the entire contents of the supplied `Reader`. This method always closes the reader when finished reading.
      Parameters:
        `reader` - the reader of the contents; may be null
      Returns:
        the contents, or an empty string if the supplied reader is null
      Throws:
        `IOException` - if there is an error reading the content

    - #### read

          public static String read(InputStream stream)
                             throws IOException

      Read and return the entire contents of the supplied `InputStream`. This method always closes the stream when finished reading.
      Parameters:
        `stream` - the streamed contents; may be null
      Returns:
        the contents, or an empty string if the supplied stream is null
      Throws:
        `IOException` - if there is an error reading the content

    - #### write

          public static void write(String content,
                   OutputStream stream)
                            throws IOException

      Write the entire contents of the supplied string to the given stream. This method always flushes and closes the stream when finished.
      Parameters:
        `content` - the content to write to the stream; may be null
        `stream` - the stream to which the content is to be written
      Throws:
        `IOException`
        `IllegalArgumentException` - if the stream is null

    - #### write

          public static void write(String content,
                   Writer writer)
                            throws IOException

      Write the entire contents of the supplied string to the given writer. This method always flushes and closes the writer when finished.
      Parameters:
        `content` - the content to write to the writer; may be null
        `writer` - the writer to which the content is to be written
      Throws:
        `IOException`
        `IllegalArgumentException` - if the writer is null

    - #### getStackTrace

          public static String getStackTrace(Throwable throwable)

      Get the stack trace of the supplied exception.
      Parameters:
        `throwable` - the exception for which the stack trace is to be returned
      Returns:
        the stack trace, or null if the supplied exception is null

    - #### normalize

          public static String normalize(String text)

      Removes leading and trailing whitespace from the supplied text, and reduces other consecutive whitespace characters to a single space. Whitespace includes line-feeds.
      Parameters:
        `text` - the text to be normalized
      Returns:
        the normalized text

    - #### getHexString

          public static String getHexString(byte[] bytes)

      Get the hexadecimal string representation of the supplied byte array.
      Parameters:
        `bytes` - the byte array
      Returns:
        the hex string representation of the byte array; never null

    - #### fromHexString

          public static byte[] fromHexString(String hexadecimal)

    - #### isHexString

          public static boolean isHexString(String hexadecimal)

    - #### isHexCharacter

          public static boolean isHexCharacter(char c)

    - #### isBlank

          public static boolean isBlank(String str)

      Returns true if the given string is null or represents the empty string
      Parameters:
        `str` - the string; may be null or empty
      Returns:
        true if the string is null or contains only whitespace

    - #### containsAnyOf

          public static boolean containsAnyOf(String str,
                              char... chars)

      Return whether the supplied string contains any of the supplied characters.
      Parameters:
        `str` - the string to be examined; may not be null
        `chars` - the characters to be found within the supplied string; may be zero-length
      Returns:
        true if the supplied string contains at least one of the supplied characters, or false otherwise

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.