# 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` 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` 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` - 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` 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` 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` - 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::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` - parameter: `f`, type: `java.util.function.Function` - 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` - 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