> 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/struct.md).
# struct
This type provides the core map class for Boxlang.
Structs are highly versatile and are used for organizing and managing related data.
Types of Structs in BoxLang: `DEFAULT, CASE_SENSITIVE, LINKED, LINKED_CASE_SENSITIVE, SORTED, WEAK, SOFT`
* DEFAULT: These are the basic structures where each key is associated with a single value. Keys are case-insensitive and can be strings or symbols.
* Nested Structs: Structs can contain other structs as values, allowing for a hierarchical organization of data.
* CASE\_SENSITIVE: By default, BoxLang structs are case-insensitive. However, you can create case-sensitive structs if needed.
* LINKED, LINKED\_CASE\_SENSITIVE (Ordered Structs): This implementation of a Struct maintains keys in the order they were added.
* SORTED: This implementation of a Struct maintains keys in specified sorted order.
* WEAK: This implementation of a Struct uses weak references for keys.
* SOFT: This implementation of a Struct uses a default struct with values wrapped in a SoftReference.
## Struct Methods
append(struct2=[structloose], overwrite=[boolean])
Appends the contents of a second struct to the first struct either with or without overwrite
### Method Signature
```
append(struct2=[structloose], overwrite=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | --------- | -------- | -------------------------------------------------------------------------------------------------------- | ------- |
| `struct2` | `struct` | `true` | The struct containing the values to be appended | |
| `overwrite` | `boolean` | `false` | Default true. Whether to overwrite existing values found
in struct1 from the values in struct2
| `true` |
### Examples
*Append One Struct to Another:*
```java
animals = {
cow: "moo",
pig: "oink"
};
// Show current animals
animals.dump( label ="Current animals" );
// Create a new animal
newAnimal = {
cat: "meow"
};
// Append the newAnimal to animals
animals.append( newAnimal );
animals.dump( label="Updated animals" );
```
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` |
clear()
Clear all items from struct
### Method Signature
```
clear()
```
### Arguments
This function does not accept any arguments
copy()
Creates a shallow copy of a struct.
Copies top-level keys, values, and arrays in the structure by value; copies nested structures by reference.
### Method Signature
```
copy()
```
### Arguments
This function does not accept any arguments
count()
Returns the absolute value of a number
### Method Signature
```
count()
```
### Arguments
This function does not accept any arguments
delete(key=[any])
Deletes a key from a struct
### Method Signature
```
delete(key=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ----------------- | ------- |
| `key` | `any` | `true` | The key to delete | |
duplicate(deep=[boolean])
Duplicates an object - either shallow or deep
### Method Signature
```
duplicate(deep=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | ------------------------------------------------------------------------------------------------- | ------- |
| `deep` | `boolean` | `false` | Whether to deep copy the object or make a shallow copy (e.g. only the top level keys in a struct) | `true` |
each(callback=[function:BiConsumer], parallel=[boolean], maxThreads=[any], ordered=[boolean], virtual=[boolean])
Used to iterate over a struct and run the function closure for each key/value pair.
The function will be passed 3 arguments: the key, the value, and the struct. You can alternatively pass a Java BiConsumer which will only receive the first 2 args (key and value).
This BIF is useful for performing side effects on each item in the struct, such as logging or modifying external state.
## 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
```
each(callback=[function:BiConsumer], parallel=[boolean], maxThreads=[any], ordered=[boolean], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------ | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `callback` | `function:BiConsumer` | `true` | The function to invoke for each item. The function will be passed 3 arguments: the key, the value, the struct. You can alternatively pass a Java BiConsumer which will only receive the first 2 args. | |
| `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.
| |
| `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` |
equals(struct2=[structloose])
Tests equality between two structs
### Method Signature
```
equals(struct2=[structloose])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------- | -------- | -------- | ------------------------------- | ------- |
| `struct2` | `struct` | `true` | The struct to test for equality | |
every(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[any], virtual=[boolean])
Used to iterate over a struct and test whether **every** item meets the test callback.
The function will be passed 3 arguments: the value, the index, and the struct. 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 structs, especially when the test function is computationally expensive or the struct is large.
### Method Signature
```
every(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[any], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------ | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:BiPredicate` | `true` | The function used to test. The function will be passed 3 arguments: the key, the value, the struct. You can alternatively pass a Java BiPredicate which will only receive the first 2 args. | |
| `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 parallel is true and maxThreads is not passed, it will use the common ForkJoinPool.
| |
| `virtual` | `boolean` | `false` | Whether to use a virtual thread for each task when running in parallel. Defaults to false. Ignored if parallel is false. | `false` |
filter(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[any], virtual=[boolean])
Filters a struct and returns a new struct with the values that pass the filter criteria.
This BIF will invoke the callback function for each entry in the struct, passing the key, value, and the struct itself.
* If the callback returns true, the entry will be included in the new struct.
* If the callback returns false, the entry will be excluded from the new struct.
* If the callback requires strict arguments, it will only receive the key and value.
* If the callback does not require strict arguments, it will receive the key, value, and the original struct.
## 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
```
filter(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[any], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------ | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:BiPredicate` | `true` | The function used to filter. The function will be passed 3 arguments: the key, the value, the struct. You can alternatively pass a Java BiPredicate which will only receive the first 2 args. | |
| `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.
| |
| `virtual` | `boolean` | `false` | If true, the function will be invoked using virtual threads. Defaults to false. Ignored if parallel is false. | `false` |
find(key=[any], defaultValue=[any])
Finds and retrieves a top-level key from a string in a struct
### Method Signature
```
find(key=[any], defaultValue=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------------- | ----- | -------- | ----------------------------------------------------------------------- | ------- |
| `key` | `any` | `true` | The key to search | |
| `defaultValue` | `any` | `false` | An optional value to be returned if the struct does not contain the key | |
findKey(key=[any], scope=[string])
Searches a struct for a given key and returns an array of values
### Method Signature
```
findKey(key=[any], scope=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | -------- | -------- | -------------------------------------------------------------------------------- | ------- |
| `key` | `any` | `true` | The key to search for | |
| `scope` | `string` | `false` | Either one (default), which finds the first instance or all to return all values | `one` |
findValue(value=[string], scope=[string])
Searches a struct for a given value and returns an array of results
### Method Signature
```
findValue(value=[string], scope=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | -------- | -------- | -------------------------------------------------------------------------------- | ------- |
| `value` | `string` | `true` | The value to search for | |
| `scope` | `string` | `false` | Either one (default), which finds the first instance or all to return all values | `one` |
getFromPath(path=[string])
Retrieves the value from a struct using a path based expression
### Method Signature
```
getFromPath(path=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | -------- | -------- | ----------------------------------------------------- | ------- |
| `path` | `string` | `true` | The string path to the object requested in the struct | |
getMetadata()
Gets Struct-specific metadata of the requested struct.
### Method Signature
```
getMetadata()
```
### Arguments
This function does not accept any arguments
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` |
insert(key=[any], value=[any], overwrite=[boolean])
Inserts a key/value pair in to a struct - with an optional overwrite argument
### Method Signature
```
insert(key=[any], value=[any], overwrite=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | --------- | -------- | ---------------------------------------------------------------------------- | ------- |
| `key` | `any` | `true` | The struct key | |
| `value` | `any` | `true` | The value to assign for the specified key | |
| `overwrite` | `boolean` | `false` | Whether to overwrite the existing value if the key exists ( default: false ) | `false` |
isCaseSensitive()
Returns whether the give struct is case sensitive
### Method Signature
```
isCaseSensitive()
```
### Arguments
This function does not accept any arguments
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
isOrdered()
Tests whether a struct is ordered ( e.g.
linked )
### Method Signature
```
isOrdered()
```
### Arguments
This function does not accept any arguments
keyArray()
Get keys of a struct as an array
### Method Signature
```
keyArray()
```
### Arguments
This function does not accept any arguments
keyExists(key=[any])
Tests whether a key exists in a struct and returns a boolean value
### Method Signature
```
keyExists(key=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ----------------------------------------------- | ------- |
| `key` | `any` | `true` | The key within the struct to test for existence | |
keyList(delimiter=[string])
Get keys of a struct as a string list
### Method Signature
```
keyList(delimiter=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | -------- | -------- | -------------------------------------------------------------------------------- | ------- |
| `delimiter` | `string` | `false` | The delimiter to use between the keys in the returned list. Defaults to a comma. | `,` |
keySet(type=[string])
Build a Set containing the keys of a Struct.
Key names are extracted as plain Strings via Key.getName(), so the resulting Set always holds String values. The backing variant can be configured; use "linked" to preserve the Struct's iteration order.
### Method Signature
```
keySet(type=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `type` | `string` | `false` | The backing variant: "default" / "hash" (HashSet), "linked" / "ordered" (LinkedHashSet,
preserves Struct iteration order), or "sorted" / "tree" (TreeSet, alphabetical order).
| `default` |
keyTranslate(deep=[boolean], retainKeys=[boolean])
Converts a struct with dot-notated keys in to an unflattened version
### Method Signature
```
keyTranslate(deep=[boolean], retainKeys=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------ | --------- | -------- | --------------------------------------------------------------- | ------- |
| `deep` | `boolean` | `false` | Whether to recurse in to nested keys - default false | `false` |
| `retainKeys` | `boolean` | `false` | Whether to retain the original dot-notated keys - default false | `false` |
len()
Returns the absolute value of a number
### Method Signature
```
len()
```
### Arguments
This function does not accept any arguments
map(callback=[function:BiFunction], parallel=[boolean], maxThreads=[any], virtual=[boolean])
This BIF will iterate over each key-value pair in the struct and invoke the callback function for each item so you can do any operation on the key-value pair and return a new value that will be set in a new struct.
The callback function will be passed the key, the value, and the original struct.
* If the callback requires strict arguments, it will only receive the key and value.
* If the callback does not require strict arguments, it will receive the key, value, and the original struct.
## 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
```
map(callback=[function:BiFunction], parallel=[boolean], maxThreads=[any], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------ | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:BiFunction` | `true` | The function used to produce the right-hand value assignment in the new struct. The function will be passed 3 arguments: the key, the value, the struct. You can alternatively pass a Java BiFunction which will only receive the
first 2 args.
| |
| `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` |
none(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[any], virtual=[boolean])
Used to iterate over a struct and test whether **NONE** item meets the test callback.
This is the opposite of `StructSome`.
The function will be passed 3 arguments: the value, the index, and the struct. 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 structs, especially when the test function is computationally expensive or the struct is large.
### Method Signature
```
none(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[any], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------ | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:BiPredicate` | `true` | The function used to test. The function will be passed 3 arguments: the key, the value, the struct. You can alternatively pass a Java BiPredicate which will only receive the first 2 args. | |
| `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 parallel is true and maxThreads is not passed, it will use the common ForkJoinPool.
| |
| `virtual` | `boolean` | `false` | Whether to use a virtual thread for each task when running in parallel. Defaults to false. Ignored if parallel is false. | `false` |
reduce(callback=[function], initialValue=[any])
Run the provided udf against struct to reduce the values to a single output
### Method Signature
```
reduce(callback=[function], initialValue=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function` | `true` | The function to invoke for each entry in the struct. The function will be passed 4 arguments: the accumulator, they entry key,
the
current index, and the original struct. The function should return the new accumulator value.
| |
| `initialValue` | `any` | `false` | The initial value of the accumulator | |
some(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[any], virtual=[boolean])
Used to iterate over a struct and test whether **ANY** items meet the test callback.
The function will be passed 3 arguments: the key, the value, and the struct. You can alternatively pass a Java BiPredicate which will only receive the first 2 args. 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
```
some(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[any], virtual=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ------------ | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:BiPredicate` | `true` | The function used to test. The function will be passed 3 arguments: the key, the value, the struct. You can alternatively pass a Java BiPredicate which will only receive the first 2 args. | |
| `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 parallel is true and maxThreads is not passed, it will use the common ForkJoinPool.
| |
| `virtual` | `boolean` | `false` | Whether to use a virtual thread for each task when running in parallel. Defaults to false. Ignored if parallel is false. | `false` |
sort(sortType=[any], sortOrder=[string], path=[string], callback=[function:Comparator])
Sorts a struct according to the specified arguments and returns an array of struct keys
### Method Signature
```
sort(sortType=[any], sortOrder=[string], path=[string], callback=[function:Comparator])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | ------- |
| `sortType` | `any` | `false` | An optional sort type to apply to that type - if a callback is given in this position it will be used as that argument | `text` |
| `sortOrder` | `string` | `false` | The sort order applicable to the sortType argument | `asc` |
| `path` | `string` | `false` | An optional key path used to sort by a nested value within each struct entry (e.g. "address.city"). | |
| `callback` | `function:Comparator` | `false` | An optional callback to use as the sorting function. You can alternatively pass a Java Comparator. | |
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` |
toModifiable()
Convert an array, struct, query or set to its Modifiable counterpart.
### Method Signature
```
toModifiable()
```
### Arguments
This function does not accept any arguments
toQueryString(delimiter=[string])
Converts a struct to a query string using the specified delimiter.
The default delimiter is `"&"`
### Method Signature
```
toQueryString(delimiter=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | -------- | -------- | -------------------------------------------------------- | ------- |
| `delimiter` | `string` | `false` | The delimiter to use in the query string. Default is "&" | `&` |
toSorted(sortType=[any], sortOrder=[string], localeSensitive=[any], callback=[function:Comparator])
Converts a struct to a sorted struct - using either a callback comparator or textual directives as the sort option
### Method Signature
```
toSorted(sortType=[any], sortOrder=[string], localeSensitive=[any], callback=[function:Comparator])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------------- | --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | ------- |
| `sortType` | `any` | `false` | An optional sort type to apply to that type - if a callback is given in this position it will be used as that argument | `text` |
| `sortOrder` | `string` | `false` | The sort order applicable to the sortType argument | `asc` |
| `localeSensitive` | `any` | `false` | Sort based on local rules | `false` |
| `callback` | `function:Comparator` | `false` | An optional callback to use as the sorting function. You can alternatively pass a Java Comparator. | |
toUnmodifiable()
Convert an array, struct, query or set to its Unmodifiable counterpart.
### Method Signature
```
toUnmodifiable()
```
### Arguments
This function does not accept any arguments
update(key=[any], value=[any])
Updates or sets a key/value pair in to a struct
### Method Signature
```
update(key=[any], value=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ----------------------------------------- | ------- |
| `key` | `any` | `true` | The struct key | |
| `value` | `any` | `true` | The value to assign for the specified key | |
valueArray()
Returns an array of all values of top level keys in a struct
### Method Signature
```
valueArray()
```
### Arguments
This function does not accept any arguments
valueSet(type=[string])
Build a Set containing the values of a Struct, deduplicating automatically.
The backing variant can be configured; use "linked" to preserve the Struct's value iteration order.
### Method Signature
```
valueSet(type=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `type` | `string` | `false` | The backing variant: "default" / "hash" (HashSet), "linked" / "ordered" (LinkedHashSet,
preserves Struct iteration order), or "sorted" / "tree" (TreeSet).
| `default` |
### Creating structs using the function `structNew`
```java
// Create a default struct ( unordered )
myStruct = structNew();
// Create an ordered struct which will maintain key order of insertion
myStruct = structNew( "ordered" );
// Create a case-sensitive struct which will require key access to use the exact casing
myStruct = structNew( "casesensitive" );
myStruct[ "cat" ] = "pet";
myStruct[ "Cat" ] = "wild";
// Create a sorted struct
myStruct = structNew( "sorted", "textAsc" )
```
### Creating structs using object literal syntax
```java
// Create an empty default struct ( unordered )
myStruct = {};
// Create an empty struct and populate it with values
animals = {
cow: "moo",
pig: "oink"
};
// JavaScript-style key shorthand
sound = "moo";
animal = { sound }; // same as { sound: sound }
// Create an ordered struct which will maintain key order of insertion
// Note that you must provide the ordered struct with data to prevent confusion as to whether it is an array or struct
orderedAnimals = [
cow: "moo",
pig: "oink"
];
```
### Object destructuring assignment
```java
data = { a: 10, b: 20, c: { d: 40, e: 50 }, f: 60 };
// Basic destructuring into the default assignment scope
({ a, b } = data);
// Scoped assignment via explicit rename
({ a: variables.a, b: request.b } = data);
// Defaults, nested destructuring, and rest
({ a, z = 999, c: { d }, ...rest } = data);
```
---
# 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/struct.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.