Package com.norconex.commons.lang.text

# Class StringUtil

java.lang.Object
com.norconex.commons.lang.text.StringUtil

public final class StringUtil extends Object
String-related utility methods not found in popular libraries.

Since:
  1.14.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `TRUNCATE_HASH_LENGTH`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static int`
  `countMatchesEnd(String str, String sub)`
  Counts the number of consecutive matches at end of a a string.
  `static int`
  `countMatchesStart(String str, String sub)`
  Counts the number of consecutive matches from the beginning of a string.
  `static void`
  `ifBlank(String str, Runnable runnable)`
  Consume the given string only if it is blank.
  `static void`
  `ifNotBlank(String str, Consumer<String> consumer)`
  Consume the given string only if it is not blank.
  `static String`
  `singular(String plural)`
  Converts an English plural word to singular one using very simple heuristics.
  `static String`
  `singularOrElse(String plural, String defaultValue)`
  Converts an English plural word to singular one using very simple heuristics.
  `static String`
  `trimEnd(String str)`
  Trims white spaces at the end of a string.
  `static String`
  `trimStart(String str)`
  Trims white spaces at the beginning of a string.
  `static byte[]`
  `truncateBytesWithHash(byte[] bytes, Charset charset, int maxByteLength)`
  Truncates character byte array text larger than the given max byte length and appends a hash value from the truncated text.
  `static byte[]`
  `truncateBytesWithHash(byte[] bytes, Charset charset, int maxByteLength, String separator)`
  Truncates character byte array text larger than the given max byte length and appends a hash value from the truncated text, with an optional separator in-between.
  `static String`
  `truncateBytesWithHash(String text, Charset charset, int maxByteLength)`
  Truncates text with size in bytes larger than the given max byte length and appends a hash value from the truncated text.
  `static String`
  `truncateBytesWithHash(String text, Charset charset, int maxByteLength, String separator)`
  Truncates text with size in bytes larger than the given max byte length and appends a hash value from the truncated text, with an optional separator in-between.
  `static String`
  `truncateWithHash(String text, int maxLength)`
  Truncate text larger than the given max length and appends a hash value from the truncated text.
  `static String`
  `truncateWithHash(String text, int maxLength, String separator)`
  Truncate text larger than the given max length and appends a hash value from the truncated text, with an optional separator in-between.

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

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

- ## Field Details

  - ### TRUNCATE_HASH_LENGTH

    public static final int TRUNCATE_HASH_LENGTH
    See Also:
      - Constant Field Values

- ## Method Details

  - ### ifBlank

    public static void ifBlank(String str, Runnable runnable)
    Consume the given string only if it is blank.
    Parameters:
      `str` - the string to consume
      `runnable` - code to be executed
    Since:
      3.0.0

  - ### ifNotBlank

    public static void ifNotBlank(String str, Consumer<String> consumer)
    Consume the given string only if it is not blank.
    Parameters:
      `str` - the string to consume
      `consumer` - string consumer
    Since:
      3.0.0

  - ### truncateWithHash

    public static String truncateWithHash(String text, int maxLength)
    Truncate text larger than the given max length and appends a hash value from the truncated text. The hash size has 10 digits. The hash is added to fit within the maximum length supplied. For this reason, the `maxLength` argument must be be minimum 10 for any truncation to occur. The hash is added without a separator. To insert a separator between the truncated text and the hash code, use `truncateWithHash(String, int, String)`
    Parameters:
      `text` - text to truncate
      `maxLength` - maximum length the truncated text must have
    Returns:
      truncated text, or original text if no truncation required

  - ### truncateWithHash

    public static String truncateWithHash(String text, int maxLength, String separator)
    Truncate text larger than the given max length and appends a hash value from the truncated text, with an optional separator in-between. The hash size has 10 digits. The hash and separator are added to fit within the maximum length supplied. For this reason, the `maxLength` argument must be be minimum 10 + separator length for any truncation to occur.
    Parameters:
      `text` - text to truncate
      `maxLength` - maximum length the truncated text must have
      `separator` - string separating truncated text from hash code
    Returns:
      truncated text, or original text if no truncation required

  - ### truncateBytesWithHash

    public static String truncateBytesWithHash(String text, Charset charset, int maxByteLength) throws CharacterCodingException
    Truncates text with size in bytes larger than the given max byte length and appends a hash value from the truncated text. The hash size is equal to the byte length of 10 digits using the given charset. The hash and separator are added to fit within the maximum byte length supplied. For this reason, the `maxByteLength` argument must be be large enough for any truncation to occur.
    Parameters:
      `text` - text to truncate
      `charset` - character encoding
      `maxByteLength` - maximum byte length the truncated text must have
    Returns:
      truncated character byte array, or original text if no truncation required
    Throws:
      `CharacterCodingException` - character coding problem

  - ### truncateBytesWithHash

    public static String truncateBytesWithHash(String text, Charset charset, int maxByteLength, String separator) throws CharacterCodingException
    Truncates text with size in bytes larger than the given max byte length and appends a hash value from the truncated text, with an optional separator in-between. The hash size is equal to the byte length of 10 digits using the given charset. The hash and separator are added to fit within the maximum byte length supplied. For this reason, the `maxByteLength` argument must be be large enough for any truncation to occur.
    Parameters:
      `text` - text to truncate
      `charset` - character encoding
      `maxByteLength` - maximum byte length the truncated text must have
      `separator` - string separating truncated text from hash code
    Returns:
      truncated character byte array, or original text if no truncation required
    Throws:
      `CharacterCodingException` - character coding problem

  - ### truncateBytesWithHash

    public static byte[] truncateBytesWithHash(byte[] bytes, Charset charset, int maxByteLength) throws CharacterCodingException
    Truncates character byte array text larger than the given max byte length and appends a hash value from the truncated text. The hash size is equal to the byte length of 10 digits using the given charset. The hash and separator are added to fit within the maximum byte length supplied. For this reason, the `maxByteLength` argument must be be large enough for any truncation to occur.
    Parameters:
      `bytes` - byte array of text to truncate
      `charset` - character encoding
      `maxByteLength` - maximum byte length the truncated text must have
    Returns:
      truncated character byte array, or original text if no truncation required
    Throws:
      `CharacterCodingException` - character coding problem

  - ### truncateBytesWithHash

    public static byte[] truncateBytesWithHash(byte[] bytes, Charset charset, int maxByteLength, String separator) throws CharacterCodingException
    Truncates character byte array text larger than the given max byte length and appends a hash value from the truncated text, with an optional separator in-between. The hash size is equal to the byte length of 10 digits using the given charset. The hash and separator are added to fit within the maximum byte length supplied. For this reason, the `maxByteLength` argument must be be large enough for any truncation to occur.
    Parameters:
      `bytes` - byte array of text to truncate
      `charset` - character encoding
      `maxByteLength` - maximum byte length the truncated text must have
      `separator` - string separating truncated text from hash code
    Returns:
      truncated character byte array, or original text if no truncation required
    Throws:
      `CharacterCodingException` - character coding problem

  - ### trimEnd

    public static String trimEnd(String str)
    Trims white spaces at the end of a string.
    Parameters:
      `str` - the string to trim its end
    Returns:
      trimmed string
    Since:
      2.0.0

  - ### trimStart

    public static String trimStart(String str)
    Trims white spaces at the beginning of a string.
    Parameters:
      `str` - the string to trim its beginning
    Returns:
      trimmed string
    Since:
      2.0.0

  - ### countMatchesEnd

    public static int countMatchesEnd(String str, String sub)
    Counts the number of consecutive matches at end of a a string.
    Parameters:
      `str` - the string to check
      `sub` - the substring to count
    Returns:
      number of matches from the start
    Since:
      2.0.0

  - ### countMatchesStart

    public static int countMatchesStart(String str, String sub)
    Counts the number of consecutive matches from the beginning of a string.
    Parameters:
      `str` - the string to check
      `sub` - the substring to count
    Returns:
      number of matches from the end
    Since:
      2.0.0

  - ### singular

    public static String singular(String plural)
    Converts an English plural word to singular one using very simple heuristics. Returns `null` if the plural word is `null`. Else, returns the word unchanged if it cannot find a singular variant. You are encouraged to used a more sophisticated approach if accuracy is important.
    Parameters:
      `plural` - plural word
    Returns:
      singular word
    Since:
      3.0.0

  - ### singularOrElse

    public static String singularOrElse(String plural, String defaultValue)
    Converts an English plural word to singular one using very simple heuristics. Returns `null` if the plural word is `null`. Else, returns the default value if it cannot find a singular variant. You are encouraged to used a more sophisticated approach if accuracy is important.
    Parameters:
      `plural` - plural word
      `defaultValue` - default value if singular can't be resolved
    Returns:
      singular word or `null`
    Since:
      3.0.0