> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-language/reference/types/string.md).
# string
In BoxLang, the `string` type is represented by the native Java class `java.lang.String`. The member functions below are provided by the BoxLang runtime and can be called directly on the value, in addition to the methods of the underlying Java class.
The `String` class represents character strings.
## String Methods
ascii()
Determine the ASCII value of a character
### Method Signature
```
ascii()
```
### Arguments
This function does not accept any arguments
bind(placeholders=[structloose])
This BIF allows you to bind a string with placeholders to a set of values.
Each placeholder is defined as `${placeholder-name`} and can be used anywhere and multiple times in the string.
### Method Signature
```
bind(placeholders=[structloose])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------------- | -------- | -------- | ------------------------------------------ | ------- |
| `placeholders` | `struct` | `true` | A struct containing the placeholder values | |
booleanFormat()
Returns the value formatted as a boolean string
### Method Signature
```
booleanFormat()
```
### Arguments
This function does not accept any arguments
bxDump(label=[string], depth=[numeric], maxRows=[numeric], top=[numeric], expand=[boolean], abort=[boolean], output=[string], format=[string], showUDFs=[boolean])
Outputs the contents of a variable (simple or complex) of any type for debugging purposes to a specific output location.
The available `output` locations are: - **buffer**: The output is written to the buffer, which is the default location. If running on a web server, the output is written to the browser. - **console**: The output is printed to the System console. - **Absolute File Path** The output is written to a file with the specified absolute file path.
The output `format` can be either HTML or plain text.
The default format is HTML if the output location is the buffer or a web server or a file, otherwise it is plain text for the console.
### Method Signature
```
bxDump(label=[string], depth=[numeric], maxRows=[numeric], top=[numeric], expand=[boolean], abort=[boolean], output=[string], format=[string], showUDFs=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `label` | `string` | `false` | A custom label to display above the dump (Only in HTML output) | |
| `depth` | `numeric` | `false` | The recursion depth to display when dumping nested collections. 1-based: -1 (default) is unlimited, 0 shows nothing,
1 shows the top level with no recursion, 2 recurses once, etc. (Only in HTML output)
| |
| `maxRows` | `numeric` | `false` | The maximum number of keys/rows/items to display per level of a collection, array, or query. 1-based: -1 (default)
is unlimited, 0 shows nothing, 1 shows a single row, etc. (Only in HTML output)
| |
| `top` | `numeric` | `false` | Deprecated: use maxRows instead. When maxRows is not also passed, top's value is used as maxRows.
Kept for backwards compatibility with existing BoxLang code. (Only in HTML output)
| |
| `expand` | `boolean` | `false` | Whether to expand the dump. Be default, we try to expand as much as possible. (Only in HTML output) | `true` |
| `abort` | `boolean` | `false` | Whether to do a hard abort the request after dumping. Default is false | `false` |
| `output` | `string` | `false` | The output format which can be "buffer", "console", or "{absolute file path}". The default is "buffer". | |
| `format` | `string` | `false` | The format of the output to a **filename**. Can be "html" or "text". The default is according to the output location. | |
| `showUDFs` | `boolean` | `false` | Show UDFs or not. Default is true. (Only in HTML output) | `true` |
camelCase()
Convert a string to camel case
### Method Signature
```
camelCase()
```
### Arguments
This function does not accept any arguments
charsetDecode(encoding=[string])
Encodes a string to a binary representation
### Method Signature
```
charsetDecode(encoding=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------- | ------- |
| `encoding` | `string` | `false` | The charset encoding to use (default: utf-8 ) | `utf-8` |
compare(string2=[any])
Performs a case-sensitive comparison of two strings.
-1, if string1 is less than string2 0, if string1 is equal to string2 1, if string1 is greater than string2
### Method Signature
```
compare(string2=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------- | ----- | -------- | ---------------------------- | ------- |
| `string2` | `any` | `true` | The second string to compare | |
compareNoCase(string2=[string])
Performs a case-insensitive comparison of two strings.
-1, if string1 is less than string2 0, if string1 is equal to string2 1, if string1 is greater than string2
### Method Signature
```
compareNoCase(string2=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------- | -------- | -------- | ---------------------------- | ------- |
| `string2` | `string` | `true` | The second string to compare | |
dateFormat(mask=[string], timezone=[string], locale=[string])
Formats a datetime, date or time
### Method Signature
```
dateFormat(mask=[string], timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `mask` | `string` | `false` | Optional format mask, or common mask. If an explicit mask is used, it should use the mask characters specified in the
java.time.format.DateTimeFormatter class.
If a common mask is used, the following are supported:
- short: equivalent to "M/d/y h:mm tt"
- medium: equivalent to "MMM d, yyyy h🇲🇲ss tt"
- long: medium followed by three-letter time zone; i.e. "MMMM d, yyyy h🇲🇲ss tt zzz"
- full: equivalent to "dddd, MMMM d, yyyy H🇲🇲ss tt zz"
- ISO8601/ISO: equivalent to "yyyy-MM-dd'T'HH🇲🇲ssXXX"
- epoch: Total seconds of a given date (Example:1567517664)
- epochms: Total milliseconds of a given date (Example:1567517664000)
| |
| `timezone` | `string` | `false` | Optional specific timezone to apply to the date ( if not present in the date string ) | |
| `locale` | `string` | `false` | Optional ISO locale string which will be used to localize the resulting date/time string | |
dateTimeFormat(mask=[string], timezone=[string], locale=[string])
Formats a datetime, date or time
### Method Signature
```
dateTimeFormat(mask=[string], timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `mask` | `string` | `false` | Optional format mask, or common mask. If an explicit mask is used, it should use the mask characters specified in the
java.time.format.DateTimeFormatter class.
If a common mask is used, the following are supported:
- short: equivalent to "M/d/y h:mm tt"
- medium: equivalent to "MMM d, yyyy h🇲🇲ss tt"
- long: medium followed by three-letter time zone; i.e. "MMMM d, yyyy h🇲🇲ss tt zzz"
- full: equivalent to "dddd, MMMM d, yyyy H🇲🇲ss tt zz"
- ISO8601/ISO: equivalent to "yyyy-MM-dd'T'HH🇲🇲ssXXX"
- epoch: Total seconds of a given date (Example:1567517664)
- epochms: Total milliseconds of a given date (Example:1567517664000)
| |
| `timezone` | `string` | `false` | Optional specific timezone to apply to the date ( if not present in the date string ) | |
| `locale` | `string` | `false` | Optional ISO locale string which will be used to localize the resulting date/time string | |
day(timezone=[string], locale=[string])
Returns the day of the month of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
day(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
dayOfWeek(timezone=[string], locale=[string])
Returns the numeric day of the week of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
dayOfWeek(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
dayOfWeekAsString(timezone=[string], locale=[string])
Returns the full day of the week name of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
dayOfWeekAsString(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
dayOfWeekShortAsString(timezone=[string], locale=[string])
Returns the short day of the week name of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
dayOfWeekShortAsString(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
dayOfYear(timezone=[string], locale=[string])
Returns the numeric day of the year of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
dayOfYear(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
daysInMonth(timezone=[string], locale=[string])
Returns the number of days in the month of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
daysInMonth(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
daysInYear(timezone=[string], locale=[string])
Return the number of days in the year of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
daysInYear(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
endsWith(substring=[string])
Determines whether a string ends with a specified suffix.
### Method Signature
```
endsWith(substring=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | -------- | -------- | ------------------------ | ------- |
| `substring` | `string` | `true` | The suffix to check for. | |
endsWithNoCase(substring=[string])
Determines whether a string ends with a specified suffix, case-insensitive.
### Method Signature
```
endsWithNoCase(substring=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | -------- | -------- | ------------------------ | ------- |
| `substring` | `string` | `true` | The suffix to check for. | |
find(substring=[string], start=[integer])
Finds the first occurrence of a substring in a string, from a specified start position.
### Method Signature
```
find(substring=[string], start=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | --------- | -------- | ----------------------------------------------------------------------- | ------- |
| `substring` | `string` | `true` | The string you are looking for. | |
| `start` | `integer` | `false` | The position from which to start searching in the string. Default is 1. | `1` |
findNoCase(substring=[string], start=[integer])
Finds the first occurrence of a substring in a string, from a specified start position.
### Method Signature
```
findNoCase(substring=[string], start=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | --------- | -------- | ----------------------------------------------------------------------- | ------- |
| `substring` | `string` | `true` | The string you are looking for. | |
| `start` | `integer` | `false` | The position from which to start searching in the string. Default is 1. | `1` |
findOneOf(set=[string], start=[integer])
Finds the first occurrence of any character in a set of characters, from a specified start position.
### Method Signature
```
findOneOf(set=[string], start=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | ----------------------------------------------------------------------- | ------- |
| `set` | `string` | `true` | The set of characters to search for the first occurrence of. | |
| `start` | `integer` | `false` | The position from which to start searching in the string. Default is 1. | `1` |
firstDayOfMonth(timezone=[string], locale=[string])
Returns the first date of the month of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
firstDayOfMonth(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
fromJSON(strictMapping=[boolean], useCustomSerializer=[string])
Converts a JSON (JavaScript Object Notation) string data representation into data, such as a structure or array.
JSON deserialization in BoxLang will always use ordered structs for objects which will preserve the key order of the original JSON string. This is handy when reading a JSON file, modifying it, and writing it back out.
### Method Signature
```
fromJSON(strictMapping=[boolean], useCustomSerializer=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ | ------- |
| `strictMapping` | `boolean` | `false` | A Boolean value that specifies whether to convert the JSON strictly. If true, everything becomes structures. | `true` |
| `useCustomSerializer` | `string` | `false` | A string that specifies the name of a custom serializer to use. (Not used) | |
getnumericdate(timezone=[string], locale=[string])
Returns the numeric date in days from epoch of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
getnumericdate(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
getToken(index=[integer], delimiter=[string])
Determines whether a token of the list in the delimiters parameter is present in a string.
Returns the token found at position index of the string, as a string. If index is greater than the number of tokens in the string, returns an empty string.
### Method Signature
```
getToken(index=[integer], delimiter=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | --------- | -------- | ------------------------------------------------------------- | ------- |
| `index` | `integer` | `true` | numeric the one-based index position to retrieve the value at | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
hash(algorithm=[string], encoding=[string], numIterations=[integer])
Creates an algorithmic hash of an object
### Method Signature
```
hash(algorithm=[string], encoding=[string], numIterations=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------- | ------- |
| `algorithm` | `string` | `false` | The supported `java.security.MessageDigest` algorithm (case-insensitive) or "quick" for an insecure 64-bit hash | `MD5` |
| `encoding` | `string` | `false` | Applicable to strings ( default "utf-8" ) | `utf-8` |
| `numIterations` | `integer` | `false` | The number of iterations to re-digest the object ( default 1 ); | `1` |
hmac(key=[any], algorithm=[string], encoding=[string], numIterations=[integer])
Creates an algorithmic hash of an object
### Method Signature
```
hmac(key=[any], algorithm=[string], encoding=[string], numIterations=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------------- | --------- | -------- | ---------------------------------------------------------------------------- | --------- |
| `key` | `any` | `true` | The secret key used to generate the HMAC. Can be a string or a binary value. | |
| `algorithm` | `string` | `false` | The supported `java.security.MessageDigest` algorithm (case-insensitive) | `HmacMD5` |
| `encoding` | `string` | `false` | Applicable to strings ( default "utf-8" ) | `utf-8` |
| `numIterations` | `integer` | `false` | The number of iterations to re-digest the object ( default 1 ); | `1` |
hour(timezone=[string], locale=[string])
Returns the hour of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
hour(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
inputBaseN(radix=[integer])
Converts a string, using the base specified by radix, to an integer.
### Method Signature
```
inputBaseN(radix=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | ------------------------------------------------------------ | ------- |
| `radix` | `integer` | `true` | Base of the number represented by string, in the range 2-36. | |
insert(substring=[string], position=[integer])
Inserts a substring into another string at a specified position.
### Method Signature
```
insert(substring=[string], position=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | --------- | -------- | ------------------------------------------- | ------- |
| `substring` | `string` | `true` | The string to insert. | |
| `position` | `integer` | `true` | The position at which to insert the string. | |
isEmpty()
Determine whether a given value is empty.
We check for emptiness of anything that can be casted to: Array, Struct, Query, or String.
### Method Signature
```
isEmpty()
```
### Arguments
This function does not accept any arguments
jsFormat()
Escapes special JavaScript characters, such as single quotation mark, double quotation mark, and newline
### Method Signature
```
jsFormat()
```
### Arguments
This function does not accept any arguments
jSONDeserialize(strictMapping=[boolean], useCustomSerializer=[string])
Converts a JSON (JavaScript Object Notation) string data representation into data, such as a structure or array.
JSON deserialization in BoxLang will always use ordered structs for objects which will preserve the key order of the original JSON string. This is handy when reading a JSON file, modifying it, and writing it back out.
### Method Signature
```
jSONDeserialize(strictMapping=[boolean], useCustomSerializer=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------ | ------- |
| `strictMapping` | `boolean` | `false` | A Boolean value that specifies whether to convert the JSON strictly. If true, everything becomes structures. | `true` |
| `useCustomSerializer` | `string` | `false` | A string that specifies the name of a custom serializer to use. (Not used) | |
jSONPrettify()
Prettifies a JSON string.
### Method Signature
```
jSONPrettify()
```
### Arguments
This function does not accept any arguments
kebabCase()
Convert a string to kebab case
### Method Signature
```
kebabCase()
```
### Arguments
This function does not accept any arguments
lCase()
Uppercase a string
### Method Signature
```
lCase()
```
### Arguments
This function does not accept any arguments
left(count=[integer])
Extract the leftmost count characters from a string
### Method Signature
```
left(count=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | ------------------------------------- | ------- |
| `count` | `integer` | `true` | The number of characters to retrieve. | |
len()
Returns the absolute value of a number
### Method Signature
```
len()
```
### Arguments
This function does not accept any arguments
listAppend(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Appends an element to a list
### Method Signature
```
listAppend(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `value` | `string` | `true` | The value to append | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listAvg(delimiter=[string], multiCharacterDelimiter=[boolean])
Gets the average of all values in a list
### Method Signature
```
listAvg(delimiter=[string], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ------------------------------------------------ | ------- |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listChangeDelims(newDelimiter=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Converts the delimiters of a list to the new delimiter.
### Method Signature
```
listChangeDelims(newDelimiter=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `newDelimiter` | `string` | `true` | string the new list delimiter | |
| `delimiter` | `string` | `false` | string the old list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listCompact(delimiter=[string], multiCharacterDelimiter=[boolean])
Compacts a list by removing empty items from the start and end of the list
### Method Signature
```
listCompact(delimiter=[string], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ------------------------------------------------ | ------- |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listContains(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Return int position of value in delimited list, case sensitive or case-insenstive variations
### Method Signature
```
listContains(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ---------------------------------------------------------------- | ------- |
| `value` | `string` | `true` | The value to locate in the list or a function to filter the list | |
| `delimiter` | `string` | `false` | The list delimiter(s) | `,` |
| `includeEmptyFields` | `boolean` | `false` | Whether to include empty fields in the search | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listContainsNoCase(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Return int position of value in delimited list, case sensitive or case-insenstive variations
### Method Signature
```
listContainsNoCase(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ---------------------------------------------------------------- | ------- |
| `value` | `string` | `true` | The value to locate in the list or a function to filter the list | |
| `delimiter` | `string` | `false` | The list delimiter(s) | `,` |
| `includeEmptyFields` | `boolean` | `false` | Whether to include empty fields in the search | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listDeleteAt(position=[integer], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Deletes an element from a list.
Returns a copy of the list, without the specified element.
### Method Signature
```
listDeleteAt(position=[integer], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | --------------------------------------------------------------- | ------- |
| `position` | `integer` | `true` | The one-based index position of the element to delete. | |
| `delimiter` | `string` | `false` | The delimiter used in the list. | `,` |
| `includeEmptyFields` | `boolean` | `false` | Whether to include empty fields in the list. | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | Whether the delimiter is a multi-character
delimiter.
| `false` |
listEach(callback=[function:Consumer], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[any], ordered=[boolean], virtual=[boolean])
Used to iterate over a delimited list and run the function closure for each item in the list.
This BIF is similar to the ArrayEach BIF, but operates on a delimited list instead of an array.
## Parallel Execution
If the `parallel` argument is set to true, and no `max_threads` are sent, the filter will be executed in parallel using a ForkJoinPool with parallel streams. If `max_threads` is specified, it will create a new ForkJoinPool with the specified number of threads to run the filter in parallel, and destroy it after the operation is complete. Please note that this may not be the most efficient way to iterate, as it will create a new ForkJoinPool for each invocation of the BIF. You may want to consider using a shared ForkJoinPool for better performance.
### Method Signature
```
listEach(callback=[function:Consumer], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[any], ordered=[boolean], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:Consumer` | `true` | The function to invoke for each item. The function will be passed 3 arguments: the value, the index, the array. You can alternatively pass a Java Consumer which will only receive the 1st arg. | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
| `parallel` | `boolean` | `false` | Whether to run the filter in parallel. Defaults to false. If true, the filter will be run in parallel using a ForkJoinPool. | `false` |
| `maxThreads` | `any` | `false` | The maximum number of threads to use when running the filter in parallel. If not passed it will use the default number of threads for the ForkJoinPool.
If parallel is false, this argument is ignored. If a boolean is provided it will be assigned to the virtual argument instead.
| |
| `ordered` | `boolean` | `false` | Whether parallel operations should execute and maintain order | `false` |
| `virtual` | `boolean` | `false` | If true, the function will be invoked using virtual threads. Defaults to false. Ignored if parallel is false. | `false` |
listEvery(callback=[function:Predicate], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[any], virtual=[boolean])
Used to iterate over a delimited list and test whether **every** item meets the test callback.
The function will be passed 3 arguments: the value, the index, and the list. You can alternatively pass a Java Predicate which will only receive the 1st arg. The function should return true if the item meets the test, and false otherwise.
**Note:** This operation is a short-circuit operation, meaning it will stop iterating as soon as it finds the first item that does not meet the test condition.
## Parallel Execution
If the `parallel` argument is set to true, and no `max_threads` are sent, the filter will be executed in parallel using a ForkJoinPool with parallel streams. If `max_threads` is specified, it will create a new ForkJoinPool with the specified number of threads to run the filter in parallel, and destroy it after the operation is complete. This allows for efficient processing of large lists, especially when the test function is computationally expensive or the list is large.
### Method Signature
```
listEvery(callback=[function:Predicate], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[any], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `callback` | `function:Predicate` | `true` | | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
| `parallel` | `boolean` | `false` | Whether to run the filter in parallel. Defaults to false. If true, the filter will be run in parallel using a ForkJoinPool. | `false` |
| `maxThreads` | `any` | `false` | The maximum number of threads to use when running in parallel. If not passed it will use the default number of threads for the ForkJoinPool.
If parallel is false, this argument is ignored. If a boolean is provided it will be assigned to the virtual argument instead.
| |
| `virtual` | `boolean` | `false` | If true, the function will be invoked using virtual threads. Defaults to false. Ignored if parallel is false. | `false` |
listFilter(filter=[function:Predicate], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[any], virtual=[boolean])
Filters a delimted list and returns the values from the callback test This BIF will invoke the callback function for each entry in the list, passing the entry as a string.
* If the callback returns true, the entry will be included in the new list.
* If the callback returns false, the entry will be excluded from the new list.
* If the callback requires strict arguments, it will only receive the entry as a string.
* If the callback does not require strict arguments, it will receive the entry as a string, the index (0-based), and the original list as a string.
## Parallel Execution
If the `parallel` argument is set to true, and no `max_threads` are sent, the filter will be executed in parallel using a ForkJoinPool with parallel streams. If `max_threads` is specified, it will create a new ForkJoinPool with the specified number of threads to run the filter in parallel, and destroy it after the operation is complete. Please note that this may not be the most efficient way to filter, as it will create a new ForkJoinPool for each invocation of the BIF. You may want to consider using a shared ForkJoinPool for better performance.
### Method Signature
```
listFilter(filter=[function:Predicate], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[any], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `filter` | `function:Predicate` | `true` | function closure filter test. You can alternatively pass a Java Predicate which will only receive the 1st arg. | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
| `parallel` | `boolean` | `false` | Whether to run the filter in parallel. Defaults to false. If true, the filter will be run in parallel using a ForkJoinPool. | `false` |
| `maxThreads` | `any` | `false` | The maximum number of threads to use when running the filter in parallel. If not passed it will use the default number of threads for the ForkJoinPool.
If parallel is false, this argument is ignored. If a boolean is provided it will be assigned to the virtual argument instead.
| |
| `virtual` | `boolean` | `false` | If true, the function will be invoked using virtual threads. Defaults to false. Ignored if parallel is false. | `false` |
listFind(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Return int position of value in delimited list, case sensitive or case-insenstive variations
### Method Signature
```
listFind(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ---------------------------------------------------------------- | ------- |
| `value` | `string` | `true` | The value to locate in the list or a function to filter the list | |
| `delimiter` | `string` | `false` | The list delimiter(s) | `,` |
| `includeEmptyFields` | `boolean` | `false` | Whether to include empty fields in the search | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listFindNoCase(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Return int position of value in delimited list, case sensitive or case-insenstive variations
### Method Signature
```
listFindNoCase(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ---------------------------------------------------------------- | ------- |
| `value` | `string` | `true` | The value to locate in the list or a function to filter the list | |
| `delimiter` | `string` | `false` | The list delimiter(s) | `,` |
| `includeEmptyFields` | `boolean` | `false` | Whether to include empty fields in the search | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listFirst(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Returns the first or last item in a delimited list, according to the specified function name
### Method Signature
```
listFirst(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listGetAt(position=[integer], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Retrieves an item from a delimited list at the specified position
### Method Signature
```
listGetAt(position=[integer], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `position` | `integer` | `true` | numeric the one-based index position to retrieve the value at | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listIndexExists(index=[integer], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Checks if a list has a given index
### Method Signature
```
listIndexExists(index=[integer], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `index` | `integer` | `true` | numeric The index to check for | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listInsertAt(position=[integer], value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Filters a delimted list and returns the values from the callback test
### Method Signature
```
listInsertAt(position=[integer], value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `position` | `integer` | `true` | | |
| `value` | `string` | `true` | | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listItemTrim(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Trims each item in the list.
### Method Signature
```
listItemTrim(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listLast(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Returns the first or last item in a delimited list, according to the specified function name
### Method Signature
```
listLast(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listLen(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Calculates the length of a list separated by the specified delimiter
### Method Signature
```
listLen(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listMap(callback=[function:Function], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[any], virtual=[boolean])
This BIF will iterate over each item in the delimited list and invoke the callback function for each item so you can do any operation on the item and return a new value that will be set at the same index in a new list.
The callback function will be passed the item as a string, the current index (0-based), and the original list.
* If the callback requires strict arguments, it will only receive the item as a string.
* If the callback does not require strict arguments, it will receive the item as a string, the index (0-based), and the original list.
## Parallel Execution
If the `parallel` argument is set to true, and no `max_threads` are sent, the map will be executed in parallel using a ForkJoinPool with parallel streams. If `max_threads` is specified, it will create a new ForkJoinPool with the specified number of threads to run the map in parallel, and destroy it after the operation is complete. Please note that this may not be the most efficient way to map, as it will create a new ForkJoinPool for each invocation of the BIF. You may want to consider using a shared ForkJoinPool for better performance.
### Method Signature
```
listMap(callback=[function:Function], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[any], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:Function` | `true` | The function to invoke for each item. The function will be passed 3 arguments: the value, the index, the array. You can alternatively pass a Java Function which will only receive the 1st arg. | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
| `parallel` | `boolean` | `false` | Whether to run the filter in parallel. Defaults to false. If true, the filter will be run in parallel using a ForkJoinPool. | `false` |
| `maxThreads` | `any` | `false` | The maximum number of threads to use when running the filter in parallel. If not passed it will use the default number of threads for the ForkJoinPool.
If parallel is false, this argument is ignored. If a boolean is provided it will be assigned to the virtual argument instead.
| |
| `virtual` | `boolean` | `false` | If true, the function will be invoked using virtual threads. Defaults to false. Ignored if parallel is false. | `false` |
listNone(callback=[function:Predicate], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[any], virtual=[boolean])
Used to iterate over a delimited list and test whether **NONE** item meets the test callback.
This is the opposite of `ListSome`.
The function will be passed 3 arguments: the value, the index, and the list. You can alternatively pass a Java Predicate which will only receive the 1st arg. The function should return true if the item meets the test, and false otherwise.
**Note:** This operation is a short-circuit operation, meaning it will stop iterating as soon as it finds the first item that does not meet the test condition.
## Parallel Execution
If the `parallel` argument is set to true, and no `max_threads` are sent, the filter will be executed in parallel using a ForkJoinPool with parallel streams. If `max_threads` is specified, it will create a new ForkJoinPool with the specified number of threads to run the filter in parallel, and destroy it after the operation is complete. This allows for efficient processing of large lists, especially when the test function is computationally expensive or the list is large.
### Method Signature
```
listNone(callback=[function:Predicate], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[any], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:Predicate` | `true` | | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
| `parallel` | `boolean` | `false` | Whether to run the filter in parallel. Defaults to false. If true, the filter will be run in parallel using a ForkJoinPool. | `false` |
| `maxThreads` | `any` | `false` | The maximum number of threads to use when running the filter in parallel. If not passed it will use the default number of threads for the ForkJoinPool.
If parallel is false, this argument is ignored. If a boolean is provided it will be assigned to the virtual argument instead.
| |
| `virtual` | `boolean` | `false` | If true, the function will be invoked using virtual threads. Defaults to false. Ignored if parallel is false. | `false` |
listPrepend(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Filters a delimted list and returns the values from the callback test
### Method Signature
```
listPrepend(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `value` | `string` | `true` | | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listQualify(qualifier=[string], delimiter=[string], elements=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Inserts a string at the beginning and end of list elements.
If this BIF is being called from inside of a query component, and the qualifier is a single quote, any single quotes in the values will be escaped by doubling them up. This protects against SQL Injection attacks.
### Method Signature
```
listQualify(qualifier=[string], delimiter=[string], elements=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------- | ------- |
| `qualifier` | `string` | `true` | The string to insert at the beginning and end of each element. | |
| `delimiter` | `string` | `false` | The delimiter used in the list. | `,` |
| `elements` | `string` | `false` | The elements to qualify. If set to "char", only elements that are all alphabetic characters will be qualified. | `all` |
| `includeEmptyFields` | `boolean` | `false` | If true, empty fields will be qualified. | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listReduce(callback=[function:BiFunction], initialValue=[any], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Run the provided udf over a delimited list to reduce the values to a single output
### Method Signature
```
listReduce(callback=[function:BiFunction], initialValue=[any], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:BiFunction` | `true` | The function to invoke for each item. The function will be passed 3 arguments: the value, the index, the array. You can alternatively pass a Java BiFunction which will only receive the ffirst 2 args. | |
| `initialValue` | `any` | `false` | The initial value of the reduction | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `true` |
listReduceRight(callback=[function:BiFunction], initialValue=[any], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Run the provided udf over a reversed delimited list to reduce the values to a single output
### Method Signature
```
listReduceRight(callback=[function:BiFunction], initialValue=[any], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `callback` | `function:BiFunction` | `true` | The function to invoke for each item. The function will be passed 3 arguments: the value, the index, the array. You can alternatively pass a Java BiFunction which will only receive the first 2 args. | |
| `initialValue` | `any` | `false` | The initial value of the reduction | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listRemoveDuplicates(delimiter=[string], ignoreCase=[boolean], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
De-duplicates a delimited list - either case-sensitively or case-insenstively
### Method Signature
```
listRemoveDuplicates(delimiter=[string], ignoreCase=[boolean], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ------------------------------------------------------------------------------ | ------- |
| `delimiter` | `string` | `false` | The delimiter of the list | `,` |
| `ignoreCase` | `boolean` | `false` | Whether case should be ignored or not during deduplication - defaults to false | `false` |
| `includeEmptyFields` | `boolean` | `false` | | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listRest(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], offset=[integer])
Returns the remainder of a list after removing the first item
### Method Signature
```
listRest(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], offset=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
| `offset` | `integer` | `false` | | `1` |
listSetAt(position=[integer], value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Retrieves an item in to a delimited list at the specified position
### Method Signature
```
listSetAt(position=[integer], value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `position` | `integer` | `true` | numeric the one-based index position to retrieve the value at | |
| `value` | `string` | `true` | string the value to set at the specified position | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listSome(callback=[function:Predicate], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[integer], virtual=[boolean])
Used to iterate over a delimited list and test whether **ANY** items meet the test callback.
The function will be passed 3 arguments: the value, the index, and the list. You can alternatively pass a Java Predicate which will only receive the 1st arg. The function should return true if the item meets the test, and false otherwise.
**Note:** This operation is a short-circuit operation, meaning it will stop iterating as soon as it finds the first item that meets the test condition.
## Parallel Execution
If the `parallel` argument is set to true, and no `max_threads` are sent, the filter will be executed in parallel using a ForkJoinPool with parallel streams. If `max_threads` is specified, it will create a new ForkJoinPool with the specified number of threads to run the filter in parallel, and destroy it after the operation is complete. Please note that this may not be the most efficient way to iterate, as it will create a new ForkJoinPool for each invocation of the BIF. You may want to consider using a shared ForkJoinPool for better performance.
### Method Signature
```
listSome(callback=[function:Predicate], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[integer], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:Predicate` | `true` | | |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
| `parallel` | `boolean` | `false` | Whether to run the filter in parallel. Defaults to false. If true, the filter will be run in parallel using a ForkJoinPool. | `false` |
| `maxThreads` | `integer` | `false` | The maximum number of threads to use when running the filter in parallel. If not passed it will use the default number of threads for the ForkJoinPool.
If parallel is false, this argument is ignored. If a boolean is provided it will be assigned to the virtual argument instead.
| |
| `virtual` | `boolean` | `false` | If true, the function will be invoked using virtual threads. Defaults to false. Ignored if parallel is false. | `false` |
listSort(sortType=[any], sortOrder=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], localeSensitive=[boolean], callback=[any])
Sorts a delimited list and returns the result
### Method Signature
```
listSort(sortType=[any], sortOrder=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], localeSensitive=[boolean], callback=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------- | ------- |
| `sortType` | `any` | `false` | Options are text, numeric, or textnocase | |
| `sortOrder` | `string` | `false` | Options are asc or desc | `asc` |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
| `localeSensitive` | `boolean` | `false` | Sort based on local rules | `false` |
| `callback` | `any` | `false` | Optional function to use for sorting - if the sort type is a closure, it will be recognized as a callback | |
listToArray(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Converts a delimited list to an array
### Method Signature
```
listToArray(delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `includeEmptyFields` | `boolean` | `false` | boolean whether to include empty fields in the returned result | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listToJSON(queryFormat=[string], useSecureJSONPrefix=[string], useCustomSerializer=[boolean], pretty=[boolean])
Converts a BoxLang variable into a JSON (JavaScript Object Notation) string according to the specified options.
## Query Format Options
The `queryFormat` argument determines how queries are serialized:
* `row` or `false`: Serializes the query as a top-level struct with two keys: `columns` (an array of column names) and `data` (an array of arrays representing each row's data).
* `column` or `true`: Serializes the query as a top-level struct with three keys: `rowCount` (the number of rows), `columns` (an array of column names), and `data` (a struct where each key is a column name and the value is an array of values for that column).
* `struct`: Serializes the query as an array of structs, where each struct represents a row of data.
## Usage
```
// Convert a query to JSON
myQuery = ...;
json = jsonSerialize( myQuery, queryFormat="row" );
// Convert a list to JSON
myList = "foo,bar,baz";
jsonList = jsonSerialize( myList );
```
### Method Signature
```
listToJSON(queryFormat=[string], useSecureJSONPrefix=[string], useCustomSerializer=[boolean], pretty=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `queryFormat` | `string` | `false` | If the variable is a query, specifies whether to serialize the query by rows or by columns. Valid values are:
row same as false, column same as true, or struct. Defaults to row.
| |
| `useSecureJSONPrefix` | `string` | `false` | If true, the JSON string is prefixed with a secure JSON prefix. (Not implemented yet) | `false` |
| `useCustomSerializer` | `boolean` | `false` | If true, the JSON string is serialized using a custom serializer. (Not implemented yet) | |
| `pretty` | `boolean` | `false` | If true, the JSON string is formatted with indentation and line breaks for readability. Defaults to false. | `false` |
listToSet(type=[string], delimiter=[string])
Convert a collection into a Set, deduplicating automatically.
Accepts an Array, a list-delimited String, an existing Set, a QueryColumn, an XML node, a bounded Range, or any value castable to a Set. When the value is already of the requested variant it is returned as-is; otherwise a new Set of the specified variant is created and populated.
### Method Signature
```
listToSet(type=[string], delimiter=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `type` | `string` | `false` | The backing variant: "default" / "hash" (HashSet), "linked" / "ordered" (LinkedHashSet),
or "sorted" / "tree" (TreeSet). When omitted, the caster defaults to LINKED for ordered
collections like Arrays.
| |
| `delimiter` | `string` | `false` | When `value` is a String, the list delimiter to split on. Defaults to `","`. | `,` |
listTrim(delimiter=[string], multiCharacterDelimiter=[boolean])
Compacts a list by removing empty items from the start and end of the list
### Method Signature
```
listTrim(delimiter=[string], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ------------------------------------------------ | ------- |
| `delimiter` | `string` | `false` | string the list delimiter | `,` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listValueCount(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
returns a count of the number of occurrences of a value in a list
### Method Signature
```
listValueCount(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ------------------------------------------------ | ------- |
| `value` | `string` | `true` | The value to locale | |
| `delimiter` | `string` | `false` | The list delimiter(s) | `,` |
| `includeEmptyFields` | `boolean` | `false` | Whether to include empty fields in the search | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
listValueCountNoCase(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
returns a count of the number of occurrences of a value in a list
### Method Signature
```
listValueCountNoCase(value=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ------------------------------------------------ | ------- |
| `value` | `string` | `true` | The value to locale | |
| `delimiter` | `string` | `false` | The list delimiter(s) | `,` |
| `includeEmptyFields` | `boolean` | `false` | Whether to include empty fields in the search | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | boolean whether the delimiter is multi-character | `false` |
lJustify(length=[integer])
Justifies characters in a string of a specified length, either left or right.
### Method Signature
```
lJustify(length=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | --------------------------------------------- | ------- |
| `length` | `integer` | `true` | The specified length of the resulting string. | |
lTrim(chars=[string])
Trim leading whitespace from a string.
If chars is provided, each character in the string is treated as a character to trim instead of whitespace.
### Method Signature
```
lTrim(chars=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | -------- | -------- | --------------------------------------------------------------------------------- | ------- |
| `chars` | `string` | `false` | An optional string of characters to trim. Each character is treated individually. | |
mid(start=[integer], count=[integer])
Extract a substring from a string
### Method Signature
```
mid(start=[integer], count=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | ------------------------------------------------ | ------- |
| `start` | `integer` | `true` | The position of the first character to retrieve. | |
| `count` | `integer` | `false` | The number of characters to retrieve. | |
millisecond(timezone=[string], locale=[string])
Returns the millisecond of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
millisecond(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
minute(timezone=[string], locale=[string])
Returns the minute of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
minute(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
month(timezone=[string], locale=[string])
Returns the numeric month of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
month(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
monthAsString(timezone=[string], locale=[string])
Returns the full month name of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
monthAsString(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
monthShortAsString(timezone=[string], locale=[string])
Returns the short month name of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
monthShortAsString(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
nanosecond(timezone=[string], locale=[string])
Returns the nanosecond of adate object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
nanosecond(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
offset(timezone=[string], locale=[string])
Returns the timezone offset of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
offset(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
paragraphFormat()
Replaces characters in a string: Single newline characters (CR/LF sequences) with spaces and double newline characters with HTML paragraph tags
### Method Signature
```
paragraphFormat()
```
### Arguments
This function does not accept any arguments
parseDateTime(format=[string], timezone=[string], locale=[string])
Parses a datetime string or object
### Method Signature
```
parseDateTime(format=[string], timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------ | ------- |
| `format` | `string` | `false` | the format mask to use in parsing | |
| `timezone` | `string` | `false` | the timezone to apply to the parsed datetime | |
| `locale` | `string` | `false` | optional ISO locale string ( e.g. en-US, en\_US, es-SA, es\_ES, ru-RU, etc ) used to parse localized formats | |
pascalCase()
Convert a string to pascal case
### Method Signature
```
pascalCase()
```
### Arguments
This function does not accept any arguments
quarter(timezone=[string], locale=[string])
Returns the quarter of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
quarter(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
reFind(reg_expression=[string], start=[integer], returnSubExpressions=[boolean], scope=[string])
Uses a regular expression (RE) to search a string for a pattern, starting from a specified position.
The search is case-sensitive. It will return numeric if returnsubexpressions is false and a struct of arrays named "len", "match" and "pos" when returnsubexpressions is true.
### Method Signature
```
reFind(reg_expression=[string], start=[integer], returnSubExpressions=[boolean], scope=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `reg_expression` | `string` | `true` | The regular expression to search for | |
| `start` | `integer` | `false` | The position from which to start searching in the string. Default is 1. | `1` |
| `returnSubExpressions` | `boolean` | `false` | True: if the regular expression is found, the first array element contains the length and position, respectively, of
the first match. If the regular expression contains parentheses that group subexpressions, each subsequent array
element contains the length and position, respectively, of the first occurrence of each group. If the regular
expression is not found, the arrays each contain one element with the value 0. False: the function returns the
position in the string where the match begins. Default.
| `false` |
| `scope` | `string` | `false` | "one": returns the first value that matches the regex. "all": returns all values that match the regex. | `one` |
reFindNoCase(reg_expression=[string], start=[integer], returnSubExpressions=[boolean], scope=[string])
Uses a regular expression (RE) to search a string for a pattern, starting from a specified position.
The search is case-sensitive. It will return numeric if returnsubexpressions is false and a struct of arrays named "len", "match" and "pos" when returnsubexpressions is true.
### Method Signature
```
reFindNoCase(reg_expression=[string], start=[integer], returnSubExpressions=[boolean], scope=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `reg_expression` | `string` | `true` | The regular expression to search for | |
| `start` | `integer` | `false` | The position from which to start searching in the string. Default is 1. | `1` |
| `returnSubExpressions` | `boolean` | `false` | True: if the regular expression is found, the first array element contains the length and position, respectively, of
the first match. If the regular expression contains parentheses that group subexpressions, each subsequent array
element contains the length and position, respectively, of the first occurrence of each group. If the regular
expression is not found, the arrays each contain one element with the value 0. False: the function returns the
position in the string where the match begins. Default.
| `false` |
| `scope` | `string` | `false` | "one": returns the first value that matches the regex. "all": returns all values that match the regex. | `one` |
reMatch(reg_expression=[string])
Uses a regular expression (RE) to search a string for a pattern.
### Method Signature
```
reMatch(reg_expression=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------------- | -------- | -------- | ------------------------------------ | ------- |
| `reg_expression` | `string` | `true` | The regular expression to search for | |
reMatchNoCase(reg_expression=[string])
Uses a regular expression (RE) to search a string for a pattern.
### Method Signature
```
reMatchNoCase(reg_expression=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------------- | -------- | -------- | ------------------------------------ | ------- |
| `reg_expression` | `string` | `true` | The regular expression to search for | |
removeChars(start=[integer], count=[integer])
Removes characters from a string.
### Method Signature
```
removeChars(start=[integer], count=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | -------------------------------------------------------------- | ------- |
| `start` | `integer` | `true` | The one-based index position of the first character to remove. | |
| `count` | `integer` | `true` | The number of characters to remove. | |
replace(substring1=[string], obj=[any], scope=[string])
Replaces occurrences of substring1 in a string with obj, in a specified scope.
The search is case-sensitive. Function returns original string with replacements made
### Method Signature
```
replace(substring1=[string], obj=[any], scope=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------ | -------- | -------- | ------------------------------------------------------- | ------- |
| `substring1` | `string` | `true` | The substring to search for | |
| `obj` | `any` | `true` | The string to replace substring1 with | |
| `scope` | `string` | `true` | The scope to search in. Valid values are "one" or "all" | `one` |
replaceList(list1=[string], list2=[string], delimiter_list1=[string], delimiter_list2=[string], includeEmptyFields=[boolean])
Replaces occurrences of the elements from a delimited list, in a string with corresponding elements from another delimited list.
### Method Signature
```
replaceList(list1=[string], list2=[string], delimiter_list1=[string], delimiter_list2=[string], includeEmptyFields=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------------------- | --------- | -------- | --------------------------------------------------- | ------- |
| `list1` | `string` | `true` | The first delimited list of search values | |
| `list2` | `string` | `true` | The second delimited list of replacement values | |
| `delimiter_list1` | `string` | `false` | The delimiters for list 1 | `,` |
| `delimiter_list2` | `string` | `false` | The delimiters for list 2 | `,` |
| `includeEmptyFields` | `boolean` | `false` | Whether to include empty fields in the final result | `false` |
replaceListNoCase(list1=[string], list2=[string], delimiter_list1=[string], delimiter_list2=[string], includeEmptyFields=[boolean])
Replaces occurrences of the elements from a delimited list, in a string with corresponding elements from another delimited list.
### Method Signature
```
replaceListNoCase(list1=[string], list2=[string], delimiter_list1=[string], delimiter_list2=[string], includeEmptyFields=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------------------- | --------- | -------- | --------------------------------------------------- | ------- |
| `list1` | `string` | `true` | The first delimited list of search values | |
| `list2` | `string` | `true` | The second delimited list of replacement values | |
| `delimiter_list1` | `string` | `false` | The delimiters for list 1 | `,` |
| `delimiter_list2` | `string` | `false` | The delimiters for list 2 | `,` |
| `includeEmptyFields` | `boolean` | `false` | Whether to include empty fields in the final result | `false` |
replaceNoCase(substring1=[string], obj=[any], scope=[string], start=[string])
Replaces occurrences of substring1 in a string with obj, in a specified scope.
The search is case-sensitive. Function returns original string with replacements made
### Method Signature
```
replaceNoCase(substring1=[string], obj=[any], scope=[string], start=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------ | -------- | -------- | ------------------------------------- | ------- |
| `substring1` | `string` | `true` | The substring to search for | |
| `obj` | `any` | `true` | The string to replace substring1 with | |
| `scope` | `string` | `true` | The scope to search in | `one` |
| `start` | `string` | `false` | | `1` |
reReplace(regex=[string], substring=[string], scope=[string])
Uses a regular expression (regex) to search a string for a string pattern and replace it with another.
The search is case-sensitive.
### Method Signature
```
reReplace(regex=[string], substring=[string], scope=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | -------- | -------- | ------------------------------------ | ------- |
| `regex` | `string` | `true` | The regular expression to search for | |
| `substring` | `string` | `true` | The string to replace regex with | |
| `scope` | `string` | `true` | The scope to search in (one, all) | `one` |
reReplaceNoCase(regex=[string], substring=[string], scope=[string])
Uses a regular expression (regex) to search a string for a string pattern and replace it with another.
The search is case-sensitive.
### Method Signature
```
reReplaceNoCase(regex=[string], substring=[string], scope=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | -------- | -------- | ------------------------------------ | ------- |
| `regex` | `string` | `true` | The regular expression to search for | |
| `substring` | `string` | `true` | The string to replace regex with | |
| `scope` | `string` | `true` | The scope to search in (one, all) | `one` |
reverse()
Reverse the order of characters in a string
### Method Signature
```
reverse()
```
### Arguments
This function does not accept any arguments
right(count=[integer])
Extract the rightmost count characters from a string
### Method Signature
```
right(count=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | ------------------------------------- | ------- |
| `count` | `integer` | `true` | The number of characters to retrieve. | |
rJustify(length=[integer])
Justifies characters in a string of a specified length, either left or right.
### Method Signature
```
rJustify(length=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | --------------------------------------------- | ------- |
| `length` | `integer` | `true` | The specified length of the resulting string. | |
rTrim(chars=[string])
Trim trailing whitespace from a string.
If chars is provided, each character in the string is treated as a character to trim instead of whitespace.
### Method Signature
```
rTrim(chars=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | -------- | -------- | --------------------------------------------------------------------------------- | ------- |
| `chars` | `string` | `false` | An optional string of characters to trim. Each character is treated individually. | |
second(timezone=[string], locale=[string])
Returns the second of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
second(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
slugify(maxLength=[integer], allow=[string])
Slugify a string for URL safety
### Method Signature
```
slugify(maxLength=[integer], allow=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | --------- | -------- | ------------------------------------------------------------------------------- | ------- |
| `maxLength` | `integer` | `false` | The maximum number of chracters to allow, 0 is all | `0` |
| `allow` | `string` | `false` | A regex safe list of additional characters to allow. The default is `[^a-z0-9]` | |
snakeCase()
Convert a string to snake case
### Method Signature
```
snakeCase()
```
### Arguments
This function does not accept any arguments
spanExcluding(set=[string])
Get characters from a string, from the beginning to a character that is in a specified set of characters.
The search is case-sensitive.
### Method Signature
```
spanExcluding(set=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | -------- | -------- | ---------------------------------------------- | ------- |
| `set` | `string` | `true` | The set of chracters to exclude from the span. | |
spanIncluding(set=[string])
Gets characters from a string, from the beginning to a character that is NOT in a specified set of characters.
The search is case-sensitive.
### Method Signature
```
spanIncluding(set=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | -------- | -------- | ---------------------------------------------- | ------- |
| `set` | `string` | `true` | The set of chracters to exclude from the span. | |
sQLPrettify()
Prettify a SQL string
### Method Signature
```
sQLPrettify()
```
### Arguments
This function does not accept any arguments
startsWith(substring=[string])
Determines whether a string starts with a specified prefix.
### Method Signature
```
startsWith(substring=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | -------- | -------- | ------------------------ | ------- |
| `substring` | `string` | `true` | The prefix to check for. | |
startsWithNoCase(substring=[string])
Determines whether a string starts with a specified prefix, case-insensitive.
### Method Signature
```
startsWithNoCase(substring=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | -------- | -------- | ------------------------ | ------- |
| `substring` | `string` | `true` | The prefix to check for. | |
stringReduceRight(callback=[function:BiFunction], initialValue=[any], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
Run the provided udf over a reversed string to reduce the values to a single output
### Method Signature
```
stringReduceRight(callback=[function:BiFunction], initialValue=[any], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:BiFunction` | `true` | The function to invoke for each item. The function will be passed 3 arguments: the value, the index, the array. | |
| `initialValue` | `any` | `false` | The initial value of the reduction | |
| `delimiter` | `string` | `false` | | `,` |
| `includeEmptyFields` | `boolean` | `false` | | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | | `false` |
stringSome(callback=[function:Predicate], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[integer], virtual=[boolean])
Tests whether any item in a string meets the specified callback
### Method Signature
```
stringSome(callback=[function:Predicate], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], parallel=[boolean], maxThreads=[integer], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | -------------------- | -------- | ----------- | ------- |
| `callback` | `function:Predicate` | `true` | | |
| `delimiter` | `string` | `false` | | `,` |
| `includeEmptyFields` | `boolean` | `false` | | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | | `false` |
| `parallel` | `boolean` | `false` | | `false` |
| `maxThreads` | `integer` | `false` | | |
| `virtual` | `boolean` | `false` | | `false` |
stringSort(sortType=[any], sortOrder=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], localeSensitive=[boolean], callback=[any])
Sorts a string and returns the result
### Method Signature
```
stringSort(sortType=[any], sortOrder=[string], delimiter=[string], includeEmptyFields=[boolean], multiCharacterDelimiter=[boolean], localeSensitive=[boolean], callback=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------------------- | --------- | -------- | ----------- | ------- |
| `sortType` | `any` | `false` | | |
| `sortOrder` | `string` | `false` | | `asc` |
| `delimiter` | `string` | `false` | | `,` |
| `includeEmptyFields` | `boolean` | `false` | | `false` |
| `multiCharacterDelimiter` | `boolean` | `false` | | `false` |
| `localeSensitive` | `boolean` | `false` | | `false` |
| `callback` | `any` | `false` | | |
stripCR()
Deletes return characters from a string.
### Method Signature
```
stripCR()
```
### Arguments
This function does not accept any arguments
timeFormat(mask=[string], timezone=[string], locale=[string])
Formats a datetime, date or time
### Method Signature
```
timeFormat(mask=[string], timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `mask` | `string` | `false` | Optional format mask, or common mask. If an explicit mask is used, it should use the mask characters specified in the
java.time.format.DateTimeFormatter class.
If a common mask is used, the following are supported:
- short: equivalent to "M/d/y h:mm tt"
- medium: equivalent to "MMM d, yyyy h🇲🇲ss tt"
- long: medium followed by three-letter time zone; i.e. "MMMM d, yyyy h🇲🇲ss tt zzz"
- full: equivalent to "dddd, MMMM d, yyyy H🇲🇲ss tt zz"
- ISO8601/ISO: equivalent to "yyyy-MM-dd'T'HH🇲🇲ssXXX"
- epoch: Total seconds of a given date (Example:1567517664)
- epochms: Total milliseconds of a given date (Example:1567517664000)
| |
| `timezone` | `string` | `false` | Optional specific timezone to apply to the date ( if not present in the date string ) | |
| `locale` | `string` | `false` | Optional ISO locale string which will be used to localize the resulting date/time string | |
timezone(timezone=[string], locale=[string])
Provides the BIF and member functions for all time unit request with no arguments
### Method Signature
```
timezone(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
to(encoding=[string])
Converts a value to a string.
### Method Signature
```
to(encoding=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | ---------------------------------------------------------------------------- | ------- |
| `encoding` | `string` | `false` | The character encoding (character set) of the string, used with binary data. | |
toAST(filepath=[string], returnType=[string], sourceType=[string])
Generates the Abstract Syntax Tree (AST) for BoxLang source code or a file.
The AST represents the syntactic structure of the code and can be used for code analysis, transformation, or generation.
**Usage Examples:**
```
// Parse source code and return as struct (default)
ast = boxAST( source = "x = 1 + 2" );
println( ast.ASTType ); // Outputs: BoxAssignment
// Parse source code and return as JSON
json = boxAST( source = "function add(a, b) { return a + b; }", returnType = "json" );
println( json ); // Outputs: JSON representation of the AST
// Parse source code and return as text
text = boxAST( source = "if (x > 5) { println('yes'); }", returnType = "text" );
println( text ); // Outputs: Human-readable text representation
// Parse a file
ast = boxAST( filepath = "src/MyClass.bx" );
// Use as a member function on a string
source = "a = [1, 2, 3]";
ast = source.toAST(); // Returns AST as struct
ast = source.toAST( returnType = "json" ); // Returns AST as JSON string
// Parse CFML/ColdFusion syntax
ast = boxAST( source = "cfset x = 1", sourceType = "cfscript" );
// Parse template syntax
ast = boxAST( source = "#now()#", sourceType = "template" );
```
The returned AST structure contains nodes with the following key properties:
* **ASTType** - The type of AST node (e.g., BoxAssignment, BoxFunctionDeclaration, BoxClass)
* **ASTPackage** - The package name of the AST node class
* Additional properties specific to each node type (e.g., name, value, children, etc.)
### Method Signature
```
toAST(filepath=[string], returnType=[string], sourceType=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `filepath` | `string` | `false` | The path to a BoxLang file to parse. Either source or filepath must be provided.
Can be relative (to the current working directory) or absolute.
| |
| `returnType` | `string` | `false` | The format of the returned AST. Valid values are "struct" (default), "json", or "text".
- struct - Returns a nested structure (Map) representing the AST hierarchy
- json - Returns a JSON string representation of the AST
- text - Returns a human-readable text representation of the AST
| `struct` |
| `sourceType` | `string` | `false` | The type of source code being parsed. Valid values are "script" (default), "template", "cfscript", or "cftemplate".
- script - BoxLang script syntax (BOXSCRIPT)
- template - BoxLang template syntax (BOXTEMPLATE)
- cfscript - ColdFusion script syntax (CFSCRIPT)
- cftemplate - ColdFusion template syntax (CFTEMPLATE)
| `script` |
toBase64(encoding=[string])
Calculates the Base64 representation of a string or binary object.
The Base64 format uses printable characters, allowing binary data to be sent in forms and e-mail, and stored in a database or file.
### Method Signature
```
toBase64(encoding=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | ---------------------------------------------------------------------------- | ------- |
| `encoding` | `string` | `false` | The character encoding (character set) of the string, used with binary data. | `UTF-8` |
toBinary()
Calculates the binary representation of Base64-encoded data.
### Method Signature
```
toBinary()
```
### Arguments
This function does not accept any arguments
toDateTime(format=[string], timezone=[string], locale=[string])
Parses a datetime string or object
### Method Signature
```
toDateTime(format=[string], timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------ | ------- |
| `format` | `string` | `false` | the format mask to use in parsing | |
| `timezone` | `string` | `false` | the timezone to apply to the parsed datetime | |
| `locale` | `string` | `false` | optional ISO locale string ( e.g. en-US, en\_US, es-SA, es\_ES, ru-RU, etc ) used to parse localized formats | |
toJSON(queryFormat=[string], useSecureJSONPrefix=[string], useCustomSerializer=[boolean], pretty=[boolean])
Converts a BoxLang variable into a JSON (JavaScript Object Notation) string according to the specified options.
## Query Format Options
The `queryFormat` argument determines how queries are serialized:
* `row` or `false`: Serializes the query as a top-level struct with two keys: `columns` (an array of column names) and `data` (an array of arrays representing each row's data).
* `column` or `true`: Serializes the query as a top-level struct with three keys: `rowCount` (the number of rows), `columns` (an array of column names), and `data` (a struct where each key is a column name and the value is an array of values for that column).
* `struct`: Serializes the query as an array of structs, where each struct represents a row of data.
## Usage
```
// Convert a query to JSON
myQuery = ...;
json = jsonSerialize( myQuery, queryFormat="row" );
// Convert a list to JSON
myList = "foo,bar,baz";
jsonList = jsonSerialize( myList );
```
### Method Signature
```
toJSON(queryFormat=[string], useSecureJSONPrefix=[string], useCustomSerializer=[boolean], pretty=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `queryFormat` | `string` | `false` | If the variable is a query, specifies whether to serialize the query by rows or by columns. Valid values are:
row same as false, column same as true, or struct. Defaults to row.
| |
| `useSecureJSONPrefix` | `string` | `false` | If true, the JSON string is prefixed with a secure JSON prefix. (Not implemented yet) | `false` |
| `useCustomSerializer` | `boolean` | `false` | If true, the JSON string is serialized using a custom serializer. (Not implemented yet) | |
| `pretty` | `boolean` | `false` | If true, the JSON string is formatted with indentation and line breaks for readability. Defaults to false. | `false` |
trim(chars=[string])
Trim whitespace from the beginning and end of a string.
If chars is provided, each character in the string is treated as a character to trim instead of whitespace.
### Method Signature
```
trim(chars=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | -------- | -------- | --------------------------------------------------------------------------------- | ------- |
| `chars` | `string` | `false` | An optional string of characters to trim. Each character is treated individually. | |
trueFalseFormat()
Returns the value formatted as a boolean string
### Method Signature
```
trueFalseFormat()
```
### Arguments
This function does not accept any arguments
uCase()
Uppercase a string
### Method Signature
```
uCase()
```
### Arguments
This function does not accept any arguments
uCFirst(doAll=[boolean], doLowerIfAllUppercase=[boolean])
Transform the first letter of a string to uppercase or the first letter of each word, and optionally lowercase uppercase characters.
### Method Signature
```
uCFirst(doAll=[boolean], doLowerIfAllUppercase=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------------------- | --------- | -------- | --------------------------------------------------------------------------- | ------- |
| `doAll` | `boolean` | `false` | Boolean flag indicating whether to transform the first letter of each word. | `false` |
| `doLowerIfAllUppercase` | `boolean` | `false` | Boolean flag indicating whether to lowercase uppercase characters. | `false` |
uRLEncodedFormat()
Generates a URL-encoded string.
For example, it replaces spaces with `%20`, and non-alphanumeric characters with equivalent hexadecimal escape sequences. Passes arbitrary strings within a URL.
### Method Signature
```
uRLEncodedFormat()
```
### Arguments
This function does not accept any arguments
val()
Converts numeric characters and the first period found that occur at the beginning of a string to a number.
A period not accompianied by at least one numeric digit will be ignored. If no numeric digits are found at the start of the string, zero will be returned.
### Method Signature
```
val()
```
### Arguments
This function does not accept any arguments
week(timezone=[string], locale=[string])
Returns the numeric week within a year of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
week(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
wrap(limit=[integer], strip=[boolean])
Wraps a string at the specified limit, breaking at the last space within the limit.
### Method Signature
```
wrap(limit=[integer], strip=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | --------------------------------------------------------------------------------- | ------- |
| `limit` | `integer` | `true` | The character limit at which to wrap the string. | |
| `strip` | `boolean` | `false` | If true, replaces all line endings with spaces before wrapping. Default is false. | `false` |
xMLFormat(escapeChars=[boolean])
Formats a string so that special XML characters can be used as text in XML
### Method Signature
```
xMLFormat(escapeChars=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `escapeChars` | `boolean` | `false` | whether to escape additional characters restricted as per XML standards. For details, see
.
| `false` |
year(timezone=[string], locale=[string])
Returns the year of a date object. If a string is provided as the argument, an attempt will be made to parse it as a date. If parsing fails, an error will be thrown.
### Method Signature
```
year(timezone=[string], locale=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `timezone` | `string` | `false` | An optional timezone which to convert the date object to | |
| `locale` | `string` | `false` | An optional ISO locale string which will return the specified time unit with a locale-specific result ( e.g. month name, or starting day of week as Monday vs Sunda ) | |
yesNoFormat()
Return Yes/No based on whether the input is true/false
### Method Signature
```
yesNoFormat()
```
### Arguments
This function does not accept any arguments
## Java Methods
> **Use at your own risk:** These are the public methods of the native Java class `java.lang.String`, documented from the JDK 21 javadocs. They are not part of the BoxLang API, are not tested or supported by BoxLang, and may change between Java versions. Java methods with the same name as one of the BoxLang member functions above are not listed, as the BoxLang member function is called instead.
char charAt(int index)
Returns the `char` value at the specified index. An index ranges from `0` to `length() - 1`. The first `char` value of the sequence is at index `0`, the next at index `1`, and so on, as for array indexing.
If the `char` value specified by the index is a surrogate, the surrogate value is returned.
**Parameters:**
* `index` - the index of the `char` value.
**Returns:** the `char` value at the specified index of this string. The first `char` value is at index `0`.
IntStream chars()
Returns a stream of `int` zero-extending the `char` values from this sequence. Any char which maps to a `surrogate code point` is passed through uninterpreted.
**Returns:** an IntStream of char values from this sequence
int codePointAt(int index)
Returns the character (Unicode code point) at the specified index. The index refers to `char` values (Unicode code units) and ranges from `0` to `#length()- 1`.
If the `char` value specified at the given index is in the high-surrogate range, the following index is less than the length of this `String`, and the `char` value at the following index is in the low-surrogate range, then the supplementary code point corresponding to this surrogate pair is returned. Otherwise, the `char` value at the given index is returned.
**Parameters:**
* `index` - the index to the `char` values
**Returns:** the code point value of the character at the `index`
int codePointBefore(int index)
Returns the character (Unicode code point) before the specified index. The index refers to `char` values (Unicode code units) and ranges from `1` to `length`.
If the `char` value at `(index - 1)` is in the low-surrogate range, `(index - 2)` is not negative, and the `char` value at `(index - 2)` is in the high-surrogate range, then the supplementary code point value of the surrogate pair is returned. If the `char` value at `index - 1` is an unpaired low-surrogate or a high-surrogate, the surrogate value is returned.
**Parameters:**
* `index` - the index following the code point that should be returned
**Returns:** the Unicode code point value before the given index.
int codePointCount(int beginIndex, int endIndex)
Returns the number of Unicode code points in the specified text range of this `String`. The text range begins at the specified `beginIndex` and extends to the `char` at index `endIndex - 1`. Thus the length (in `char`s) of the text range is `endIndex-beginIndex`. Unpaired surrogates within the text range count as one code point each.
**Parameters:**
* `beginIndex` - the index to the first `char` of the text range.
* `endIndex` - the index after the last `char` of the text range.
**Returns:** the number of Unicode code points in the specified text range
IntStream codePoints()
Returns a stream of code point values from this sequence. Any surrogate pairs encountered in the sequence are combined as if by `Character.toCodePoint` and the result is passed to the stream. Any other code units, including ordinary BMP characters, unpaired surrogates, and undefined code units, are zero-extended to `int` values which are then passed to the stream.
**Returns:** an IntStream of Unicode code points from this sequence
int compareTo(String anotherString)
Compares two strings lexicographically. The comparison is based on the Unicode value of each character in the strings. The character sequence represented by this `String` object is compared lexicographically to the character sequence represented by the argument string. The result is a negative integer if this `String` object lexicographically precedes the argument string. The result is a positive integer if this `String` object lexicographically follows the argument string. The result is zero if the strings are equal; `compareTo` returns `0` exactly when the `#equals(Object)` method would return `true`.
This is the definition of lexicographic ordering. If two strings are different, then either they have different characters at some index that is a valid index for both strings, or their lengths are different, or both. If they have different characters at one or more index positions, let *k* be the smallest such index; then the string whose character at position *k* has the smaller value, as determined by using the `<` operator, lexicographically precedes the other string. In this case, `compareTo` returns the difference of the two character values at position `k` in the two string -- that is, the value:
> ```
> this.charAt(k)-anotherString.charAt(k)
>
> ```
If there is no index position at which they differ, then the shorter string lexicographically precedes the longer string. In this case, `compareTo` returns the difference of the lengths of the strings -- that is, the value:
> ```
> this.length()-anotherString.length()
>
> ```
For finer-grained String comparison, refer to `java.text.Collator`.
**Parameters:**
* `anotherString` - the `String` to be compared.
**Returns:** the value `0` if the argument string is equal to this string; a value less than `0` if this string is lexicographically less than the string argument; and a value greater than `0` if this string is lexicographically greater than the string argument.
int compareToIgnoreCase(String str)
Compares two strings lexicographically, ignoring case differences. This method returns an integer whose sign is that of calling `compareTo` with case folded versions of the strings where case differences have been eliminated by calling `Character.toLowerCase(Character.toUpperCase(int))` on each Unicode code point.
Note that this method does *not* take locale into account, and will result in an unsatisfactory ordering for certain locales. The `java.text.Collator` class provides locale-sensitive comparison.
**Parameters:**
* `str` - the `String` to be compared.
**Returns:** a negative integer, zero, or a positive integer as the specified String is greater than, equal to, or less than this String, ignoring case considerations.
String concat(String str)
Concatenates the specified string to the end of this string.
If the length of the argument string is `0`, then this `String` object is returned. Otherwise, a `String` object is returned that represents a character sequence that is the concatenation of the character sequence represented by this `String` object and the character sequence represented by the argument string.
Examples:
> ```
> "cares".concat("s") returns "caress"
> "to".concat("get").concat("her") returns "together"
>
> ```
**Parameters:**
* `str` - the `String` that is concatenated to the end of this `String`.
**Returns:** a string that represents the concatenation of this object's characters followed by the string argument's characters.
boolean contains(CharSequence s)
Returns true if and only if this string contains the specified sequence of char values.
**Parameters:**
* `s` - the sequence to search for
**Returns:** true if this string contains `s`, false otherwise
boolean contentEquals(CharSequence cs)
Compares this string to the specified `CharSequence`. The result is `true` if and only if this `String` represents the same sequence of char values as the specified sequence. Note that if the `CharSequence` is a `StringBuffer` then the method synchronizes on it.
For finer-grained String comparison, refer to `java.text.Collator`.
**Parameters:**
* `cs` - The sequence to compare this `String` against
**Returns:** `true` if this `String` represents the same sequence of char values as the specified sequence, `false` otherwise
boolean contentEquals(StringBuffer sb)
Compares this string to the specified `StringBuffer`. The result is `true` if and only if this `String` represents the same sequence of characters as the specified `StringBuffer`. This method synchronizes on the `StringBuffer`.
For finer-grained String comparison, refer to `java.text.Collator`.
**Parameters:**
* `sb` - The `StringBuffer` to compare this `String` against
**Returns:** `true` if this `String` represents the same sequence of characters as the specified `StringBuffer`, `false` otherwise
static String copyValueOf(char[] data)
Equivalent to `#valueOf(char[])`.
**Parameters:**
* `data` - the character array.
**Returns:** a `String` that contains the characters of the character array.
static String copyValueOf(char[] data, int offset, int count)
Equivalent to `int, int)`.
**Parameters:**
* `data` - the character array.
* `offset` - initial offset of the subarray.
* `count` - length of the subarray.
**Returns:** a `String` that contains the characters of the specified subarray of the character array.
Optional<String> describeConstable()
Returns an `Optional` containing the nominal descriptor for this instance, which is the instance itself.
**Returns:** an `Optional` describing the `String` instance
boolean equals(Object anObject)
Compares this string to the specified object. The result is `true` if and only if the argument is not `null` and is a `String` object that represents the same sequence of characters as this object.
For finer-grained String comparison, refer to `java.text.Collator`.
**Parameters:**
* `anObject` - The object to compare this `String` against
**Returns:** `true` if the given object represents a `String` equivalent to this string, `false` otherwise
boolean equalsIgnoreCase(String anotherString)
Compares this `String` to another `String`, ignoring case considerations. Two strings are considered equal ignoring case if they are of the same length and corresponding Unicode code points in the two strings are equal ignoring case.
Two Unicode code points are considered the same ignoring case if at least one of the following is true:
* The two Unicode code points are the same (as compared by the `==` operator)
* Calling `Character.toLowerCase(Character.toUpperCase(int))` on each Unicode code point produces the same result
Note that this method does *not* take locale into account, and will result in unsatisfactory results for certain locales. The `java.text.Collator` class provides locale-sensitive comparison.
**Parameters:**
* `anotherString` - The `String` to compare this `String` against
**Returns:** `true` if the argument is not `null` and it represents an equivalent `String` ignoring case; `false` otherwise
static String format(Locale l, String format, Object[] args)
Returns a formatted string using the specified locale, format string, and arguments.
**Parameters:**
* `l` - The `locale` to apply during formatting. If `l` is `null` then no localization is applied.
* `format` - A format string
* `args` - Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The number of arguments is variable and may be zero. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by *The Java Virtual Machine Specification*. The behaviour on a `null` argument depends on the conversion.
**Returns:** A formatted string
static String format(String format, Object[] args)
Returns a formatted string using the specified format string and arguments.
The locale always used is the one returned by `Locale.getDefault(Locale.Category)` with `FORMAT` category specified.
**Parameters:**
* `format` - A format string
* `args` - Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The number of arguments is variable and may be zero. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by *The Java Virtual Machine Specification*. The behaviour on a `null` argument depends on the conversion.
**Returns:** A formatted string
String formatted(Object[] args)
Formats using this string as the format string, and the supplied arguments.
**Parameters:**
* `args` - Arguments referenced by the format specifiers in this string.
**Returns:** A formatted string
byte[] getBytes()
Encodes this `String` into a sequence of bytes using the `default charset`, storing the result into a new byte array.
The behavior of this method when this string cannot be encoded in the default charset is unspecified. The `java.nio.charset.CharsetEncoder` class should be used when more control over the encoding process is required.
**Returns:** The resultant byte array
byte[] getBytes(Charset charset)
Encodes this `String` into a sequence of bytes using the given `charset`, storing the result into a new byte array.
This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement byte array. The `java.nio.charset.CharsetEncoder` class should be used when more control over the encoding process is required.
**Parameters:**
* `charset` - The `java.nio.charset.Charset` to be used to encode the `String`
**Returns:** The resultant byte array
byte[] getBytes(String charsetName)
Encodes this `String` into a sequence of bytes using the named charset, storing the result into a new byte array.
The behavior of this method when this string cannot be encoded in the given charset is unspecified. The `java.nio.charset.CharsetEncoder` class should be used when more control over the encoding process is required.
**Parameters:**
* `charsetName` - The name of a supported `charset`
**Returns:** The resultant byte array
void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)
Copies characters from this string into the destination character array.
The first character to be copied is at index `srcBegin`; the last character to be copied is at index `srcEnd-1` (thus the total number of characters to be copied is `srcEnd-srcBegin`). The characters are copied into the subarray of `dst` starting at index `dstBegin` and ending at index:
> ```
> dstBegin + (srcEnd-srcBegin) - 1
>
> ```
**Parameters:**
* `srcBegin` - index of the first character in the string to copy.
* `srcEnd` - index after the last character in the string to copy.
* `dst` - the destination array.
* `dstBegin` - the start offset in the destination array.
int hashCode()
Returns a hash code for this string. The hash code for a `String` object is computed as
> ```
> s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1]
>
> ```
using `int` arithmetic, where `s[i]` is the *i*th character of the string, `n` is the length of the string, and `^` indicates exponentiation. (The hash value of the empty string is zero.)
**Returns:** a hash code value for this object.
String indent(int n)
Adjusts the indentation of each line of this string based on the value of `n`, and normalizes line termination characters.
This string is conceptually separated into lines using `String#lines()`. Each line is then adjusted as described below and then suffixed with a line feed `"\n"` (U+000A). The resulting lines are then concatenated and returned.
If `n > 0` then `n` spaces (U+0020) are inserted at the beginning of each line.
If `n < 0` then up to `n` `white space characters` are removed from the beginning of each line. If a given line does not contain sufficient white space then all leading `white space characters` are removed. Each white space character is treated as a single character. In particular, the tab character `"\t"` (U+0009) is considered a single character; it is not expanded.
If `n == 0` then the line remains unchanged. However, line terminators are still normalized.
**Parameters:**
* `n` - number of leading `white space characters` to add or remove
**Returns:** string with indentation adjusted and line endings normalized
int indexOf(String str)
Returns the index within this string of the first occurrence of the specified substring.
The returned index is the smallest value `k` for which:
```
this.startsWith(str, k)
```
If no such value of `k` exists, then `-1` is returned.
**Parameters:**
* `str` - the substring to search for.
**Returns:** the index of the first occurrence of the specified substring, or `-1` if there is no such occurrence.
int indexOf(String str, int beginIndex, int endIndex)
Returns the index of the first occurrence of the specified substring within the specified index range of `this` string.
This method returns the same result as the one of the invocation
```
s.substring(beginIndex, endIndex).indexOf(str) + beginIndex
```
if the index returned by `#indexOf(String)` is non-negative, and returns -1 otherwise. (No substring is instantiated, though.)
**Parameters:**
* `str` - the substring to search for.
* `beginIndex` - the index to start the search from (included).
* `endIndex` - the index to stop the search at (excluded).
**Returns:** the index of the first occurrence of the specified substring within the specified index range, or `-1` if there is no such occurrence.
int indexOf(String str, int fromIndex)
Returns the index within this string of the first occurrence of the specified substring, starting at the specified index.
The returned index is the smallest value `k` for which:
```
k >= Math.min(fromIndex, this.length()) &&
this.startsWith(str, k)
```
If no such value of `k` exists, then `-1` is returned.
**Parameters:**
* `str` - the substring to search for.
* `fromIndex` - the index from which to start the search.
**Returns:** the index of the first occurrence of the specified substring, starting at the specified index, or `-1` if there is no such occurrence.
int indexOf(int ch)
Returns the index within this string of the first occurrence of the specified character. If a character with value `ch` occurs in the character sequence represented by this `String` object, then the index (in Unicode code units) of the first such occurrence is returned. For values of `ch` in the range from 0 to 0xFFFF (inclusive), this is the smallest value *k* such that:
> ```
> this.charAt(k) == ch
>
> ```
is true. For other values of `ch`, it is the smallest value *k* such that:
> ```
> this.codePointAt(k) == ch
>
> ```
is true. In either case, if no such character occurs in this string, then `-1` is returned.
**Parameters:**
* `ch` - a character (Unicode code point).
**Returns:** the index of the first occurrence of the character in the character sequence represented by this object, or `-1` if the character does not occur.
int indexOf(int ch, int beginIndex, int endIndex)
Returns the index within this string of the first occurrence of the specified character, starting the search at `beginIndex` and stopping before `endIndex`.
If a character with value `ch` occurs in the character sequence represented by this `String` object at an index no smaller than `beginIndex` but smaller than `endIndex`, then the index of the first such occurrence is returned. For values of `ch` in the range from 0 to 0xFFFF (inclusive), this is the smallest value *k* such that:
> ```
> (this.charAt(k) == ch) && (beginIndex <= k < endIndex)
>
> ```
is true. For other values of `ch`, it is the smallest value *k* such that:
> ```
> (this.codePointAt(k) == ch) && (beginIndex <= k < endIndex)
>
> ```
is true. In either case, if no such character occurs in this string at or after position `beginIndex` and before position `endIndex`, then `-1` is returned.
All indices are specified in `char` values (Unicode code units).
**Parameters:**
* `ch` - a character (Unicode code point).
* `beginIndex` - the index to start the search from (included).
* `endIndex` - the index to stop the search at (excluded).
**Returns:** the index of the first occurrence of the character in the character sequence represented by this object that is greater than or equal to `beginIndex` and less than `endIndex`, or `-1` if the character does not occur.
int indexOf(int ch, int fromIndex)
Returns the index within this string of the first occurrence of the specified character, starting the search at the specified index.
If a character with value `ch` occurs in the character sequence represented by this `String` object at an index no smaller than `fromIndex`, then the index of the first such occurrence is returned. For values of `ch` in the range from 0 to 0xFFFF (inclusive), this is the smallest value *k* such that:
> ```
> (this.charAt(k) == ch) && (k >= fromIndex)
>
> ```
is true. For other values of `ch`, it is the smallest value *k* such that:
> ```
> (this.codePointAt(k) == ch) && (k >= fromIndex)
>
> ```
is true. In either case, if no such character occurs in this string at or after position `fromIndex`, then `-1` is returned.
There is no restriction on the value of `fromIndex`. If it is negative, it has the same effect as if it were zero: this entire string may be searched. If it is greater than the length of this string, it has the same effect as if it were equal to the length of this string: `-1` is returned.
All indices are specified in `char` values (Unicode code units).
**Parameters:**
* `ch` - a character (Unicode code point).
* `fromIndex` - the index to start the search from.
**Returns:** the index of the first occurrence of the character in the character sequence represented by this object that is greater than or equal to `fromIndex`, or `-1` if the character does not occur.
String intern()
Returns a canonical representation for the string object.
A pool of strings, initially empty, is maintained privately by the class `String`.
When the intern method is invoked, if the pool already contains a string equal to this `String` object as determined by the `#equals(Object)` method, then the string from the pool is returned. Otherwise, this `String` object is added to the pool and a reference to this `String` object is returned.
It follows that for any two strings `s` and `t`, `s.intern() == t.intern()` is `true` if and only if `s.equals(t)` is `true`.
All literal strings and string-valued constant expressions are interned. String literals are defined in section JLS 3.10.5 of the *The Java Language Specification*.
**Returns:** a string that has the same contents as this string, but is guaranteed to be from a pool of unique strings.
boolean isBlank()
Returns `true` if the string is empty or contains only `white space` codepoints, otherwise `false`.
**Returns:** `true` if the string is empty or contains only `white space` codepoints, otherwise `false`
static String join(CharSequence delimiter, CharSequence[] elements)
Returns a new String composed of copies of the `CharSequence elements` joined together with a copy of the specified `delimiter`.
> For example,
>
> ```
> String message = String.join("-", "Java", "is", "cool");
> // message returned is: "Java-is-cool"
> ```
Note that if an element is null, then `"null"` is added.
**Parameters:**
* `delimiter` - the delimiter that separates each element
* `elements` - the elements to join together.
**Returns:** a new `String` that is composed of the `elements` separated by the `delimiter`
static String join(CharSequence delimiter, Iterable<? extends CharSequence> elements)
Returns a new `String` composed of copies of the `CharSequence elements` joined together with a copy of the specified `delimiter`.
> For example,
>
> List<String> strings = List.of("Java", "is", "cool");
> String message = String.join(" ", strings);
> // message returned is: "Java is cool"
> Set<String> strings = new LinkedHashSet<>(List.of("Java", "is", "very", "cool")); String message = String.join("-", strings); // message returned is: "Java-is-very-cool"</code></pre></blockquote>
> Note that if an individual element is null, then "null" is added.
> Parameters:
>
> delimiter - a sequence of characters that is used to separate each
> of the elements in the resulting String
> elements - an Iterable that will have its elements
> joined together.
>
> Returns: a new String that is composed from the elements
> argument
>
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://boxlang.ortusbooks.com/boxlang-language/reference/types/string.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.