Final Class lispa\amos\core\utilities\StringUtils

{@see StringUtils} instances can NOT be constructed in standard programming.

Instead, the class should be used as:

StringUtils::trim(' foo ');

Capitalizes a string changing the first letter to upper case.

No other letters are changed. For a word based algorithm, see {@see capitalize}. A null input string returns null.

StringUtils::capitalize(null);  // null
StringUtils::capitalize('');    // ''
StringUtils::capitalize('cat'); // 'Cat'
StringUtils::capitalize('cAt'); // 'CAt'

See also [[StringUtils::uncapitalize,]] WordUtils::capitalize.

Returns the character at the specified index.

An index ranges from 0 to StringUtils::length() - 1. The first character of the sequence is at index 0, the next at index 1, and so on, as for array indexing.

Removes one newline from end of a string if it's there, otherwise leave it alone.

A newline is "\n", "\r", or "\r\n".

StringUtils::chomp(null);          // null
StringUtils::chomp('');            // ''
StringUtils::chomp("abc \r");      // 'abc '
StringUtils::chomp("abc\n");       // 'abc'
StringUtils::chomp("abc\r\n");     // 'abc'
StringUtils::chomp("abc\r\n\r\n"); // "abc\r\n"
StringUtils::chomp("abc\n\r");     // "abc\n"
StringUtils::chomp("abc\n\rabc");  // "abc\n\rabc"
StringUtils::chomp("\r");          // ''
StringUtils::chomp("\n");          // ''
StringUtils::chomp("\r\n");        // ''

Remove the specified last character from a string.

If the string ends in \r\n, then remove both of them.

StringUtils::chop(null);       // null
StringUtils::chop('');         // ''
StringUtils::chop("abc \r");   // 'abc '
StringUtils::chop("abc\n");    // 'abc'
StringUtils::chop("abc\r\n");  // 'abc'
StringUtils::chop('abc');      // 'ab'
StringUtils::chop("abc\nabc"); // "abc\nab"
StringUtils::chop('a');        // ''
StringUtils::chop("\r");       // ''
StringUtils::chop("\n");       // ''
StringUtils::chop("\r\n");     // ''

Compares two strings lexicographically.

The comparison is based on the Unicode value of each character in the strings. The character sequence represented by the first string is compared lexicographically to the character sequence represented by the second string. The result is a negative integer if the first string lexicographically precedes the second string. The result is a positive integer if the first string lexicographically follows the second string.

This method returns an integer whose sign is that of calling {@see compare} with normalized versions of the strings.

Compares two strings lexicographically, ignoring case differences.

This method returns an integer whose sign is that of calling {@see compare} with normalized versions of the strings.

Checks if a string ends with a specified suffix.

nulls are handled without exceptions. Two null references are considered to be equal. The comparison is case sensitive.

StringUtils::endsWith(null, null);      // true
StringUtils::endsWith(null, 'def');     // false
StringUtils::endsWith('abcdef', null);  // false
StringUtils::endsWith('abcdef', 'def'); // true
StringUtils::endsWith('ABCDEF', 'def'); // false
StringUtils::endsWith('ABCDEF', 'cde'); // false

Compares two strings, returning true if they are equal.

nulls are handled without exceptions. Two null references are considered to be equal. The comparison is case sensitive.

StringUtils::equals(null, null);   // true
StringUtils::equals(null, 'abc');  // false
StringUtils::equals('abc', null);  // false
StringUtils::equals('abc', 'abc'); // true
StringUtils::equals('abc', 'ABC'); // false

Compares two strings, returning true if they are equal ignoring the case.

nulls are handled without exceptions. Two null references are considered to be equal. The comparison is case insensitive.

StringUtils::equalsIgnoreCase(null, null);   // true
StringUtils::equalsIgnoreCase(null, 'abc');  // false
StringUtils::equalsIgnoreCase('abc', null);  // false
StringUtils::equalsIgnoreCase('abc', 'abc'); // true
StringUtils::equalsIgnoreCase('abc', 'ABC'); // true

Finds the first index within a string from a start position, handling null.

A null or empty ('') string will return -1. A negative start position is treated as zero. A start position greater than the string length returns -1.

