This file provides manipulation of "structs". A "struct" is a data structure that associates arbitrary keys with values and allows you to get and set values by key.

To use, add the following lines to the beginning of your file:

include <BOSL2/std.scad>
include <BOSL2/structs.scad>

1. Section: struct operations
   • struct_set() – Sets one or more key-value pairs in a struct.
   • struct_remove() – Removes one or more keys from a struct.
   • struct_val() – Returns the value for an key in a struct.
   • struct_keys() – Returns a list of keys for a struct.
   • echo_struct() – Echoes the struct to the console in a formatted manner.
   • is_struct() – Returns true if the value is a struct.

Synopsis: Sets one or more key-value pairs in a struct.

Topics: Data Structures, Dictionaries

See Also: struct_remove(), struct_val(), struct_keys(), echo_struct(), is_struct()

Usage:

• struct2 = struct_set(struct, key, value, [grow=]);
• struct2 = struct_set(struct, [key1, value1, key2, value2, ...], [grow=]);

Description:

Sets the key(s) in the structure to the specified value(s), returning a new updated structure. If a key exists its value is changed, otherwise the key is added to the structure. If grow=false then it is an error to set a key not already defined in the structure. If you specify the same key twice that is also an error. Note that key order will change when you change a key's value.

Arguments:

Example 1: Create a struct containing just one key-value pair

include <BOSL2/std.scad>
include <BOSL2/structs.scad>
some_struct = struct_set([], "answer", 42);
// 'some_struct' now contains a single value, 42, under one key, "answer".

Example 2: Create a struct containing more than one key-value pair. Note that keys and values need not be the same type.

include <BOSL2/std.scad>
include <BOSL2/structs.scad>
some_struct = struct_set([], ["answer", 42, 2, "two", "quote", "What a nice day"]);
// 'some struct' now contains these key-value pairs:
// answer: 42
// 2: two
// quote: What a nice day

Synopsis: Removes one or more keys from a struct.

Topics: Data Structures, Dictionaries

See Also: struct_set(), struct_val(), struct_keys(), echo_struct(), is_struct()

Usage:

• struct2 = struct_remove(struct, key);

Description:

Remove key or list of keys from a structure. If you want to remove a single key which is a list you must pass it as a singleton list, or struct_remove will attempt to remove the listed items as keys. If you list the same item multiple times for removal it will be removed without error.

Arguments:

Synopsis: Returns the value for an key in a struct.

Topics: Data Structures, Dictionaries

See Also: struct_set(), struct_remove(), struct_keys(), echo_struct(), is_struct()

Usage:

• val = struct_val(struct, key, default);

Description:

Returns the value for the specified key in the structure, or default value if the key is not present

Arguments:

Synopsis: Returns a list of keys for a struct.

Topics: Data Structures, Dictionaries

See Also: struct_set(), struct_remove(), struct_val(), echo_struct(), is_struct()

Usage:

• keys = struct_keys(struct);

Description:

Returns a list of the keys in a structure

Arguments:

Synopsis: Echoes the struct to the console in a formatted manner.

Topics: Data Structures, Dictionaries

See Also: struct_set(), struct_remove(), struct_val(), struct_keys(), is_struct()

Usage:

• echo_struct(struct, [name]);
• foo = echo_struct(struct, [name]);

Description:

Displays a list of structure keys and values, one pair per line, for easier reading.

Arguments:

Synopsis: Returns true if the value is a struct.

Topics: Data Structures, Dictionaries

See Also: struct_set(), struct_remove(), struct_val(), struct_keys(), echo_struct()

Usage:

• bool = is_struct(struct);

Description:

Returns true if the input is a list of pairs, false otherwise.