Structs
Structs are data "structures" containing multiple values associated with field names.
Such structures are ubiquitous in computing, from the original struct in C to dynamic objects in JavaScript.
They are used to compose data together into larger, more meaningful objects.
Struct values and types
Structs have a fixed set of fields of given name and type.
There are an infinite number of distinct struct types.
The East type for a struct is created via StructType(fields), where fields is an object mapping field names to East types.
For example StructType({ a: IntegerType, b: StringType }) is the type of a struct containing field a with integer values and field b with string values.
The JavaScript representation is a plain object, such as the value { a: 1n, b: "abc" }.
The TypeScript type of such values is { a: bigint, b: string }.
| East type | Example value (JavaScript) | East object notation |
|---|---|---|
StructType({}) | {} | () |
StructType({ a: IntegerType, b: StringType }) | { a: 1n, b: "abc" } | (a = 1, b = "abc",) |
Structs are very flexible as you are free to choose the number, names and types of the fields yourself. You will use structs extensively in the EDK.
Structs are plain values
East is not an object-oriented language, and does not support classes. It is not possible to attach methods or functions to structs to augment their behavior. Structs stand alone as values – as plain data.
Furthermore, East uses structural typing and struct types are not nominal types. Two structs with the same field names and types are considered to have the same type. Their values can be compared and used interchangeably.
It may be helpful to consider a struct as like the type of a row in a table. A table has named columns, and the data in each column is expected to have a certain type. A table has many rows, and each row has a set of fields containing a value. In both East and SQL, you can treat any two structs or rows as having the same type if the names and types of the fields agree.
Constructing and deconstructing structs
You can build a new struct with Struct, and get a field from an existing struct with GetField.
| East function | Description | Example usage | Result |
|---|---|---|---|
Struct | Create a new struct | Struct({ a: Add(1n, 3n), b: Const("abc") }) | (a = 4, b = "abc",) |
GetField | Get a field value from a struct | GetField(Const({ a: 4n, b: "abc" }), "a") | 4n |
Note that the Struct function allows you to write an expression to compute each field (like Add above).
Direct usage of a JavaScript object will be assumed to be a struct literal value by the EDK.
Each field will assumed to be a value, not an expression.
If any of the fields need to be computed at runtime, it is essential to use the Struct expression to create a new struct.
The EDK will automatically infer the field names and types for you.
The GetField expression is much like the . operator in common programming languages.
For example x.a returns the field named a from the struct x.
(Sadly, the EDK cannot use JavaScript syntax like {} or . for constructing East expressions, much like you cannot use + for Add or * for Multiply, so users need to write out Struct and GetField verbosely. Similar constructors exist for variants, arrays, sets and dictionaries.)
Setting fields
Structs in East are immutable. You cannot modify the fields in an existing struct.
However you will often find yourself needing to construct a new value much like an existing struct but with small modifications.
For example, you may want to change just one field in a struct.
Instead of manually copying each field, the EDK exports the SetField helper function to achieve this goal.
This helper function is just nicer "syntax" for constructing a (possibly quite large) Struct expression.
| East function | Description | Example usage | Result |
|---|---|---|---|
SetField | Create a new struct with an updated field value | SetField(Const({ a: 1n, b: "abc" }), "a", 42n) | (a = 42, b = "abc",) |
You can think of this operation as being like the "spread" syntax { ...struct, field: value } in JavaScript.
The original struct is not modified, but a new one with an updated field is created.
Empty structs
Note that StructType({}) is a valid East type.
This struct containing zero fields.
It has only one possible value, ().
Much like null, it takes zero bits of memory to represent such a value.
Comparison and ordering
Two structs (having the same field names) are compared be comparing the values for each field. For the purpose of ordering, the first field is considered first, followed by the second field, and so-on. This is a kind of "lexical ordering".
Note that this ordering allows for e.g. sorting or grouping by a secondary key.
An array with values of type StructType({ sort_key: DateTimeType, unique_key: StringType, ... }) can be sorted with Sort.
The values will be ordered first by sort_key and then by the (distinct) unique_key.
Such patterns enable efficient algorithms (similar to those used by SQL databases) that you can use in your Elara solutions.
Representation
Structs are represented as JSON objects in East's canonical JSON representation, with field names for keys and the values encoded recursively.
East's object notation, produced by Print, uses parentheses to delimit structs, comma-seperated entries, and = between the field name and value, like (a = 1, b = 2,).
Next steps
Continue to the next tutorial to understand how to use and manipulate sum types with East and Elara using variants.