StringUtils::indexOf(null, *, *);          // -1
StringUtils::indexOf(*, null, *);          // -1
StringUtils::indexOf('', '', 0);           // 0
StringUtils::indexOf('aabaabaa', 'a', 0);  // 0
StringUtils::indexOf('aabaabaa', 'b', 0);  // 2
StringUtils::indexOf('aabaabaa', 'ab', 0); // 1
StringUtils::indexOf('aabaabaa', 'b', 3);  // 5
StringUtils::indexOf('aabaabaa', 'b', 9);  // -1
StringUtils::indexOf('aabaabaa', 'b', -1); // 2
StringUtils::indexOf('aabaabaa', '', 2);   // 2
StringUtils::indexOf('abc', '', 9);        // 3

Checks if a string is whitespace, empty ('') or null.

StringUtils::isBlank(null); // true

StringUtils::isBlank('');        // true
StringUtils::isBlank(' ');       // true
StringUtils::isBlank('bob');     // false
StringUtils::isBlank('  bob  '); // false

Checks if a string is empty ('') or null.

StringUtils::isEmpty(null); // true

StringUtils::isEmpty('');        // true
StringUtils::isEmpty(' ');       // false
StringUtils::isEmpty('bob');     // false
StringUtils::isEmpty('  bob  '); // false

Checks if a string is not empty (''), not null and not whitespace only.

StringUtils::isNotBlank(null); // false

StringUtils::isNotBlank('');        // false
StringUtils::isNotBlank(' ');       // false
StringUtils::isNotBlank('bob');     // true
StringUtils::isNotBlank('  bob  '); // true

Checks if a string is not empty ('') and not null.

StringUtils::isNotEmpty(null); // false

StringUtils::isNotEmpty('');        // false
StringUtils::isNotEmpty(' ');       // true
StringUtils::isNotEmpty('bob');     // true
StringUtils::isNotEmpty('  bob  '); // true

Finds the first index within a string, handling null.

A null string will return -1. A negative start position returns -1. An empty ('') search string always matches unless the start position is negative. A start position greater than the string length searches the whole string.

StringUtils::lastIndexOf(null, *, *);          // -1
StringUtils::lastIndexOf(*, null, *);          // -1
StringUtils::lastIndexOf('aabaabaa', 'a', 8);  // 7
StringUtils::lastIndexOf('aabaabaa', 'b', 8);  // 5
StringUtils::lastIndexOf('aabaabaa', 'ab', 8); // 4
StringUtils::lastIndexOf('aabaabaa', 'b', 9);  // 5
StringUtils::lastIndexOf('aabaabaa', 'b', -1); // -1
StringUtils::lastIndexOf('aabaabaa', 'a', 0);  // 0
StringUtils::lastIndexOf('aabaabaa', 'b', 0);  // -1

Returns the length of a string or 0 if the string is null.

Converts a string to lower case.

A null input string returns null.

StringUtils::lowerCase(null)  = null
StringUtils::lowerCase('')    = ''
StringUtils::lowerCase('aBc') = 'abc'

Removes a substring only if it is at the end of a source string, otherwise returns the source string.

A null source string will return null. An empty ('') source string will return the empty string. A null search string will return the source string.

StringUtils::removeEnd(null, *);                    // null
StringUtils::removeEnd('', *);                      // ''
StringUtils::removeEnd(*, null);                    // *
StringUtils::removeEnd('www.domain.com', '.com.');  // 'www.domain.com'
StringUtils::removeEnd('www.domain.com', '.com');   // 'www.domain'
StringUtils::removeEnd('www.domain.com', 'domain'); // 'www.domain.com'
StringUtils::removeEnd('abc', '');                  // 'abc'

Removes a substring only if it is at the beginning of a source string, otherwise returns the source string.

A null source string will return null. An empty ('') source string will return the empty string. A null search string will return the source string.

StringUtils::removeStart(null, *);                    // null
StringUtils::removeStart('', *);                      // ''
StringUtils::removeStart(*, null);                    // *
StringUtils::removeStart('www.domain.com', 'www.');   // 'domain.com'
StringUtils::removeStart('domain.com', 'www.');       // 'domain.com'
StringUtils::removeStart('www.domain.com', 'domain'); // 'www.domain.com'
StringUtils::removeStart('abc', '');                  // 'abc'

Repeats a string the specified number of times to form a new string, with a specified string injected each time.

StringUtils::repeat(null, 2, null); // null

StringUtils::repeat(null, 2, 'x');  // null
StringUtils::repeat('', 0, null);   // ''
StringUtils::repeat('', 2, '');     // ''
StringUtils::repeat('', 3, 'x');    // 'xxx'
StringUtils::repeat('?', 3, ', ');  // '?, ?, ?'

