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.

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 in the struct meets the test.

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])

Used to filter a struct and return a new struct containing the result

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])

Used to map a struct to a new struct of the same type containing the result

Arguments:

Argument	Type	Required	Default
callback	function:BiFunction	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.

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])

Converts a BoxLang variable into a JSON (JavaScript Object Notation) string.

Arguments:

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

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