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
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:
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" );
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.
duplicate(deep=[boolean])
Duplicates an object - either shallow or deep
Arguments:
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:
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:
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:
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:
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:
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:
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:
value
string
true
null
scope
string
false
one
getFromPath(path=[string])
Retrieves the value from a struct using a path based expression
Arguments:
path
string
true
null
hash(algorithm=[string], encoding=[string], numIterations=[integer])
Creates an algorithmic hash of an object
Arguments:
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:
key
any
true
null
value
any
true
null
overwrite
boolean
false
false
isEmpty()
Determine whether a given value is empty.
We check for emptiness of anything that can be casted to: Array, Struct, Query, or String.
keyExists(key=[any])
Tests whether a key exists in a struct and returns a boolean value
Arguments:
key
any
true
null
keyList(delimiter=[string])
Get keys of a struct as a string list
Arguments:
delimiter
string
false
,
keyTranslate(deep=[boolean], retainKeys=[boolean])
Converts a struct with dot-notated keys in to an unflattened version
Arguments:
deep
boolean
false
false
retainKeys
boolean
false
false
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:
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:
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:
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:
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:
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:
queryFormat
string
false
row
useSecureJSONPrefix
string
false
false
useCustomSerializer
boolean
false
null
pretty
boolean
false
false
toQueryString(delimiter=[string])
Converts a struct to a query string using the specified delimiter.
, The default delimiter is ,{@code "&"}
Arguments:
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:
sortType
any
false
text
sortOrder
string
false
asc
localeSensitive
any
false
false
callback
function:Comparator
false
null
update(key=[any], value=[any])
Updates or sets a key/value pair in to a struct
Arguments:
key
any
true
null
value
any
true
null
Examples
Last updated
Was this helpful?