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:

• Basic Structs: 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 Structs: By default, BoxLang structs are case-insensitive. However, you can create case-sensitive structs if needed.

• Ordered Structs: This implementation of a Struct maintains keys in the order they were added.

• Sorted Structs: This implementation of a Struct maintains keys in specified sorted order.

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:

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=[string], indicateNotExists=[boolean])

Deletes a key from a struct

Arguments:

each(callback=[function], parallel=[boolean], maxThreads=[integer], ordered=[boolean])

Used to iterate over a struct and run the function closure for each key/value pair.

Arguments:

equals(struct2=[structloose])

Tests equality between two structs

Arguments:

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

Used to iterate over a struct and test whether every item in the struct meets the test.

Arguments:

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

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

Arguments:

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

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

Arguments:

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

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

Arguments:

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

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

Arguments:

getFromPath(path=[string])

Retrieves the value from a struct using a path based expression

Arguments:

getMetadata()

Gets Struct-specific metadata of the requested struct.

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

Creates an algorithmic hash of an object

Arguments:

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

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

Arguments:

isCaseSensitive()

Returns whether the give struct is case sensitive

isEmpty()

Determine whether a given value is empty

isOrdered()

Tests whether a struct is ordered ( e.g.

linked )

keyArray()

Get keys of a struct as an array

keyExists(key=[string])

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

Arguments:

keyList(delimiter=[string])

Get keys of a struct as a string list

Arguments:

len()

Returns the absolute value of a number

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

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

Arguments:

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

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

Arguments:

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

Used to iterate over a struct and test whether any items meet the test callback.

Arguments:

sort(sortType=[any], sortOrder=[string], path=[string], callback=[function])

Sorts a struct according to the specified arguments and returns an array of struct keys

Arguments:

toImmutable()

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

toJSON(queryFormat=[string], useSecureJSONPrefix=[boolean], useCustomSerializer=[boolean])

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

Arguments:

toMutable()

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

toQueryString(delimiter=[string])

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

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

Arguments:

toSorted(sortType=[any], sortOrder=[string], localeSensitive=[any], callback=[function])

Converts a struct to a sorted struct - using either a callback comparator or textual directives as the sort option

Arguments:

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

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

Arguments:

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

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

Arguments:

valueArray()

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

Examples