# Class: com.pnfsoftware.jeb.util.format.Strings

Utility methods for Strings and CharSequences.

## Constructor: Strings


## Static Field: LINESEP
Type: `java.lang.String`
Description: Line\-separator for \*this\* platform.

## Static Method: camelCaseToString
- parameter: `s`, type: `java.lang.String`
- parameter: `breakOnDigits`, type: `boolean`
- parameter: `keepUppercaseAcronyms`, type: `boolean`
- return type: `java.lang.String`

Description: Convert a camel\-case string to a sentence. Example: 

```

 ThisIsACamelCaseString    -> This is a camel case string
 ThisIsACamel44CaseString  -> This is a camel44 case string
 CountryUSA                -> Country u s a

 with breakOnDigits=true:
 ThisIsACamel44CaseString  -> This is a camel 44 case string

 with keepUppercaseAcronyms=true:
 CountryUSA                -> Country USA
 
```
 A legal camel\-case string always starts with an upper\-case letter, and does not contain whitespace characters.
parameter: s: the input camel\-case string
parameter: breakOnDigits: if true, base\-10 numbers will also be used as breaks
parameter: keepUppercaseAcronyms: keep 2\+ upper\-case letter acronyms intact, eg:            `CountryUSA` would be converted to `Country USA` instead of            `Country u s a`
return: the result sentence
throws: if the input string was not camel\-case formatted

## Static Method: camelCaseToString
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Convert a camel\-case string to a sentence. Example: 

```

 ThisIsACamelCaseString -> This is a camel case string
 
```
 A legal camel\-case string always starts with an upper\-case letter, and does not contain whitespace characters.
parameter: s: the input camel\-case string
return: the result sentence
throws: if the input string was not camel\-case formatted

## Static Method: capitalizeFirst
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Capitalize the first character of a string.
parameter: s: input string
return: the input string with its first character converted to upper\-case, when applicable

## Static Method: contains
- parameter: `s`, type: `java.lang.String`
- parameter: `elts`, type: `java.lang.String[]`
- return type: `boolean`

