String (Groovy JDK enhancements)

Package: java.lang

## Class String

- - ### Methods Summary

    Methods
    Return type | Name and parameters
    --- | ---
    `Object` | `asType(Class c)` Provides a method to perform custom 'dynamic' type conversion to the given class using the `as` operator.
    `String` | `collectReplacements(Closure transform)` Iterates through this String a character at a time collecting either the original character or a transformed replacement String.
    `String` | `collectReplacements(List transforms)` Iterates through this String a character at a time collecting either the original character or a transformed replacement String.
    `byte[]` | `decodeBase64()` Decode the String from Base64 into a byte array.
    `byte[]` | `decodeBase64Url()` Decodes a Base64 URL and Filename Safe encoded String into a byte array.
    `byte[]` | `decodeHex()` Decodes a hex string to a byte array.
    `String` | `drop(int num)` A String variant of the equivalent CharSequence method.
    `String` | `dropRight(int num)` A String variant of the equivalent CharSequence method CharSequence#dropRight(int).
    `String` | `eachMatch(String regex, Closure closure)` Process each regex group matched substring of the given string.
    `String` | `eachMatch(Pattern pattern, Closure closure)` Processes each regex group matched substring of the given pattern.
    `Process` | `execute()` Executes the command specified by `self` as a command-line process.
    `Process` | `execute(String[] envp, File dir)` Executes the command specified by `self` with environment defined by `envp` and under the working directory `dir`.
    `Process` | `execute(List envp, File dir)` Executes the command specified by `self` with environment defined by `envp` and under the working directory `dir`.
    `String` | `getAt(IntRange range)` Supports the range subscript operator for String with IntRange.
    `String` | `getAt(Range range)` Supports the range subscript operator for String.
    `String` | `getAt(int index)` Supports the subscript operator for String.
    `Boolean` | `isAtLeast(String right)` Compares a String representing a number to another.
    `StringBuffer` | `leftShift(Object value)` Overloads the left shift operator to provide an easy way to append multiple objects as string representations to a String.
    `String` | `plus(CharSequence right)` Appends the String representation of the given operand to this string.
    `String` | `take(int num)` A String variant of the equivalent CharSequence method.
    `String` | `takeAfter(CharSequence searchString)` A String variant of the equivalent CharSequence method CharSequence#takeAfter(CharSequence).
    `String` | `takeBefore(String searchString)` A String variant of the equivalent CharSequence method CharSequence#takeBefore(CharSequence).
    `String` | `takeBetween(CharSequence enclosure)` A String variant of the equivalent CharSequence method CharSequence#takeBetween(CharSequence).
    `String` | `takeBetween(CharSequence enclosure, int occurrence)` A String variant of the equivalent CharSequence method CharSequence#takeBetween(CharSequence, int).
    `String` | `takeBetween(CharSequence from, CharSequence to)` A String variant of the equivalent CharSequence method CharSequence#takeBetween(CharSequence, CharSequence).
    `String` | `takeBetween(CharSequence from, CharSequence to, int occurrence)` A String variant of the equivalent CharSequence method CharSequence#takeBetween(CharSequence, CharSequence, int).
    `String` | `takeRight(int num)` A GString variant of the equivalent CharSequence method CharSequence#takeRight(int).
    `Boolean` | `toBoolean()` Converts the given string into a Boolean object.
    `Character` | `toCharacter()` Converts the given string into a Character object using the first character in the string.
    `URI` | `toURI()` Transforms a String representing a URI into a URI object.
    `URL` | `toURL()` Transforms a String representing a URL into a URL object.

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

    `addShutdownHook`, `any`, `any`, `asBoolean`, `asType`, `collect`, `collect`, `collect`, `dump`, `each`, `eachMatch`, `eachMatch`, `eachWithIndex`, `every`, `every`, `find`, `find`, `findAll`, `findAll`, `findIndexOf`, `findIndexOf`, `findIndexValues`, `findIndexValues`, `findLastIndexOf`, `findLastIndexOf`, `findResult`, `findResult`, `findResult`, `findResult`, `getAt`, `getMetaClass`, `getMetaPropertyValues`, `getProperties`, `grep`, `grep`, `hasProperty`, `identity`, `inject`, `inject`, `inspect`, `invokeMethod`, `is`, `isCase`, `isNotCase`, `iterator`, `metaClass`, `print`, `print`, `printf`, `printf`, `println`, `println`, `println`, `putAt`, `respondsTo`, `respondsTo`, `setMetaClass`, `split`, `sprintf`, `sprintf`, `stream`, `tap`, `toString`, `use`, `use`, `use`, `with`, `with`, `withCloseable`, `withStream`, `withTraits`

  - #### Methods inherited from interface java.lang.CharSequence

    `asBoolean`, `asType`, `bitwiseNegate`, `capitalize`, `center`, `center`, `contains`, `containsIgnoreCase`, `count`, `denormalize`, `digest`, `drop`, `dropRight`, `dropWhile`, `eachLine`, `eachLine`, `endsWithAny`, `endsWithIgnoreCase`, `expand`, `expand`, `expandLine`, `find`, `find`, `find`, `find`, `findAll`, `findAll`, `findAll`, `findAll`, `getAt`, `getAt`, `getAt`, `getAt`, `getAt`, `getChars`, `isAllWhitespace`, `isBigDecimal`, `isBigInteger`, `isBlank`, `isCase`, `isDouble`, `isFloat`, `isInteger`, `isLong`, `isNotCase`, `isNumber`, `leftShift`, `matches`, `md5`, `minus`, `minus`, `multiply`, `next`, `normalize`, `padLeft`, `padLeft`, `padRight`, `padRight`, `plus`, `previous`, `readLines`, `replace`, `replace`, `replaceAll`, `replaceAll`, `replaceAll`, `replaceAll`, `replaceFirst`, `replaceFirst`, `replaceFirst`, `replaceFirst`, `reverse`, `sha256`, `size`, `split`, `splitEachLine`, `splitEachLine`, `startsWithAny`, `startsWithIgnoreCase`, `stripIndent`, `stripIndent`, `stripIndent`, `stripMargin`, `stripMargin`, `stripMargin`, `take`, `takeAfter`, `takeBefore`, `takeBetween`, `takeBetween`, `takeBetween`, `takeBetween`, `takeRight`, `takeWhile`, `toBigDecimal`, `toBigInteger`, `toDouble`, `toFloat`, `toInteger`, `toList`, `toLong`, `toSet`, `toShort`, `toURI`, `toURL`, `tokenize`, `tokenize`, `tokenize`, `tr`, `uncapitalize`, `unexpand`, `unexpand`, `unexpandLine`

  - #### Methods inherited from interface java.lang.Comparable

    `numberAwareCompareTo`

