StructNew()

edit

Creates an empty structure.

The shorthand syntax for structNew is {};

The shorthand syntax to create an ordered structure is [:]; or [=];

You can also create structures with data using this syntax:

  • a normal structure { "key": value };
  • a linked/ordered structure use [ "key": value ];

To preserve the case of the struct key, use a quoted value for the key, otherwise, it will be converted to uppercase.

Support for shorthand notation was introduced with Lucee 6.1

lucee = "rocks";
ralio = "rocked";
st = { lucee, ralio };  // produces { "RALIO":"rocked","LUCEE":"rocks" }
StructNew( type=string, onMissingKey=function );

Returns: Struct

Argument Description Default
type
string, optional 		edit

the type of structure created:

  • normal (default): a regular struct ( thread safe )
  • ordered: a struct with linked or ordered keys that maintain their insertion order ( alias linked )
  • soft: a struct with soft reference values, which are cleared at the discretion of the garbage collector in response to memory demand.
  • weak: a struct containing weakly referenced values, which do not prevent their referents from being garbage collected. Weak references are most often used to implement simple caches.
  • observable: a struct that calls the function defined with the argument onChange after a key was set, updated or removed. Requires the argument onChange ( since Lucee 9.0.0.564 )

Note, the older type "synchronized" is now same as the default, normal; all struct/scopes are "thread safe" since version 4.1.

normal
onMissingKey
function, optional 		edit

listener function that get invoked in case a request key does not exist.

Introduced: 6.0.0.107

Examples

edit

Lucee Script

dump(var=structNew("soft"), label="soft");
dump(var=structNew("weak"), label="weak");
dump(var=structNew("linked"), label="linked");
st = {
    "one": [1,2,3],
    "two": {
        "three": QueryNew("id")
    },
    three: "unquoted keys don't preserve case"
};
dump( st );
dump( structKeyList(st) );
dump( structKeyExists(st, "one") );
// shorthand syntax for a new empty ordered struct, [=] also works
st = [:];
st.c = 1;
st.b = 2;
st.a = 3;
dump(st);
// shorthand syntax for an ordered struct with values
st = [
    c: 1,
    b: 2,
    a: 3
];
dump(st);

Observable struct ( since Lucee 9.0.0.564 )

log = [];
sct = structNew( type="observable", onChange=function( key, oldValue, newValue, struct ) {
    log.append( key & ": " & ( oldValue ?: "null" ) & " -> " & ( newValue ?: "null" ) );
} );
sct.name = "Lucee";   // NAME: null -> Lucee
sct.name = "Gian";    // NAME: Lucee -> Gian
sct.delete( "name" ); // NAME: Gian -> null
dump( log );

Lucee Tags

<cfset st = structNew()>
<cfset st["name"] = "John Doe">
<cfset st["age"] = 30>
<cfset st["city"] = "New York">
<cfdump var="#st#">

See also