Replaces a string with another string inside a larger string, for the first maximum number of values to replace of the search string.

StringUtils::replace(null, , , *) // null

StringUtils::replace('', *, *, *)           // ''
StringUtils::replace('any', null, *, *)     // 'any'
StringUtils::replace('any', *, null, *)     // 'any'
StringUtils::replace('any', '', *, *)       // 'any'
StringUtils::replace('any', *, *, 0)        // 'any'
StringUtils::replace('abaa', 'a', null, -1) // 'abaa'
StringUtils::replace('abaa', 'a', '', -1)   // 'b'
StringUtils::replace('abaa', 'a', 'z', 0)   // 'abaa'
StringUtils::replace('abaa', 'a', 'z', 1)   // 'zbaa'
StringUtils::replace('abaa', 'a', 'z', 2)   // 'zbza'
StringUtils::replace('abaa', 'a', 'z', -1)  // 'zbzz'

Replaces a string with another string inside a larger string, for the first maximum number of values to replace of the search string.

StringUtils::replace(null, , , *) // null

StringUtils::replace('', *, *, *)           // ''
StringUtils::replace('any', null, *, *)     // 'any'
StringUtils::replace('any', *, null, *)     // 'any'
StringUtils::replace('any', '', *, *)       // 'any'
StringUtils::replace('any', *, *, 0)        // 'any'
StringUtils::replace('abaa', 'a', null, -1) // 'abaa'
StringUtils::replace('abaa', 'a', '', -1)   // 'b'
StringUtils::replace('abaa', 'a', 'z', 0)   // 'abaa'
StringUtils::replace('abaa', 'a', 'z', 1)   // 'zbaa'
StringUtils::replace('abaa', 'a', 'z', 2)   // 'zbza'
StringUtils::replace('abaa', 'a', 'z', -1)  // 'zbzz'

Parse string and return limited one

Splits the provided text into an array with a maximum length, separators specified.

The separator is not included in the returned string array. Adjacent separators are treated as one separator. A null input string returns null. A null $chars splits on whitespace. If more than $max delimited substrings are found, the returned string includes all characters after the first $max - 1 returned strings (including separator characters).

StringUtils::split(null, null, null);      // null
StringUtils::split('', null, null);        // []
StringUtils::split('ab cd ef', null, 0);   // ['ab', 'cd', 'ef']
StringUtils::split('ab   cd ef', null, 0); // ['ab', 'cd', 'ef']
StringUtils::split('ab:cd:ef', ':', 0);    // ['ab', 'cd', 'ef']
StringUtils::split('ab:cd:ef', ':', 2);    // ['ab', 'cd:ef']

Checks if a string starts with a specified prefix.

nulls are handled without exceptions. Two null references are considered to be equal. The comparison is case sensitive.

StringUtils::startsWith(null, null);      // true
StringUtils::startsWith(null, 'abc');     // false
StringUtils::startsWith('abcdef', null);  // false
StringUtils::startsWith('abcdef', 'abc'); // true
StringUtils::startsWith('ABCDEF', 'abc'); // false

Strips any of a set of characters from the start and end of a string.

This is similar to {@see trim} but allows the characters to be stripped to be controlled.

A null input string returns null. An empty string ('') input returns the empty string.

If the string for the characters to remove is null, whitespace is stripped.

StringUtils::strip(null, *);          // null
StringUtils::strip('', *);            // ''
StringUtils::strip('abc', null);      // 'abc'
StringUtils::strip('  abc', null);    // 'abc'
StringUtils::strip('abc  ', null);    // 'abc'
StringUtils::strip(' abc ', null);    // 'abc'
StringUtils::strip('  abcyx', 'xyz'); // '  abc'

Strips any of a set of characters from the end of a string.

A null input string returns null. An empty string ('') input returns the empty string.

If the string for the characters to remove is null, whitespace is stripped.

StringUtils::stripEnd(null, *)          = null
StringUtils::stripEnd('', *)            = ''
StringUtils::stripEnd('abc', '')        = 'abc'
StringUtils::stripEnd('abc', null)      = 'abc'
StringUtils::stripEnd('  abc', null)    = '  abc'
StringUtils::stripEnd('abc  ', null)    = 'abc'
StringUtils::stripEnd(' abc ', null)    = ' abc'
StringUtils::stripEnd('  abcyx', 'xyz') = '  abc'

Strips any of a set of characters from the start of a string.