Description: A many\-element variant of [String.contains](String#contains(CharSequence)).
parameter: s: the string
parameter: elts: a list of string elements
return: true if the string contains at least one of the provided elements

## Static Method: containsAt
- parameter: `s`, type: `java.lang.String`
- parameter: `index`, type: `int`
- parameter: `elt`, type: `java.lang.String`
- return type: `boolean`

Description: Indicates if a String s contains a particular substring at a specified index. Semantically equivalent to `s.substring(i).startsWith(elt)` without intermediate substring creation.
parameter: s: the string
parameter: index: String index to look at
parameter: elt: element to identify
return: true if s.substring\(i\).startsWith\(elt\) returns true

## Static Method: count
- parameter: `str`, type: `java.lang.String`
- parameter: `ch`, type: `char`
- return type: `int`

Description: Count the number of occurrences of a character within a string.
parameter: str: haystack
parameter: ch: needle
return: the number of occurrences

## Static Method: count
- parameter: `str`, type: `java.lang.String`
- parameter: `sub`, type: `java.lang.String`
- parameter: `countOverlaps`, type: `boolean`
- return type: `int`

Description: Count the number of occurrences of a sub\-string within a string. 

 Note: a search for 'aaa' inside 'aaaaaa' would return 4, not 2\!
parameter: str: haystack
parameter: sub: needle \(if empty, the method returns 0\)
parameter: countOverlaps: if true, a search for 'aaa' inside 'aaaaaa' will return 4 instead of 2
return: the number of occurrences

## Static Method: countNonBlankCharacters
- parameter: `s`, type: `java.lang.CharSequence`
- return type: `int`

Description: Count the number of non blank characters in the provided string.
parameter: s: character sequence to scan
return: the number of non\-whitespace characters

## Static Method: decodeASCII
- parameter: `bytes`, type: `byte[]`
- parameter: `offset`, type: `int`
- parameter: `length`, type: `int`
- return type: `java.lang.String`

Description: Decode a byte buffer using an ASCII decoder. If the decoder is not available, the byte buffer is decoded using the system's default decoder.
parameter: bytes: byte buffer
parameter: offset: start offset
parameter: length: count of bytes to be decoded
return: the decoded string

## Static Method: decodeASCII
- parameter: `bytes`, type: `byte[]`
- return type: `java.lang.String`

Description: Decode a byte buffer using an ASCII decoder. If the decoder is not available, the byte buffer is decoded using the system's default decoder.
parameter: bytes: mandatory byte buffer
return: the decoded string

## Static Method: decodeArray
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String[]`

Description: Decode an encoded array of objects.
parameter: s: the encoded array
return: the array of decoded strings

## Static Method: decodeList
- parameter: `s`, type: `java.lang.String`
- return type: `java.util.List<java.lang.String>`

Description: Decode an encoded list of objects.
parameter: s: optional encoded list
return: the list of decoded strings

## Static Method: decodeLocal
- parameter: `bytes`, type: `byte[]`
- parameter: `offset`, type: `int`
- parameter: `length`, type: `int`
- return type: `java.lang.String`

Description: Decode a byte buffer using the local platform's default charset. This method is potentially dangerous.
parameter: bytes: byte buffer
parameter: offset: start offset
parameter: length: count of bytes to be decoded
return: the decoded string

## Static Method: decodeLocal
- parameter: `bytes`, type: `byte[]`
- return type: `java.lang.String`

Description: Decode a byte buffer using the local platform's default charset. This method is potentially dangerous.
parameter: bytes: mandatory byte buffer
return: the decoded string

## Static Method: decodeMap
- parameter: `s`, type: `java.lang.String`
- return type: `java.util.Map<java.lang.String,java.lang.String>`

Description: Decode an encoded map.
parameter: s: optional encoded map
return: the decoded map

## Static Method: decodeUTF8
- parameter: `bytes`, type: `byte[]`
- parameter: `offset`, type: `int`
- parameter: `length`, type: `int`
- return type: `java.lang.String`

Description: Decode a byte buffer using a UTF\-8 decoder. If the decoder is not available, the byte buffer is decoded using the system's default decoder.
parameter: bytes: byte buffer
parameter: offset: start offset
parameter: length: count of bytes to be decoded
return: the decoded string

## Static Method: decodeUTF8
- parameter: `bytes`, type: `byte[]`
- return type: `java.lang.String`

Description: Decode a byte buffer using a UTF\-8 decoder. If the decoder is not available, the byte buffer is decoded using the system's default decoder.
parameter: bytes: mandatory byte buffer
return: the decoded string

## Static Method: decodeUTF8Ex
- parameter: `bytes`, type: `byte[]`
- parameter: `useStandardDecoderFirst`, type: `boolean`
- return type: `java.lang.String`

Description: Decode UTF\-8 bytes back to a string. Sub\-optimal encodings of characters are processed as normal.
parameter: bytes: bytes to decode
parameter: useStandardDecoderFirst: true to attempt standard UTF\-8 decoding before the permissive            decoder
return: the decoded string

## Static Method: decodeUTF8Ex
- parameter: `bytes`, type: `byte[]`
- parameter: `off`, type: `int`
- parameter: `len`, type: `int`
- parameter: `useStandardDecoderFirst`, type: `boolean`
- return type: `java.lang.String`

Description: Decode UTF\-8 bytes back to a string. Sub\-optimal encodings of characters are processed as normal.
parameter: bytes: bytes to decode
parameter: off: start offset
parameter: len: number of bytes to decode
parameter: useStandardDecoderFirst: true to attempt standard UTF\-8 decoding before the permissive            decoder
return: the decoded string

## Static Method: determinePotentialEncoding
- parameter: `data`, type: `byte[]`
- parameter: `offset`, type: `int`
- parameter: `size`, type: `int`
- return type: `java.nio.charset.Charset`

Description: Heuristically determine the encoding of a string.
parameter: data: byte buffer to analyze
parameter: offset: start offset in `data`
parameter: size: number of bytes to analyze
return: null if unknown, else one of ASCII, UTF\-8, UTF\-16, UTF\-16LE, UTF\-16BE, UTF\-32LE or         UTF\-32BE

## Static Method: encodeASCII
- parameter: `s`, type: `java.lang.String`
- return type: `byte[]`

Description: Encode a string using an ASCII encoder. If the encoder is not available, the string is encoded using the system's default encoder. This should never happen.
parameter: s: mandatory string
return: the encoded byte buffer

## Static Method: encodeArray
- parameter: `array`, type: `java.lang.Object[]`
- return type: `java.lang.String`

Description: Encode an array of objects.
parameter: array: the array of objects
return: the encoded array as a string

## Static Method: encodeBinary
- parameter: `s`, type: `java.lang.String`
- return type: `byte[]`

Description: Generate a byte array consisting of the low\-bytes of the input string characters.
parameter: s: string to encode
return: a byte array containing the low byte of each input character

## Static Method: encodeList
- parameter: `list`, type: `java.util.List<?>`
- return type: `java.lang.String`

Description: Encode a list of objects.
parameter: list: the list of objects
return: the encoded list as a string

## Static Method: encodeLocal
- parameter: `s`, type: `java.lang.String`
- return type: `byte[]`

Description: Encode a string using the local platform's default charset. This method is potentially dangerous.
parameter: s: mandatory string
return: the encoded byte buffer

## Static Method: encodeMap
- parameter: `map`, type: `java.util.Map<?,?>`
- return type: `java.lang.String`

Description: Encode a dictionary. The encoding scheme will produce strings like: `encodedKey1=encodedValue1&encodedKey2=encodedValue2&...`
parameter: map: the map of key/values
return: the encoded map as a string

## Static Method: encodeUTF8
- parameter: `s`, type: `java.lang.String`
- return type: `byte[]`

Description: Encode a string using a UTF\-8 encoder. If the encoder is not available, the string is encoded using the system's default encoder. This should never happen.
parameter: s: mandatory string
return: the encoded byte buffer

## Static Method: endsWith
- parameter: `s`, type: `java.lang.String`
- parameter: `elts`, type: `java.lang.String[]`
- return type: `boolean`

Description: A many\-element variant of [String.endsWith](String#endsWith(String)).
parameter: s: the string
parameter: elts: a list of string elements
return: true if the string ends with one of the provided elements

## Static Method: equals
- parameter: `a`, type: `java.lang.String`
- parameter: `b`, type: `java.lang.String`
- return type: `boolean`

Description: A safer version of [String#equals(Object)](String#equals(Object)).
parameter: a: first string, may be null
parameter: b: second string, may be null
return: true iff both strings are non\-null and equals

## Static Method: equalsIgnoreCase
- parameter: `a`, type: `java.lang.String`
- parameter: `b`, type: `java.lang.String`
- return type: `boolean`

Description: A safer version of [String#equalsIgnoreCase(String)](String#equalsIgnoreCase(String))
parameter: a: first string, may be null
parameter: b: second string, may be null
return: true iff both strings are non\-null and iequals

## Static Method: f
- parameter: `format`, type: `java.lang.String`
- parameter: `args`, type: `java.lang.Object[]`
- return type: `java.lang.String`

Description: Format using the US locale.
parameter: format: format string
parameter: args: format arguments
return: the formatted string

## Static Method: ff
- parameter: `l`, type: `java.util.Locale`
- parameter: `sink`, type: `java.lang.Appendable`
- parameter: `format`, type: `java.lang.String`
- parameter: `args`, type: `java.lang.Object[]`
- return type: `java.lang.Appendable`

Description: A faster version of [String#format(String, Object...)](String#format(String, Object...)). 

 Implementation note: currently limited to formatters `%b %c %d %0{2,4,8}{x,X} %[N]s %[-N]s %% %n`. If any other formatter is used, the implementation reverts to String.format.
parameter: sink: optional recipient \(if null, a new builder will be created; the formatted string            is appended to the sink\)
parameter: l: locale to be used
parameter: format: format string
parameter: args: format arguments
return: the sink, never null

## Static Method: ff
- parameter: `sink`, type: `java.lang.Appendable`
- parameter: `format`, type: `java.lang.String`
- parameter: `args`, type: `java.lang.Object[]`
- return type: `java.lang.Appendable`

Description: A faster version of [String#format(String, Object...)](String#format(String, Object...)). 

 Implementation note: currently limited to formatters `%b %c %d %0{2,4,8}{x,X} %[N]s %[-N]s %% %n`. If any other formatter is used, the implementation reverts to String.format.
parameter: sink: optional recipient \(if null, a new builder will be created; the formatted string            is appended to the sink\)
parameter: format: format string
parameter: args: format arguments
return: the sink, never null

## Static Method: ff
- parameter: `l`, type: `java.util.Locale`
- parameter: `format`, type: `java.lang.String`
- parameter: `args`, type: `java.lang.Object[]`
- return type: `java.lang.String`

Description: A faster version of [String#format(String, Object...)](String#format(String, Object...)). 

 Implementation note: currently limited to formatters `%b %c %d %0{2,4,8}{x,X} %[N]s %[-N]s %% %n`. If any other formatter is used, the implementation reverts to String.format.
parameter: l: locale to be used
parameter: format: format string
parameter: args: format arguments
return: the formatted string

## Static Method: ff
- parameter: `format`, type: `java.lang.String`
- parameter: `args`, type: `java.lang.Object[]`
- return type: `java.lang.String`

Description: A faster version of [String#format(String, Object...)](String#format(String, Object...)). 

 Implementation note: currently limited to formatters `%b %c %d %0{2,4,8}{x,X} %[N]s %[-N]s %% %n`. If any other formatter is used, the implementation reverts to String.format.
parameter: format: format string
parameter: args: format arguments
return: the formatted string

## Static Method: findWordBoundaries
- parameter: `str`, type: `java.lang.String`
- parameter: `offset`, type: `int`
- return type: `int[]`

Description: Find a word in the string
parameter: str: a string
parameter: offset: offset in the string, for which the underlying word should be found
return: a tuple \(start, end\) in the string, specifying the word boundaries; if nothing is         found, the tuple returned will be \(provided\_offset, provided\_offset\)

## Static Method: findWordBoundaries
- parameter: `str`, type: `java.lang.String`
- parameter: `offset`, type: `int`
- parameter: `boundaryTester`, type: `java.util.function.Predicate<java.lang.Character>`
- return type: `int[]`

Description: Find a word in the string
parameter: str: a string
parameter: offset: offset in the string, for which the underlying word should be found
parameter: boundaryTester: optional custom boundary tester; leave null to use the default            boundary tester \(in that case, characters considered as boundaries are:            white\-space characters, punctuation characters except dash and underscore\)
return: a tuple \(start, end\) in the string, specifying the word boundaries; if nothing is         found, the tuple returned will be \(provided\_offset, provided\_offset\)

## Static Method: firstLine
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Retrieve the first line of a string.
parameter: s: input string
return: the portion of the string before the first CR or LF character

## Static Method: generate
- parameter: `c`, type: `char`
- parameter: `count`, type: `int`
- return type: `java.lang.String`

Description: Generate a repeated\-character [String](String). For [CharSequence](CharSequence) generation, use [#pad(char, int)](#pad(char, int)).
parameter: c: character to repeat
parameter: count: repeat count \(i.e. string length\)
return: the string

## Static Method: generate
- parameter: `s`, type: `java.lang.CharSequence`
- parameter: `count`, type: `int`
- return type: `java.lang.String`

Description: Generate a repeated string.
parameter: s: string to repeat
parameter: count: repeat count
return: the resulting result

## Static Method: getAsciiLength
- parameter: `data`, type: `byte[]`
- parameter: `maxlen`, type: `int`
- return type: `int`

Description: Retrieve the length of a potentially ASCII\-encoded string. The String characters allowed are contained CR, LF, TAB, and any character in the \[0x20, 0x7E\] range.
parameter: data: a byte array
parameter: maxlen: maximum length
return: the length of the string

## Static Method: getAsciiLength
- parameter: `data`, type: `byte[]`
- return type: `int`

Description: Same as [getAsciiLength\(data, data.length\)](#getAsciiLength(byte[], int)).
parameter: data: a byte array
return: the length of the string

## Static Method: getBOMSize
- parameter: `input`, type: `byte[]`
- return type: `int`

Description: Retrieve the size taken by the BOM or equivalent encoding mark. Detect UTF\-8, UTF\-16 and UTF\-32.
parameter: input: byte array. Be sure to have at least 4 bytes to analyze all.
return: the size taken by BOM or 0 if no BOM was detected

## Static Method: getComparator
- return type: `java.util.Comparator<java.lang.String>`

Description: Get a case\-sensitive string comparator that treats hexadecimal sequences as numbers, and orders them accordingly, instead as simple strings. 

 Refer to [NumberComparator](NumberComparator) and [AlphanumCharComparator](AlphanumCharComparator) for details.
return: the comparator

## Static Method: getComparator
- parameter: `caseSensitive`, type: `boolean`
- parameter: `scanHexadecimal`, type: `boolean`
- return type: `java.util.Comparator<java.lang.String>`

Description: Get a string comparator that can treat hexadecimal sequences as numbers \(and order them accordingly\) instead as simple strings. 

 Refer to [NumberComparator](NumberComparator) and [AlphanumCharComparator](AlphanumCharComparator) for details.
parameter: caseSensitive: true to sort upper\-case and lower\-case letters separately
parameter: scanHexadecimal: true to recognize hexadecimal number chunks
return: the comparator

## Static Method: getFastFormatFailureCount
- return type: `int`


## Static Method: getFastFormatInvocationCount
- return type: `int`


## Static Method: getInitialBlankSize
- parameter: `in`, type: `java.io.InputStream`
- parameter: `includeBOM`, type: `boolean`
- parameter: `extraWSPChars`, type: `char[]`
- return type: `int`

Description: Retrieve the initial blank bytes at the beginning of a stream. This method is a destructive probe and the caller must not continue reading from the same stream after it returns.
parameter: in: input stream \(when this method returns, some bytes have been read from the            stream; callers should no longer use the stream\)
parameter: includeBOM: true will consider BOM at start of the stream as an initial blank bytes
parameter: extraWSPChars: optional set of characters to be treated as whitespaces, aside from            Space, Tab, CR, LF
return: the number of bytes considered blank and that should be skipped
throws: if the stream cannot be read

## Static Method: hasBlank
- parameter: `s`, type: `java.lang.CharSequence`
- return type: `boolean`

Description: Determine if a string contains one or more WSP characters.
parameter: s: character sequence to test
return: true if the sequence contains at least one whitespace character

## Static Method: hasLength
- parameter: `s`, type: `java.lang.CharSequence`
- return type: `boolean`

Description: Determine if a string is non\-null and non\-empty.
parameter: s: character sequence to test
return: true iff the sequence contains at least one character

## Static Method: hasRtl
- parameter: `s`, type: `java.lang.CharSequence`
- return type: `boolean`

Description: Determine if a string contains right\-to\-left \(RTL\) characters, eg Arabic or Hebrew characters.
parameter: s: character sequence to scan
return: true if the sequence contains an RTL character

## Static Method: indentBlock
- parameter: `blk`, type: `java.lang.String`
- parameter: `indent`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Indent a buffer.
parameter: blk: input block
parameter: indent: indentation string prepended to every line
return: the indented block

## Static Method: indentBlock
- parameter: `blk`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Indent a buffer using a 4\-space indentation.
parameter: blk: input block
return: the indented block

## Static Method: indexOf
- parameter: `text`, type: `java.lang.CharSequence`
- parameter: `c`, type: `char`
- return type: `int`

Description: Implementation of `indexOf` for CharSequence. Same behavior as [String#indexOf(int)](String#indexOf(int)).
parameter: text: string
parameter: c: char
return: the index position, or \-1 if not found

## Static Method: indexOf2
- parameter: `text`, type: `java.lang.CharSequence`
- parameter: `c0`, type: `char`
- parameter: `c1`, type: `char`
- return type: `int`

Description: Find the first one of two characters and return its position. 

 This is a 2\-element implementation of [String#indexOf(int)](String#indexOf(int)).
parameter: text: string
parameter: c0: first char
parameter: c1: second char
return: the position of the first occurrence of c0 or c1 \(whichever came first\), \-1 if not         found

## Static Method: indexOf2
- parameter: `text`, type: `java.lang.CharSequence`
- parameter: `from`, type: `int`
- parameter: `c0`, type: `char`
- parameter: `c1`, type: `char`
- return type: `int`

Description: Find the first one of two characters and return its position.
parameter: text: string
parameter: from: start index
parameter: c0: first char
parameter: c1: second char
return: the position of the first occurrence of c0 or c1 \(whichever came first\), \-1 if not         found

## Static Method: indexOfAny
- parameter: `text`, type: `java.lang.CharSequence`
- parameter: `cset`, type: `java.util.Set<java.lang.Character>`
- return type: `int`

Description: Find the first one of any of the provided characters and return its position. 

 This is a N\-element implementation of [String#indexOf(int)](String#indexOf(int)).
parameter: text: string
parameter: cset: a set of characters
return: the position of the first occurrence of any character in the set, or \-1 if not found

## Static Method: indexOfNotInGroup
- parameter: `text`, type: `java.lang.CharSequence`
- parameter: `c`, type: `char`
- parameter: `fromIndex`, type: `int`
- parameter: `ingoreInGroups`, type: `char[][]`
- return type: `int`

Description: Find the index a of character, ignoring some groups. For example: 
 
- ignore some text in parenthesis: `indexOfNotInGroup("it is (almost) done", 'o', 0, ['(', ')'])` will return 16
-  
- ignore generics: `indexOfNotInGroup("std::myclass<a,b>::mymethod(type a, type b)", ',', 0, ['<', '>'])` will return 34
-
parameter: text: string
parameter: c: character to find
parameter: fromIndex: start index, use 0 by default
parameter: ingoreInGroups: list of character groups to be ignored, for example `{'(', ')'}`            or `{'<', '>'}`. Each character group must contain at least 2 elements \(one            for the open element, one for the close element\)
return: positive index if found, \-1 when not found, \-2 in case of malformed

## Static Method: isAsciiWhitespace
- parameter: `b`, type: `int`
- parameter: `extraWhitespaceCharacters`, type: `char[]`
- return type: `boolean`

Description: Determine if a character is a white\-space, per the Ascii standard. It only processes regular space, tab, CR and LF characters.
parameter: b: the int to test
parameter: extraWhitespaceCharacters: additional ascii characters considered as whitespace
return: true if the value is an ASCII whitespace character

## Static Method: isBlank
- parameter: `s`, type: `java.lang.CharSequence`
- return type: `boolean`

Description: Determine if a character sequence is null, empty, or contains WSP chars exclusively.
parameter: s: the character sequence
return: true if the sequence is null or blank

## Static Method: isConsistentHexNumberString
- parameter: `text`, type: `java.lang.String`
- return type: `boolean`

Description: Check that every character of a non\-empty input string is an hexadecimal digit. Allow upper case as well as lower case characters \(only lower or only upper\).
parameter: text: the input string
return: true if the string is a valid hexadecimal number

## Static Method: isContainedIn
- parameter: `s`, type: `java.lang.String`
- parameter: `elts`, type: `java.lang.String[]`
- return type: `boolean`

Description: Determine if a string is contained in an var\-arg list of provided strings.
parameter: s: string to be searched
parameter: elts: the list of elements
return: true iff the input string was not null and found in the list of elements

## Static Method: isNumber
- parameter: `text`, type: `java.lang.String`
- return type: `boolean`

Description: Check that every character of the text parameter is a digit.
parameter: text: string to test
return: true if text is a valid decimal number

## Static Method: isPrintableCharsetHeader
- parameter: `headerBytes`, type: `byte[]`
- parameter: `charset`, type: `java.nio.charset.Charset`
- return type: `boolean`

Description: Validate if some starting bytes may be encoded with a particular charset.
parameter: headerBytes: starting bytes. May be cropped without incidence \(will be more accurate            with more bytes, though\).
parameter: charset: charset to detect. Use [#isPrintableUTF8Header(byte[])](#isPrintableUTF8Header(byte[])) for UTF\-8.
return: true if bytes appears to represent the provided charset.

## Static Method: isPrintableUTF8Header
- parameter: `headerBytes`, type: `byte[]`
- return type: `boolean`

Description: Validate if some starting bytes may be considered as an UTF\-8 printable character header.
parameter: headerBytes: starting bytes. May be cropped without incidence \(will be more accurate            with more bytes, though\).
return: true if bytes appears to represent UTF\-8.

## Static Method: isWellFormedUTF8
- parameter: `bytes`, type: `byte[]`
- return type: `boolean`

Description: Determine if a byte array is a well\-formed UTF\-8 byte sequence.
parameter: bytes: bytes to validate
return: true if the bytes round\-trip through UTF\-8 decoding and encoding

## Static Method: isWellFormedUTF8
- parameter: `bytes`, type: `byte[]`
- parameter: `off`, type: `int`
- parameter: `len`, type: `int`
- return type: `boolean`

Description: Determine if a byte range is a well\-formed UTF\-8 byte sequence.
parameter: bytes: bytes to validate
parameter: off: start offset
parameter: len: number of bytes to validate
return: true if the bytes round\-trip through UTF\-8 decoding and encoding

## Static Method: isWhitespace
- parameter: `c`, type: `char`
- return type: `boolean`

Description: Determine if a character is a white\-space, per the Unicode standard. This method differs from [Character#isWhitespace(char)](Character#isWhitespace(char)) \(Java language definition of a WSP\).
parameter: c: character to test
return: true if the character is one of the recognized Unicode whitespace characters

## Static Method: join
- parameter: `separator`, type: `java.lang.String`
- parameter: `iterator`, type: `java.lang.Iterable<?>`
- return type: `java.lang.String`

Description: Join the string representations of a sequence of objects using the provided separator. Null objects will be formatted as "null".
parameter: separator: a non\-null separator
parameter: iterator: an iterator
return: the resulting string

## Static Method: join
- parameter: `separator`, type: `java.lang.String`
- parameter: `iterator`, type: `java.lang.Iterable<T>`
- parameter: `f`, type: `java.util.function.Function<T,java.lang.CharSequence>`
- return type: `java.lang.String`

Description: Join a series of items. Format items using the function. For example, to display a list of long as hexadecimal separated by comma: `Strings.join(", ", Arrays.asList(0x10L, 0x20L), l -> Long.toHexString(l))`
parameter: T: Any Object
parameter: separator: a non\-null separator
parameter: iterator: items to join
parameter: f: toString\(\) equivalent method to be applied to objects from list.
return: the resulting string

## Static Method: join
- parameter: `separator`, type: `java.lang.String`
- parameter: `elts`, type: `java.lang.String[]`
- parameter: `begin`, type: `int`
- parameter: `end`, type: `int`
- return type: `java.lang.String`

Description: Join a series of non\-null strings.
parameter: separator: a non\-null separator
parameter: elts: string array to join
parameter: begin: inclusive start index
parameter: end: exclusive end index
return: the joined string

## Static Method: joinList
- parameter: `objects`, type: `java.lang.Iterable<?>`
- return type: `java.lang.String`

Description: Join the elements of a list using "," as a separator and surround the resulting string with square brackets. Careful, this method does not abide to the common semantic of `join`.
parameter: objects: a list of objects
return: the resulting string

## Static Method: joinv
- parameter: `separator`, type: `java.lang.String`
- parameter: `objects`, type: `java.lang.Object[]`
- return type: `java.lang.String`

Description: Join the string representations of a sequence of objects using the provided separator. Null objects will be formatted as "null".
parameter: separator: a non\-null separator
parameter: objects: an array of objects
return: the resulting string

## Static Method: joinv
- parameter: `separator`, type: `java.lang.String`
- parameter: `defaultValue`, type: `java.lang.String`
- parameter: `objects`, type: `java.lang.Object[]`
- return type: `java.lang.String`

Description: Join the string representations of a sequence of objects using the provided separator.
parameter: separator: a non\-null separator
parameter: defaultValue: String representation for null Objects
parameter: objects: an array of objects
return: the resulting string

## Static Method: lastIndexOf2
- parameter: `text`, type: `java.lang.CharSequence`
- parameter: `c0`, type: `char`
- parameter: `c1`, type: `char`
- return type: `int`

Description: Find the last one of two characters and return its position. 

 This is a 2\-element implementation of [String#lastIndexOf(int)](String#lastIndexOf(int)).
parameter: text: string
parameter: c0: first char
parameter: c1: second char
return: the position of the last occurrence of c0 or c1 \(whichever came first\), \-1 if not         found

## Static Method: lastIndexOf2
- parameter: `text`, type: `java.lang.CharSequence`
- parameter: `from`, type: `int`
- parameter: `c0`, type: `char`
- parameter: `c1`, type: `char`
- return type: `int`

Description: Find the last one of two characters and return its position.
parameter: text: string
parameter: from: start index
parameter: c0: first char
parameter: c1: second char
return: the position of the last occurrence of c0 or c1 \(whichever came first\), \-1 if not         found

## Static Method: lastIndexOfAny
- parameter: `text`, type: `java.lang.CharSequence`
- parameter: `cset`, type: `java.util.Set<java.lang.Character>`
- return type: `int`

Description: Find the last one of any of the provided characters and return its position. 

 This is a N\-element implementation of [String#lastIndexOf(int)](String#lastIndexOf(int)).
parameter: text: string
parameter: cset: a set of characters
return: the position of the last occurrence of any character in the set, or \-1 if not found

## Static Method: like
- parameter: `str`, type: `java.lang.String`
- parameter: `pat`, type: `java.lang.String`
- return type: `boolean`

Description: Check whether an input string matches a provided [regex pattern](Pattern). This method is case\-sensitive.
parameter: str: a string
parameter: pat: a regular expression
return: true if the pattern matches the entire string

## Static Method: likei
- parameter: `str`, type: `java.lang.String`
- parameter: `pat`, type: `java.lang.String`
- return type: `boolean`

Description: Check whether an input string matches a provided [regex pattern](Pattern). This method is case\-insensitive.
parameter: str: a string
parameter: pat: a regular expression
return: true if the pattern matches the entire string, ignoring case

## Static Method: ltrim
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Left trim all chars less than or equal to ' '. Note that this method differs from [String#trim()](String#trim()) which, for instance, does not consider CR or LF to be WSP.
parameter: s: a string
return: the left\-trimmed string

## Static Method: ltrim
- parameter: `s`, type: `java.lang.String`
- parameter: `c`, type: `char`
- return type: `java.lang.String`

Description: Left trim on a given character.
parameter: s: a string
parameter: c: character to remove
return: the left\-trimmed string

## Static Method: makeNewLine
- parameter: `sb`, type: `java.lang.StringBuilder`

Description: Append a new\-line character to the provided buffer unless the buffer is empty or the last character in the buffer is a new\-line.
parameter: sb: a string builder

## Static Method: normalizeNewLines
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Replace all newline sequences by the standard \\n LF character.
parameter: s: a string
return: the normalized string

## Static Method: pad
- parameter: `c`, type: `char`
- parameter: `count`, type: `int`
- return type: `java.lang.CharSequence`

Description: Repeat character c, iter times and build a [CharSequence](CharSequence) from it. For example pad\('0', 4\) will return "0000".
parameter: c: inner character
parameter: count: times to repeat character.
return: [CharSequence](CharSequence)

## Static Method: parseCommandline
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String[]`

Description: Parse a string as a command line. Source: ant.jar.
parameter: s: the command line to process.
return: the command line broken into strings

## Static Method: parseUrlParameter
- parameter: `s`, type: `java.lang.String`
- parameter: `entry`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Same as [#parseUrlParameters](#parseUrlParameters) with a single entry.
parameter: s: the URL\-like string to be parsed, containing a single key\-value pair, eg            `hometype=house`
parameter: entry: parameter name to retrieve
return: the parameter \(without decoding applied\), null on error

## Static Method: parseUrlParameters
- parameter: `s`, type: `java.lang.String`
- parameter: `entries`, type: `java.lang.String[]`
- return type: `java.lang.String[]`

Description: Extract the parameters of a URL\-like encoded string. No decoding is taking place. Example: 

```

 - s: "type=home&subtype=house&[another_key]=[another_value]"
 - entries: "type", "subtype"
 - returns: ["home", "house"]
 
```
parameter: s: the string to be parsed
parameter: entries: the entries, whose count must match the number of key\-value pairs
return: the array of parameter values, as they were \(i.e. without any decoding applied\); an         element is null if it could not be parsed

## Static Method: randomUniqueId
- return type: `java.lang.String`

Description: Generate a 32\-character long random unique identifier. The UID returned consists of the digits 0 to 9 and letters a to f \(lower\-case\).
return: a random lowercase hexadecimal identifier

## Static Method: readBOM
- parameter: `input`, type: `byte[]`
- return type: `java.lang.String`

Description: Retrieve the charset from start bytes. Detect UTF\-8, UTF\-16LE/BE and UTF\-32LE\-BE.
parameter: input: first bytes of a string
return: the detected charset or null if no BOM was detected.

## Static Method: replaceLast
- parameter: `str`, type: `java.lang.String`
- parameter: `target`, type: `java.lang.String`
- parameter: `replacement`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Replace the last occurrence of target in str by the replacement
parameter: str: the string to search in
parameter: target: the string to search for
parameter: replacement: the replacement part
return: the new string with replacement instead of last target occurrence or original string         if target was not found

## Static Method: replaceNewLines
- parameter: `s`, type: `java.lang.String`
- parameter: `repl`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Replace newline sequences. This method accepts null strings as input.
parameter: s: a string or null; in the latter case, null will be returned
parameter: repl: the non\-null substitution string, which must not contain new\-line characters
return: the string with all newline sequences replaced, or null if `s` is null

## Static Method: replaceWhitespaces
- parameter: `str`, type: `java.lang.String`
- parameter: `repl`, type: `char`
- return type: `java.lang.String`

Description: Efficiently replace all Unicode white\-spaces by the provided char.
parameter: str: input string
parameter: repl: replacement character
return: the string with all recognized whitespace characters replaced

## Static Method: resetFastFormatCounts


## Static Method: rtrim
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Right trim all chars less than or equal to ' '. Note that this method differs from [String#trim()](String#trim()) which, for instance, does not consider CR or LF to be WSP.
parameter: s: a string
return: the right\-trimmed string

## Static Method: rtrim
- parameter: `s`, type: `java.lang.String`
- parameter: `c`, type: `char`
- return type: `java.lang.String`

Description: Right trim on a given character.
parameter: s: a string
parameter: c: character to remove
return: the right\-trimmed string

## Static Method: safe
- parameter: `s`, type: `java.lang.Object`
- return type: `java.lang.String`

Description: Get the string representation of the parameter object, or the empty string if the object is null.
parameter: s: an object, possibly null
return: the object [Strings#toString](Strings#toString) representation, or the empty string

## Static Method: safe
- parameter: `s`, type: `java.lang.Object`
- parameter: `def`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Get the string representation of the parameter object, or the provided string if the object is null.
parameter: s: an object, possibly null
parameter: def: a non\-null string
return: a non\-null string, possibly empty

## Static Method: safe2
- parameter: `s`, type: `java.lang.Object`
- parameter: `def`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Get the string representation of the parameter object, or the provided non\-empty string if the object is null or its string representation is the empty string.
parameter: s: an object, possibly null
parameter: def: a non\-null, non\-empty string
return: a string guaranteed to be non\-empty

## Static Method: search
- parameter: `data`, type: `java.lang.CharSequence`
- parameter: `index`, type: `int`
- parameter: `pattern`, type: `java.lang.String`
- parameter: `regex`, type: `boolean`
- parameter: `caseSensitive`, type: `boolean`
- parameter: `reverseSearch`, type: `boolean`
- return type: `int`

Description: Search for a sub\-string. 

 Note: on JDK 11\+, this implementation for `regex=false, caseSensitive=false, reverseSearch=false` may be slower than doing `data.toLowerCase().indexOf(pattern.toLowerCase())`.
parameter: data: buffer to be searched \(aka, the haystack\)
parameter: index: in the case of a regular \(forward\) search, the search takes is \[index,EOS\); in            the case of a reverse \(backward\) search, the search range is \[0,index\)
parameter: pattern: text that is being searched \(aka, the needle\)
parameter: regex: if true, the pattern will be treated as a regular expression; if the regex is            invalid, it will be treated as a regular string and no error will be reported
parameter: caseSensitive: search is case\-sensitive
parameter: reverseSearch: search is done in reverse
return: index where the substring was found, or \-1 if nothing was found

## Static Method: spaces
- parameter: `count`, type: `int`
- return type: `java.lang.String`

Description: Generate a repeated string of spaces.
parameter: count: number of spaces to generate
return: a string containing `count` spaces, or the empty string if count is not positive

## Static Method: splitCsv
- parameter: `buf`, type: `java.lang.String`
- return type: `java.lang.String[]`

Description: Split a text into an array of lines using comma as a separator. Empty lines are returned.
parameter: buf: input string
return: an array of tokens; the array is empty if the input string is null or empty

## Static Method: splitLines
- parameter: `s`, type: `java.lang.String`
- parameter: `doNotReturnFinalEmptyLine`, type: `boolean`
- return type: `java.lang.String[]`

Description: Split a text into an array of Lines. Empty lines are returned. The final new\-line character\(s\) are trimmed off. Works for all new lines characters \(\\r, \\n\) or sequences of characters \(\\r\\n\)
parameter: s: mandatory input string
parameter: doNotReturnFinalEmptyLine: true to discard a final empty line
return: the lines

## Static Method: splitLines
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String[]`

Description: Split a text into an array of Lines. Empty lines are returned. The final new\-line character\(s\) are trimmed off. Works for all new lines characters \(\\r, \\n\) or sequences of characters \(\\r\\n\)
parameter: s: mandatory input string
return: the lines

## Static Method: splitall
- parameter: `s`, type: `java.lang.String`
- parameter: `delim`, type: `java.lang.String`
- return type: `java.lang.String[]`

Description: Split a string and preserve trailing empty tokens.
parameter: s: input string
parameter: delim: regular\-expression delimiter
return: the split tokens

## Static Method: starMatches
- parameter: `str`, type: `java.lang.String`
- parameter: `pat`, type: `java.lang.String`
- return type: `boolean`

Description: Check whether an input string matches a provided pattern using a [StarMatcher](StarMatcher).
parameter: str: a string
parameter: pat: a wildcard pattern
return: true if the wildcard pattern matches the string

## Static Method: startsWith
- parameter: `s`, type: `java.lang.String`
- parameter: `elts`, type: `java.lang.String[]`
- return type: `boolean`

Description: A many\-element variant of [String.startsWith](String#startsWith(String)).
parameter: s: the string
parameter: elts: a list of string elements
return: true if the string starts with one of the provided elements

## Static Method: substring
- parameter: `s`, type: `java.lang.String`
- parameter: `begin`, type: `int`
- parameter: `end`, type: `int`
- return type: `java.lang.String`

Description: Flexible version of [String#substring(int, int)](String#substring(int, int)). Allow Python\-like negative indexes for convenience.
parameter: s: a string
parameter: begin: index in the \[\-s\_length, \+s\_length\] range
parameter: end: index in the \[\-s\_length, \+s\_length\] range
return: the substring

## Static Method: toString
- parameter: `o`, type: `java.lang.Object`
- return type: `java.lang.String`

Description: A safe version of [String.toString](String#toString()).
parameter: o: an object, could be null
return: the String representation of the provided object, or "null"

## Static Method: toString
- parameter: `o`, type: `java.lang.Object`
- parameter: `defaultValue`, type: `java.lang.String`
- return type: `java.lang.String`

Description: A safe version of [String.toString](String#toString()).
parameter: o: an object, could be null
parameter: defaultValue: default String representation if o is null
return: the String representation of the provided object, or the default value

## Static Method: trim
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Trim \(left and right\) all chars less than or equal to ' '. Note that this method differs from [String#trim()](String#trim()) which, for instance, does not consider CR or LF to be WSP.
parameter: s: a string
return: the trimmed string

## Static Method: trim
- parameter: `s`, type: `java.lang.String`
- parameter: `c`, type: `char`
- return type: `java.lang.String`

Description: Trim \(left and right\) all chars to provided character.
parameter: s: a string
parameter: c: the character to be removed
return: the trimmed string

## Static Method: trimWhitespaces
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Trim \(left and right\) all characters considered to be white\-space by the Unicode standard.
parameter: s: the input string
return: the trimmed string

## Static Method: truncate
- parameter: `s`, type: `java.lang.String`
- parameter: `maxLength`, type: `int`
- return type: `java.lang.String`

Description: Truncate a string.
parameter: s: a string
parameter: maxLength: positive length
return: the truncated string, which will contain at most \`maxLength\` characters

## Static Method: truncateWithSuffix
- parameter: `s`, type: `java.lang.String`
- parameter: `maxLength`, type: `int`
- parameter: `suffix`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Truncate a string and append an optional suffix to it if it was actually truncated.
parameter: s: a string
parameter: maxLength: positive length, which must be greater than or equal to the suffix, if one            was provided
parameter: suffix: optional suffix appended to a string that is actually truncated
return: the original string, or a truncated string ending with the suffix

## Static Method: urldecodeUTF8
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Decode a [URL\-encoded](#urlencodeUTF8(String)) string.
parameter: s: the encoded string
return: the decoded string

## Static Method: urlencodeUTF8
- parameter: `s`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Urlencode a string. The resulting string will have the following characteristics: 
 
- a\-z, A\-Z, 0\-9 remain the same
-  
- ., \-, \*, \_ remain the same
-  
- space is converted to \+
-  
- all other characters are UTF8 encoded using the "%xx" scheme
-
parameter: s: the string to be encoded
return: the encoded string

