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

Last updated

Was this helpful?