UTIL_String
Class · Group: Utilities
global inherited sharing class UTIL_StringVarious string manipulation utilities
Example
String shortened = UTIL_String.abbreviate('Now is the time for all good men', 10);
String joined = UTIL_String.join(new List<Object>{'a', 'b', 'c'}, ',');
List<String> parts = UTIL_String.split('one,two,three', ',');
String replaced = UTIL_String.replace('Hello World', 'World', 'Apex');Methods
| Method | Description |
|---|---|
| global static String abbreviate(String input, Integer maxWidth) | Abbreviates a String using ellipses. |
| global static String abbreviate(String input, Integer offset, Integer maxWidth) | Abbreviates a String using ellipses. |
| global static String abbreviate(String input, SObjectField field) | Abbreviates a String to fit within the maximum length of the specified SObjectField. |
| global static String join(List<Object> objectArray, String separator) | Joins the elements of the provided array into a single String containing the provided list of elements. |
| global static String join(Set<String> stringSet, String separator) | Joins the elements of the provided array into a single String containing the provided list of elements. |
| global static String maskString(String sensitiveString) | Will mask the given string |
| global static String maskString(String sensitiveString, Decimal percentageOfStringToBeMasked) | Will mask the given string |
| global static String maskString(String sensitiveString, String maskCharacter, Integer minimumStringLength, Decimal percentageOfStringToBeMasked) | Masks a string |
| global static String remove(String input, String remove) | Removes all occurrences of a substring from within the source string. |
| global static String replace(String text, String searchString, String replacement) | Replaces all occurrences of a String within another String. |
| global static List<String> split(String input) | Splits the provided text into an array, using whitespace as the separator. |
| global static List<String> split(String input, String separatorChars) | Splits the provided text into an array, separators specified. |
| global static List<String> split(String input, String separatorChars, Integer max) | Splits the provided text into an array with a maximum length, separators specified. |
| global static List<String> splitByWholeSeparator(String input, String separator) | Splits the provided text into an array, separator string specified. |
abbreviate
global static String abbreviate(String input, Integer maxWidth)Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "Now is the time for..."
Specifically:
If the number of characters in
inputis less than or equal tomaxWidth, returninput.Else abbreviate it to
(substring(input, 0, max-3) + "...").If
maxWidthis less than4, throw anIllegalArgumentException.In no case will it return a String of length greater than
maxWidth.
Parameters
| Parameter | Type | Description |
|---|---|---|
input | String | the String to check, may be null |
maxWidth | Integer | maximum length of result String, must be at least 4 |
Returns String — abbreviated String, null if null String input
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if the width is too small |
Example
UTIL_String.abbreviate(null, 4); // returns null
UTIL_String.abbreviate('', 4); // returns ''
UTIL_String.abbreviate('abcdefg', 6); // returns 'abc...'
UTIL_String.abbreviate('abcdefg', 7); // returns 'abcdefg'
UTIL_String.abbreviate('abcdefg', 8); // returns 'abcdefg'
UTIL_String.abbreviate('abcdefg', 4); // returns 'a...'
UTIL_String.abbreviate('abcdefg', 3); // throws IllegalArgumentExceptionglobal static String abbreviate(String input, Integer offset, Integer maxWidth)Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "...is the time for..."
Works like String.abbreviate, but allows you to specify a "left edge" offset. Note that this left edge is not necessarily going to be the leftmost character in the result, or the first character following the ellipses, but it will appear somewhere in the result.
In no case will it return a String of length greater than maxWidth
Parameters
| Parameter | Type | Description |
|---|---|---|
input | String | the String to check, may be null |
offset | Integer | left edge of source String |
maxWidth | Integer | maximum length of result String, must be at least 4 |
Returns String — abbreviated String, null if null String input
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if the width is too small |
Example
UTIL_String.abbreviate(null, 0, 4); // returns null
UTIL_String.abbreviate('', 0, 4); // returns ''
UTIL_String.abbreviate('abcdefghijklmno', -1, 10); // returns 'abcdefg...'
UTIL_String.abbreviate('abcdefghijklmno', 0, 10); // returns 'abcdefg...'
UTIL_String.abbreviate('abcdefghijklmno', 1, 10); // returns 'abcdefg...'
UTIL_String.abbreviate('abcdefghijklmno', 4, 10); // returns 'abcdefg...'
UTIL_String.abbreviate('abcdefghijklmno', 5, 10); // returns '...fghi...'
UTIL_String.abbreviate('abcdefghijklmno', 6, 10); // returns '...ghij...'
UTIL_String.abbreviate('abcdefghijklmno', 8, 10); // returns '...ijklmno'
UTIL_String.abbreviate('abcdefghijklmno', 10, 10); // returns '...ijklmno'
UTIL_String.abbreviate('abcdefghijklmno', 12, 10); // returns '...ijklmno'
UTIL_String.abbreviate('abcdefghij', 0, 3); // throws IllegalArgumentException
UTIL_String.abbreviate('abcdefghij', 5, 6); // throws IllegalArgumentExceptionglobal static String abbreviate(String input, SObjectField field)Abbreviates a String to fit within the maximum length of the specified SObjectField. Automatically derives the field length from the field's describe metadata.
Parameters
| Parameter | Type | Description |
|---|---|---|
input | String | the String to abbreviate, may be null |
field | SObjectField | the SObjectField whose length determines the maximum width |
Returns String — abbreviated String fitting within the field length, null if null String input
Example
String shortened = UTIL_String.abbreviateToField(longMessage, LogEntry__c.Message__c);join
global static String join(List<Object> objectArray, String separator)Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
Parameters
| Parameter | Type | Description |
|---|---|---|
objectArray | List | the array of values to join together, may be null |
separator | Object | the separator character to use |
Returns String — the joined String, null if null array input
Example
UTIL_String.join(null, ';'); // returns null
UTIL_String.join(new List<Object>(), ';'); // returns ''
UTIL_String.join(new List<Object>{null}, ';'); // returns ''
UTIL_String.join(new List<Object>{'a', 'b', 'c'}, ';'); // returns 'a;b;c'
UTIL_String.join(new List<Object>{'a', 'b', 'c'}, null); // returns 'abc'
UTIL_String.join(new List<Object>{null, '', 'a'}, ';'); // returns ';a'global static String join(Set<String> stringSet, String separator)Joins the elements of the provided Iterator into a single String containing the provided elements.
No delimiter is added before or after the list. A null separator is the same as an empty String ("").
Parameters
| Parameter | Type | Description |
|---|---|---|
stringSet | Set | the Iterator of values to join together, may be null |
separator | String | the separator character to use, null treated as "" |
Returns String — the joined String, null if null iterator input
Example
String result = UTIL_String.join(new Set<String>{'a', 'b'}, ',');maskString
global static String maskString(String sensitiveString)Will mask the given string
Parameters
| Parameter | Type | Description |
|---|---|---|
sensitiveString | String | The string to mask |
Returns String — A Masked string
Example
String result = UTIL_String.maskString('value');global static String maskString(String sensitiveString, Decimal percentageOfStringToBeMasked)Will mask the given string
Parameters
| Parameter | Type | Description |
|---|---|---|
sensitiveString | String | The string to mask |
percentageOfStringToBeMasked | Decimal | The percentage of string to be masked |
Returns String — A Masked string
Example
String result = UTIL_String.maskString('value', 99.99);global static String maskString(String sensitiveString, String maskCharacter, Integer minimumStringLength, Decimal percentageOfStringToBeMasked)Masks a string
Parameters
| Parameter | Type | Description |
|---|---|---|
sensitiveString | String | The string to mask |
maskCharacter | String | The character to be used for masking |
minimumStringLength | Integer | The minimum length of the input string which is to be masked |
percentageOfStringToBeMasked | Decimal | The percentage of string to be masked |
Returns String — A Masked string
Example
String result = UTIL_String.maskString('value', 'value', 10, 99.99);remove
global static String remove(String input, String remove)Removes all occurrences of a substring from within the source string.
Parameters
| Parameter | Type | Description |
|---|---|---|
input | String | the source String to search, may be null |
remove | String | the String to search for and remove, may be null |
Returns String — the substring with the string removed if found, null if null String input
Example
UTIL_String.remove(null, 'ue'); // returns null
UTIL_String.remove('', 'ue'); // returns ''
UTIL_String.remove('queued', null); // returns 'queued'
UTIL_String.remove('queued', ''); // returns 'queued'
UTIL_String.remove('queued', 'ue'); // returns 'qd'
UTIL_String.remove('queued', 'zz'); // returns 'queued'replace
global static String replace(String text, String searchString, String replacement)Replaces all occurrences of a String within another String.
A null reference passed to this method is a no-op.
Parameters
| Parameter | Type | Description |
|---|---|---|
text | String | text to search and replace in, may be null |
searchString | String | the String to search for, may be null |
replacement | String | the String to replace it with, may be null |
Returns String — the text with any replacements processed, null if null String input
Example
UTIL_String.replace(null, 'a', 'z'); // returns null
UTIL_String.replace('', 'a', 'z'); // returns ''
UTIL_String.replace('any', null, 'z'); // returns 'any'
UTIL_String.replace('any', 'a', null); // returns 'any'
UTIL_String.replace('any', '', 'z'); // returns 'any'
UTIL_String.replace('aba', 'a', null); // returns 'aba'
UTIL_String.replace('aba', 'a', ''); // returns 'b'
UTIL_String.replace('aba', 'a', 'z'); // returns 'zbz'split
global static List<String> split(String input)Splits the provided text into an array, using whitespace as the separator. Whitespace is defined by UTIL_Character.isWhitespace.
The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.
A null input String returns null.
Parameters
| Parameter | Type | Description |
|---|---|---|
input | String | the String to parse, may be null |
Returns String — an array of parsed Strings, null if null String input
Example
UTIL_String.split(null); // returns null
UTIL_String.split(''); // returns new List<String>()
UTIL_String.split('abc def'); // returns new List<String>{'abc', 'def'}
UTIL_String.split('abc def'); // returns new List<String>{'abc', 'def'}
UTIL_String.split(' abc '); // returns new List<String>{'abc'}global static List<String> split(String input, String separatorChars)Splits the provided text into an array, separators specified. This is an alternative to using StringTokenizer.
The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.
A null input String returns null. A null separatorChars splits on whitespace.
Parameters
| Parameter | Type | Description |
|---|---|---|
input | String | the String to parse, may be null |
separatorChars | String | the characters used as the delimiters, null splits on whitespace |
Returns String — an array of parsed Strings, null if null String input
Example
UTIL_String.split(null, ' '); // returns null
UTIL_String.split('', ' '); // returns new List<String>()
UTIL_String.split('abc def', null); // returns new List<String>{'abc', 'def'}
UTIL_String.split('abc def', ' '); // returns new List<String>{'abc', 'def'}
UTIL_String.split('abc def', ' '); // returns new List<String>{'abc', 'def'}
UTIL_String.split('ab:cd:ef', ':'); // returns new List<String>{'ab', 'cd', 'ef'}global static List<String> split(String input, String separatorChars, Integer max)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 separatorChars splits on whitespace.
If more than max delimited substrings are found, the last returned string includes all characters after the first max - 1 returned strings (including separator characters).
Parameters
| Parameter | Type | Description |
|---|---|---|
input | String | the String to parse, may be null |
separatorChars | String | the characters used as the delimiters, null splits on whitespace |
max | Integer | the maximum number of elements to include in the array. A zero or negative value implies no limit |
Returns String — an array of parsed Strings, null if null String input
Example
UTIL_String.split(null, ':', 0); // returns null
UTIL_String.split('', ':', 0); // returns new List<String>()
UTIL_String.split('ab cd ef', null, 0); // returns new List<String>{'ab', 'cd', 'ef'}
UTIL_String.split('ab cd ef', null, 0); // returns new List<String>{'ab', 'cd', 'ef'}
UTIL_String.split('ab:cd:ef', ':', 0); // returns new List<String>{'ab', 'cd', 'ef'}
UTIL_String.split('ab:cd:ef', ':', 2); // returns new List<String>{'ab', 'cd:ef'}splitByWholeSeparator
global static List<String> splitByWholeSeparator(String input, String separator)Splits the provided text into an array, separator string specified.
The separator(s) will not be included in the returned String array. Adjacent separators are treated as one separator.
A null input String returns null. A null separator splits on whitespace.
Parameters
| Parameter | Type | Description |
|---|---|---|
input | String | the String to parse, may be null |
separator | String | String containing the String to be used as a delimiter, null splits on whitespace |
Returns String — an array of parsed Strings, null if null String was input
Example
UTIL_String.splitByWholeSeparator(null, '-!-'); // returns null
UTIL_String.splitByWholeSeparator('', '-!-'); // returns new List<String>()
UTIL_String.splitByWholeSeparator('ab de fg', null); // returns new List<String>{'ab', 'de', 'fg'}
UTIL_String.splitByWholeSeparator('ab de fg', null); // returns new List<String>{'ab', 'de', 'fg'}
UTIL_String.splitByWholeSeparator('ab:cd:ef', ':'); // returns new List<String>{'ab', 'cd', 'ef'}
UTIL_String.splitByWholeSeparator('ab-!-cd-!-ef', '-!-'); // returns new List<String>{'ab', 'cd', 'ef'}