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.

Examples

Creating structs using the function structNew

// 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( "casesenstive" );
myStruct[ "cat" ] = "pet";
myStruct[ "Cat" ] = "wild";

// Create a sorted struct 
myStruct = structNew( "sorted", "textAsc" )

Creating structs using object literal syntax

// Create an empty default struct ( unordered )
myStruct = {};

// Create an empty struct and populate it with values
animals = {
  cow: "moo",
  pig: "oink"
};

// 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"
];

Struct Methods

append(struct2=[structloose], overwrite=[boolean])

Appends the contents of a second struct to the first struct either with or without overwrite

Arguments:

Argument	Type	Required	Default
struct2	struct	true	null
overwrite	boolean	false	true

Examples:Append One Struct to Another:

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" );

clear()

Clear all items from struct

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.

count()

Returns the absolute value of a number

delete(key=[any])

Deletes a key from a struct

Arguments:

Argument	Type	Required	Default
key	any	true	null

duplicate(deep=[boolean])

Duplicates an object - either shallow or deep

Arguments:

Argument	Type	Required	Default
deep	boolean	false	true

each(callback=[function:BiConsumer], parallel=[boolean], maxThreads=[integer], ordered=[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.

Arguments:

Argument	Type	Required	Default
callback	function:BiConsumer	true	null
parallel	boolean	false	false
maxThreads	integer	false	null
ordered	boolean	false	false

equals(struct2=[structloose])

Tests equality between two structs

Arguments:

Argument	Type	Required	Default
struct2	struct	true	null

every(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[integer])

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.

Arguments:

Argument	Type	Required	Default
callback	function:BiPredicate	true	null
parallel	boolean	false	false
maxThreads	integer	false	null

filter(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[integer])

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.

Arguments:

Argument	Type	Required	Default
callback	function:BiPredicate	true	null
parallel	boolean	false	false
maxThreads	integer	false	null

find(key=[any], defaultValue=[any])

Finds and retrieves a top-level key from a string in a struct

Arguments:

Argument	Type	Required	Default
key	any	true	null
defaultValue	any	false	null

findKey(key=[any], scope=[string])

Searches a struct for a given key and returns an array of values

Arguments:

Argument	Type	Required	Default
key	any	true	null
scope	string	false	one

findValue(value=[string], scope=[string])

Searches a struct for a given value and returns an array of results

Arguments:

Argument	Type	Required	Default
value	string	true	null
scope	string	false	one

getFromPath(path=[string])

Retrieves the value from a struct using a path based expression

Arguments:

Argument	Type	Required	Default
path	string	true	null

getMetadata()

Gets Struct-specific metadata of the requested struct.

hash(algorithm=[string], encoding=[string], numIterations=[integer])

Creates an algorithmic hash of an object

Arguments:

Argument	Type	Required	Default
algorithm	string	false	MD5
encoding	string	false	utf-8
numIterations	integer	false	1

insert(key=[any], value=[any], overwrite=[boolean])

Inserts a key/value pair in to a struct - with an optional overwrite argument

Arguments:

Argument	Type	Required	Default
key	any	true	null
value	any	true	null
overwrite	boolean	false	false

isCaseSensitive()

Returns whether the give struct is case sensitive

isEmpty()

Determine whether a given value is empty.

We check for emptiness of anything that can be casted to: Array, Struct, Query, or String.

isOrdered()

Tests whether a struct is ordered ( e.g.

linked )

keyArray()

Get keys of a struct as an array

keyExists(key=[any])

Tests whether a key exists in a struct and returns a boolean value

Arguments:

Argument	Type	Required	Default
key	any	true	null

keyList(delimiter=[string])

Get keys of a struct as a string list

Arguments:

Argument	Type	Required	Default
delimiter	string	false	,

keyTranslate(deep=[boolean], retainKeys=[boolean])

Converts a struct with dot-notated keys in to an unflattened version

Arguments:

Argument	Type	Required	Default
deep	boolean	false	false
retainKeys	boolean	false	false

len()

Returns the absolute value of a number

map(callback=[function:BiFunction], parallel=[boolean], maxThreads=[integer])

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.

Arguments:

Argument	Type	Required	Default
callback	function:BiFunction	true	null
parallel	boolean	false	false
maxThreads	integer	false	null

none(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[integer])

Used to iterate over a struct and test whether NONE item meets the test callback.

This is the opposite of ,{@link 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.

Arguments:

Argument	Type	Required	Default
callback	function:BiPredicate	true	null
parallel	boolean	false	false
maxThreads	integer	false	null

reduce(callback=[function], initialValue=[any])

Run the provided udf against struct to reduce the values to a single output

Arguments:

Argument	Type	Required	Default
callback	function	true	null
initialValue	any	false	null

some(callback=[function:BiPredicate], parallel=[boolean], maxThreads=[integer])

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. ,

Arguments:

Argument	Type	Required	Default
callback	function:BiPredicate	true	null
parallel	boolean	false	false
maxThreads	integer	false	null

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

Arguments:

Argument	Type	Required	Default
sortType	any	false	text
sortOrder	string	false	asc
path	string	false	null
callback	function:Comparator	false	null

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 );
,

Arguments:

Argument	Type	Required	Default
queryFormat	string	false	row
useSecureJSONPrefix	string	false	false
useCustomSerializer	boolean	false	null
pretty	boolean	false	false

toModifiable()

Convert an array, struct or query to its Modifiable counterpart.

toQueryString(delimiter=[string])

Converts a struct to a query string using the specified delimiter.

, The default delimiter is ,{@code "&"}

Arguments:

Argument	Type	Required	Default
delimiter	string	false	&

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

Arguments:

Argument	Type	Required	Default
sortType	any	false	text
sortOrder	string	false	asc
localeSensitive	any	false	false
callback	function:Comparator	false	null

toUnmodifiable()

Convert an array, struct or query to its Unmodifiable counterpart.

update(key=[any], value=[any])

Updates or sets a key/value pair in to a struct

Arguments:

Argument	Type	Required	Default
key	any	true	null
value	any	true	null

valueArray()

Returns an array of all values of top level keys in a struct

Examples