A null input string returns null. An empty string ('') input returns the empty string.

If the string for the characters to remove is null, whitespace is stripped.

StringUtils::stripStart(null, *);          // null
StringUtils::stripStart('', *);            // ''
StringUtils::stripStart('abc', '');        // 'abc'
StringUtils::stripStart('abc', null);      // 'abc'
StringUtils::stripStart('  abc', null);    // 'abc'
StringUtils::stripStart('abc  ', null);    // 'abc  '
StringUtils::stripStart(' abc ', null);    // 'abc '
StringUtils::stripStart('yxabc  ', 'xyz'); // 'abc  '

Strips whitespace from the start and end of a string returning an empty string if null input.

This is similar to {@see trimToEmpty} but removes whitespace.

StringUtils::stripToEmpty(null);     // ''
StringUtils::stripToEmpty('');       // ''
StringUtils::stripToEmpty('   ');    // ''
StringUtils::stripToEmpty('abc');    // 'abc'
StringUtils::stripToEmpty('  abc');  // 'abc'
StringUtils::stripToEmpty('abc  ');  // 'abc'
StringUtils::stripToEmpty(' abc ');  // 'abc'
StringUtils::stripToEmpty(' ab c '); // 'ab c'

Strips whitespace from the start and end of a string returning null if the string is empty ('') after the strip.

This is similar to {@see trimToNull} but removes whitespace.

StringUtils::stripToNull(null);     // null
StringUtils::stripToNull('');       // null
StringUtils::stripToNull('   ');    // null
StringUtils::stripToNull('abc');    // 'abc'
StringUtils::stripToNull('  abc');  // 'abc'
StringUtils::stripToNull('abc  ');  // 'abc'
StringUtils::stripToNull(' abc ');  // 'abc'
StringUtils::stripToNull(' ab c '); // 'ab c'

Gets a substring from the specified string avoiding exceptions.

A negative start position can be used to start/end n characters from the end of the string.

The returned substring starts with the character in the $start position and ends before the $end position. All position counting is zero-based -- i.e., to start at the beginning of the string use $start = 0.

Negative start and end positions can be used to specify offsets relative to the end of the string.

If $start is not strictly to the left of $end, the empty string is returned.

StringUtils::substring(null, *);       // null
StringUtils::substring('', *);         // ''
StringUtils::substring('abc', 0);      // 'abc'
StringUtils::substring('abc', 2);      // 'c'
StringUtils::substring('abc', 4);      // ''
StringUtils::substring('abc', -2);     // 'bc'
StringUtils::substring('abc', -4);     // 'abc'
StringUtils::substring(null, *, *);    // null
StringUtils::substring('', * ,  *);    // '';
StringUtils::substring('abc', 0, 2);   // 'ab'
StringUtils::substring('abc', 2, 0);   // ''
StringUtils::substring('abc', 2, 4);   // 'c'
StringUtils::substring('abc', 4, 6);   // ''
StringUtils::substring('abc', 2, 2);   // ''
StringUtils::substring('abc', -2, -1); // 'b'
StringUtils::substring('abc', -4, 2);  // 'ab'

Gets the substring after the first occurrence of a separator.

The separator is not returned.

A null string input will return null. An empty ('') string input will return the empty string. A null separator will return the empty string if the input string is not null.

If nothing is found, the empty string is returned.

StringUtils::substringAfter(null, *);      // null
StringUtils::substringAfter('', *);        // ''
StringUtils::substringAfter(*, null);      // ''
StringUtils::substringAfter('abc', 'a');   // 'bc'
StringUtils::substringAfter('abcba', 'b'); // 'cba'
StringUtils::substringAfter('abc', 'c');   // ''
StringUtils::substringAfter('abc', 'd');   // ''
StringUtils::substringAfter('abc', '');    // 'abc'

Gets the substring after the last occurrence of a separator.

The separator is not returned.

A null string input will return null. An empty ('') string input will return the empty string. An empty or null separator will return the empty string if the input string is not null.

If nothing is found, the empty string is returned.

StringUtils::substringAfterLast(null, *);      // null
StringUtils::substringAfterLast('', *);        // ''
StringUtils::substringAfterLast(*, '');        // ''
StringUtils::substringAfterLast(*, null);      // ''
StringUtils::substringAfterLast('abc', 'a');   // 'bc'
StringUtils::substringAfterLast('abcba', 'b'); // 'a'
StringUtils::substringAfterLast('abc', 'c');   // ''
StringUtils::substringAfterLast('a', 'a');     // ''
StringUtils::substringAfterLast('a', 'z');     // ''

