structNew

Creates a new, empty structure. The shorthand syntax for an empty unordered struct is {}. You can also use the syntax {"key":"value"} to initialize it with values. The shorthand syntax for an ordered struct is [:] or [=]. The shorthand for a case-sensitive struct is ${}.The shorthand for a ordered and casesensitive struct is $[=].
NOTE: To preserve the case of the struct key, place quotes around it, otherwise it will be converted to uppercase.

structNew([type[[,sortType][,sortOrder][,localeSensitive]|[,callback]]]) → returns struct

  1. CFDocs
  2. Functions
  3. Structure Functions
  4. structNew
  5. CF
  6. Lucee
  7. BL 1.0.0+
  8. 0 Issue
  9. Edit
See Also:   struct-functions

Argument Reference

type string

CF 2016+ Lucee 4.5+ If set to ordered the order in which elements are added to the structure will be maintained. In Lucee linked can be used in place of ordered.
CF 2021+ If set to casesensitive the keys will remain case-sensitive. Additionally, ordered-casesensitive can be used to create an ordered case-sensitive struct.
Values:
  • ordered
  • casesensitive
  • ordered-casesensitive

sortType string

CF2016u3+ Sort types are text or numeric.
Values:
  • text
  • numeric

sortOrder string
Default: asc

CF2016u3+ The order of the sort (ascending or descending).
Values:
  • asc
  • desc

localeSensitive boolean
Default: false

CF2016u3+ Specify if you wish to do a locale sensitive sorting.

callback function

CF2016u3+ A comparator function used to sort new data entered into the structure. Returns 1, 0 or -1.

Compatibility

ColdFusion:

CF2016 added ordered structs. CF2016u3 added sorted structs. CF2018 added named parameters. CF2021 added 2 new types: ordered-casesensitive & casesensitive.

Links more information about structNew

Examples
Sample code invoking the structNew function

Creates an unordered struct.

unordered = { a=1, c=3, b=2 };
writeDump( unordered );

Creates an unordered struct.

unordered = structNew();
unordered.a = 1;
unordered.b = 2;
unordered.c = 3;
writeDump( unordered );

CF 2016+ Creates an ordered struct. Note the square brackets.

ordered = [ a=1, b=2, c=3 ];
writeDump( ordered );

CF 2016+ Lucee 4.5+ Creates an ordered struct.

ordered = structNew( "ordered" );
ordered.a = 1;
ordered.b = 2;
ordered.c = 3;
writeDump( ordered );

CF 2016+ Lucee 5+ Creates an ordered struct.

ordered = [:];
ordered.a = 1;
ordered.b = 2;
ordered.c = 3;
writeDump( ordered );

CF 2021+ Creates a case-sensitive struct.

casesensitive = structNew( "casesensitive" );
casesensitive.a = 1;
casesensitive.B = 2;
casesensitive.c = 3;
writeDump( casesensitive );

CF 2021+ Creates a case-sensitive struct.

casesensitive = ${a=1, B=2, c=3};
writeDump( casesensitive );

CF 2021+ Creates a case-sensitive struct.

someStruct = structNew( "ordered-casesensitive" );
someStruct.c = 3;
someStruct.B = 2;
someStruct.a = 1;
writeDump( someStruct );

CF 2021+ Creates an ordered and case-sensitive struct.

someStruct = $[c=3, B=2, a=1];
writeDump( someStruct );

Signup for cfbreak to stay updated on the latest news from the ColdFusion / CFML community. One email, every friday.

Fork me on GitHub