- - ### Methods Detail

    - #### public Object asType(Class c)

      Provides a method to perform custom 'dynamic' type conversion to the given class using the `as` operator.

      Example: `'123' as Double`

      By default, the following types are supported:

      - List
      - BigDecimal
      - BigInteger
      - Long
      - Integer
      - Short
      - Byte
      - Character
      - Double
      - Float
      - File
      - Subclasses of Enum
      If any other type is given, the call is delegated to DefaultGroovyMethods#asType(Object,Class).
      Parameters:
        `c` - the desired class
      Returns:
        the converted object
      Since:
        1.0

    - #### public String collectReplacements(Closure transform)

      Iterates through this String a character at a time collecting either the original character or a transformed replacement String. The `transform` Closure should return `null` to indicate that no transformation is required for the given character.

          assert "Groovy".collectReplacements{ it == 'o' ? '_O_' : null } == 'Gr_O__O_vy'
          assert "Groovy".collectReplacements{ it.equalsIgnoreCase('O') ? '_O_' : null } == 'Gr_O__O_vy'
          assert "Groovy".collectReplacements{ char c -> c == 'o' ? '_O_' : null } == 'Gr_O__O_vy'
          assert "Groovy".collectReplacements{ Character c -> c == 'o' ? '_O_' : null } == 'Gr_O__O_vy'
          assert "B&W".collectReplacements{ it == '&' ? '&' : null } == 'B&W'

      Parameters:
      Returns:
        A new string in which all characters that require escaping have been replaced with the corresponding replacements as determined by the `transform` Closure.
      Since:
        2.1.0

    - #### public String collectReplacements(List transforms)

      Iterates through this String a character at a time collecting either the original character or a transformed replacement String. The return value is an `Optional` either having a value equal to the transformed replacement String or `empty()` to indicate that no transformation is required.

          import java.util.function.Function
          import static java.util.Optional.*

          Function<Character, Optional<String>> xform1 = s -> s == 'o' ? of('_O') : empty()
          Function<Character, Optional<String>> xform2 = { it == 'G' ? of('G_') : empty() }
          assert "Groovy".collectReplacements([xform1, xform2]) == 'G_r_O_Ovy'

      Parameters:
        `transforms` - one or more transforms which potentially convert a single character to a transformed string
      Returns:
        A new string in which all characters that require escaping have been replaced with the corresponding replacements as determined by the `transform` function.
      Since:
        3.0.6

    - #### public byte[] decodeBase64()

      Decode the String from Base64 into a byte array.

      Returns:
        the decoded bytes as an array
      Since:
        1.0

    - #### public byte[] decodeBase64Url()

      Decodes a Base64 URL and Filename Safe encoded String into a byte array.

      Returns:
        the decoded bytes as an array
      Since:
        2.5.0

    - #### public byte[] decodeHex()

      Decodes a hex string to a byte array. The hex string can contain either upper case or lower case letters.

      Returns:
        decoded byte array

    - #### public String drop(int num)

      A String variant of the equivalent CharSequence method.

      Parameters:
        `num` - the number of characters to drop from this String
      Returns:
        a String consisting of all characters except the first `num` ones, or else an empty String, if the String has less than `num` characters.
      Since:
        2.5.5
      See Also:
        CharSequence#drop(int)

    - #### public String dropRight(int num)

      A String variant of the equivalent CharSequence method CharSequence#dropRight(int).

      Parameters:
        `num` - number of characters
      Returns:
        String after removing the right `num` chars and empty of the `num` is greater than the length of the CharSequence
      Since:
        3.0.0

    - #### public String eachMatch(String regex, Closure closure)

      Process each regex group matched substring of the given string. If the closure parameter takes one argument, an array with all match groups is passed to it. If the closure takes as many arguments as there are match groups, then each parameter will be one match group.

      Parameters:
        `regex` - a Regex string
        `closure` - a closure with one parameter or as many parameters as groups
      Returns:
        the source string
      Since:
        1.6.0

    - #### public String eachMatch(Pattern pattern, Closure closure)

      Processes each regex group matched substring of the given pattern. If the closure parameter takes one argument, an array with all match groups is passed to it. If the closure takes as many arguments as there are match groups, then each parameter will be one match group.

      Parameters:
        `pattern` - a regex Pattern
        `closure` - a closure with one parameter or as many parameters as groups
      Returns:
        the source string
      Since:
        1.6.1

    - #### public Process execute()

      Executes the command specified by `self` as a command-line process.

      For more control over Process construction you can use `java.lang.ProcessBuilder`.

      Returns:
        the Process which has just started for this command line representation
      Since:
        1.0

    - #### public Process execute(String[] envp, File dir)

      Executes the command specified by `self` with environment defined by `envp` and under the working directory `dir`.

      For more control over Process construction you can use `java.lang.ProcessBuilder`.

      Parameters:
        `envp` - an array of Strings, each element of which has environment variable settings in the format name=value, or `null` if the subprocess should inherit the environment of the current process.
        `dir` - the working directory of the subprocess, or `null` if the subprocess should inherit the working directory of the current process.
      Returns:
        the Process which has just started for this command line representation.
      Since:
        1.0

    - #### public Process execute(List envp, File dir)

      Executes the command specified by `self` with environment defined by `envp` and under the working directory `dir`.

      For more control over Process construction you can use `java.lang.ProcessBuilder`.

      Parameters:
        `envp` - a List of Objects (converted to Strings using toString), each member of which has environment variable settings in the format name=value, or `null` if the subprocess should inherit the environment of the current process.
        `dir` - the working directory of the subprocess, or `null` if the subprocess should inherit the working directory of the current process.
      Returns:
        the Process which has just started for this command line representation.
      Since:
        1.0

    - #### public String getAt(IntRange range)

      Supports the range subscript operator for String with IntRange.

      Parameters:
        `range` - an IntRange
      Returns:
        the resulting String
      Since:
        1.0

    - #### public String getAt(Range range)

      Supports the range subscript operator for String.

      Parameters:
        `range` - a Range
      Returns:
        a substring corresponding to the Range
      Since:
        1.0

    - #### public String getAt(int index)

      Supports the subscript operator for String.

      Parameters:
        `index` - the index of the Character to get
      Returns:
        the Character at the given index
      Since:
        1.0

    - #### public Boolean isAtLeast(String right)

      Compares a String representing a number to another. A fluent API style alias for `compareTo` on `BigDecimal`.

      Parameters:
        `right` - a String representing a number
      Returns:
        true if the value represented by left is equal to or bigger than the value represented by right
      Since:
        3.0.1

    - #### public StringBuffer leftShift(Object value)

      Overloads the left shift operator to provide an easy way to append multiple objects as string representations to a String.

      Parameters:
        `value` - an Object
      Returns:
        a StringBuffer built from this string
      Since:
        1.0

    - #### public String plus(CharSequence right)

      Appends the String representation of the given operand to this string.

      Parameters:
        `right` - any CharSequence
      Returns:
        the new string with the object appended
      Since:
        2.2

    - #### public String take(int num)

      A String variant of the equivalent CharSequence method.

      Parameters:
        `num` - the number of chars to take from this String
      Returns:
        a String consisting of the first `num` chars, or else the whole String if it has less than `num` elements.
      Since:
        2.5.5

    - #### public String takeAfter(CharSequence searchString)

      A String variant of the equivalent CharSequence method CharSequence#takeAfter(CharSequence).

      Parameters:
        `searchString` - String that is searched in this CharSequence
      Returns:
        String that is after the given searchString and empty string if it does not exist
      Since:
        3.0.0

    - #### public String takeBefore(String searchString)

      A String variant of the equivalent CharSequence method CharSequence#takeBefore(CharSequence).

      Parameters:
        `searchString` - CharSequence that is searched in this CharSequence
      Returns:
        String that is before the given searchString
      Since:
        3.0.0

    - #### public String takeBetween(CharSequence enclosure)

      A String variant of the equivalent CharSequence method CharSequence#takeBetween(CharSequence).

      Parameters:
        `enclosure` - Enclosure CharSequence
      Returns:
        String between the 2 subsequent `enclosure` strings
      Since:
        3.0.0

    - #### public String takeBetween(CharSequence enclosure, int occurrence)

      A String variant of the equivalent CharSequence method CharSequence#takeBetween(CharSequence, int).

      Parameters:
        `enclosure` - Enclosure CharSequence
        `occurrence` - nth occurrence being returned
      Returns:
        String between the nth occurrence of pair of `enclosure` strings
      Since:
        3.0.0

    - #### public String takeBetween(CharSequence from, CharSequence to)

      A String variant of the equivalent CharSequence method CharSequence#takeBetween(CharSequence, CharSequence).

      Parameters:
        `from` - beginning of search
        `to` - end of search
      Returns:
        String that is in between the given two CharSequences and empty if the unavailable inputs are given
      Since:
        3.0.0

    - #### public String takeBetween(CharSequence from, CharSequence to, int occurrence)

      A String variant of the equivalent CharSequence method CharSequence#takeBetween(CharSequence, CharSequence, int).

      Parameters:
        `from` - beginning of search
        `to` - end of search
        `occurrence` - nth occurrence that is to be returned. 0 represents first one
      Returns:
        the String that is in between the given nth (specified by occurrence) pair of `from` and `to` CharSequences and empty if the unavailable inputs are given.
      Since:
        3.0.0

    - #### public String takeRight(int num)

      A GString variant of the equivalent CharSequence method CharSequence#takeRight(int).

      Parameters:
        `num` - the number of chars to take from this CharSequence from the right
      Returns:
        a String consisting of the last `num` chars, or else the whole CharSequence if it has less than `num` elements.
      Since:
        3.0.0

    - #### public Boolean toBoolean()

      Converts the given string into a Boolean object. If the trimmed string is "true", "y" or "1" (ignoring case) then the result is true otherwise it is false.

      Returns:
        The Boolean value
      Since:
        1.0

    - #### public Character toCharacter()

      Converts the given string into a Character object using the first character in the string.

      Returns:
        the first Character
      Since:
        1.0

    - #### public URI toURI()

      Transforms a String representing a URI into a URI object.

      Returns:
        a URI
      Since:
        1.0

    - #### public URL toURL()

      Transforms a String representing a URL into a URL object.

      Returns:
        a URL
      Since:
        1.0