Gets the substring before the first occurrence of a separator.

The separator is not returned.

A null string input will return null. An empty ('') string input will return the empty string. A null separator will return the input string.

If nothing is found, the string input is returned.

StringUtils::substringBefore(null, *);      // null
StringUtils::substringBefore('', *);        // ''
StringUtils::substringBefore('abc', 'a');   // ''
StringUtils::substringBefore('abcba', 'b'); // 'a'
StringUtils::substringBefore('abc', 'c');   // 'ab'
StringUtils::substringBefore('abc', 'd');   // 'abc'
StringUtils::substringBefore('abc', '');    // ''
StringUtils::substringBefore('abc', null);  // 'abc'

Gets the substring before the last occurrence of a separator.

The separator is not returned.

A null string input will return null. An empty ('') string input will return the empty string. An empty or null separator will return the input string.

If nothing is found, the string input is returned.

StringUtils::substringBeforeLast(null, *);      // null
StringUtils::substringBeforeLast('', *);        // ''
StringUtils::substringBeforeLast('abcba', 'b'); // 'abc'
StringUtils::substringBeforeLast('abc', 'c');   // 'ab'
StringUtils::substringBeforeLast('a', 'a');     // ''
StringUtils::substringBeforeLast('a', 'z');     // 'a'
StringUtils::substringBeforeLast('a', null);    // 'a'
StringUtils::substringBeforeLast('a', '');      // 'a'

Gets the string that is nested in between two strings.

Only the first match is returned.

A null input string returns null. A null $open/$close returns null (no match). An empty ('') $open and $close returns an empty string.

StringUtils::substringBetween('wx[b]yz', '[', ']');    // 'b'
StringUtils::substringBetween(null, *, *);             // null
StringUtils::substringBetween(*, null, *);             // null
StringUtils::substringBetween(*, *, null);             // null
StringUtils::substringBetween('', '', '');             // ''
StringUtils::substringBetween('', '', ']');            // null
StringUtils::substringBetween('', '[', ']');           // null
StringUtils::substringBetween('yabcz', '', '');        // ''
StringUtils::substringBetween('yabcz', 'y', 'z');      // 'abc'
StringUtils::substringBetween('yabczyabcz', 'y', 'z'); // 'abc'

Removes control characters (char <= 32) from both ends of a string, handling null by returning null.

This method removes start and end characters <= 32. To strip whitespace use {@see strip}.

To trim your choice of characters, use the {@see strip} method.

StringUtils::trim(null);          // null
StringUtils::trim('');            // ''
StringUtils::trim('     ');       // ''
StringUtils::trim('abc');         // 'abc'
StringUtils::trim('    abc    '); // 'abc'

Removes control characters (char <= 32) from both ends of a string returning an empty string ('') if the string is empty ('') after the trim or if it is null.

This method removes start and end characters <= 32. To strip whitespace use {@see stripToEmpty}.

StringUtils::trimToEmpty(null);          // ''
StringUtils::trimToEmpty('');            // ''
StringUtils::trimToEmpty('     ');       // ''
StringUtils::trimToEmpty('abc');         // 'abc'
StringUtils::trimToEmpty('    abc    '); // 'abc'

Removes control characters (char <= 32) from both ends of a string returning null if the string is empty ('') after the trim or if it is null.

This method removes start and end characters <= 32. To strip whitespace use {@see stripToNull}.

StringUtils::trimToNull(null);          // null
StringUtils::trimToNull('');            // null
StringUtils::trimToNull('     ');       // null
StringUtils::trimToNull('abc');         // 'abc'
StringUtils::trimToNull('    abc    '); // 'abc'

Uncapitalizes a string changing the first letter to lower case.

No other letters are changed. For a word based algorithm, see {@see uncapitalize}. A null input string returns null.

StringUtils::uncapitalize(null);  // null
StringUtils::uncapitalize('');    // ''
StringUtils::uncapitalize('Cat'); // 'cat'
StringUtils::uncapitalize('CAT'); // 'cAT'

See also [[StringUtils::capitalize,]] WordUtils::uncapitalize.

Converts a string to upper case.

A null input string returns null.

StringUtils::upperCase(null)  = null
StringUtils::upperCase('')    = ''
StringUtils::upperCase('aBc') = 'ABC'