structs.scad

LibFile: structs.scad

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>

File Contents

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.

Section: struct operations

Function: struct_set()

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:

By Position	What it does
struct	input structure.
key	key to set or list of key,value pairs to set
value	value to set the key to (when giving a single key and value)

By Name	What it does
grow	Set to true to allow structure to grow, or false for new keys to generate an error. Default: true

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

include <BOSL2/std.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>
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

---

Function: struct_remove()

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:

By Position	What it does
struct	input structure
key	a single key or list of keys to remove.

---

Function: struct_val()

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:

By Position	What it does
struct	input structure
key	key whose value to return
default	default value to return if key is not present. Default: undef

---

Function: struct_keys()

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:

By Position	What it does
struct	input structure

---

Function/Module: echo_struct()

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:

By Position	What it does
struct	input structure
name	optional structure name to list at the top of the output. Default: ""

---

Function: is_struct()

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.

---