Structures
==========

Introduction to Structures
--------------------------

Maxima provides a simple data aggregate called a structure. A structure is an expression in which arguments are identified by name (the field name) and the expression as a whole is identified by its operator (the structure name). A field value can be any expression.

A structure is defined by the defstruct function; the global variable structures is the list of user-defined structures. The function new creates instances of structures. The @ operator refers to fields. kill(S) removes the structure definition S, and kill(X@ A) unbinds the field A of the structure instance X.

In the pretty-printing console display (with display2d equal to true), structure instances are displayed with the value of each field represented as an equation, with the field name on the left-hand side and the value on the right-hand side. (The equation is only a display construct; only the value is actually stored.) In 1-dimensional display (via grind or with display2d equal to false), structure instances are displayed without the field names.

There is no way to use a field name as a function name, although a field value can be a lambda expression. Nor can the values of fields be restricted to certain types; any field can be assigned any kind of expression. There is no way to make some fields accessible or inaccessible in different contexts; all fields are always visible.

Functions and Variables for Structures
--------------------------------------

 -- Global variable: structures

     structures is the list of user-defined structures defined by defstruct.

     Categories: Structures Global variables

 -- Function: defstruct
     defstruct (S(A_1, ..., A_N))
     defstruct (S(A_1 = V_1, ..., A_N = V_N))

     Define a structure, which is a list of named fields A_1, ..., A_N associated with a symbol S. An instance of a structure is just an expression which has operator S and exactly n arguments. new(S) creates a new instance of structure S.

     An argument which is just a symbol A specifies the name of a field. An argument which is an equation A = V specifies the field name A and its default value V. The default value can be any expression.

     defstruct puts S on the list of user-defined structures, structures.

     kill(S) removes S from the list of user-defined structures, and removes the structure definition.

     Examples:

          (%i1) defstruct (foo (a, b, c));
          (%o1)                    [foo(a, b, c)]
          (%i2) structures;
          (%o2)                    [foo(a, b, c)]
          (%i3) new (foo);
          (%o3)                     foo(a, b, c)
          (%i4) defstruct (bar (v, w, x = 123, y = %pi));
          (%o4)             [bar(v, w, x = 123, y = %pi)]
          (%i5) structures;
          (%o5)      [foo(a, b, c), bar(v, w, x = 123, y = %pi)]
          (%i6) new (bar);
          (%o6)              bar(v, w, x = 123, y = %pi)
          (%i7) kill (foo);
          (%o7)                         done
          (%i8) structures;
          (%o8)             [bar(v, w, x = 123, y = %pi)]

     Categories: Structures

 -- Function: new
     new (S)
     new (S (V_1, ..., V_N))

     new creates new instances of structures.

     new(S) creates a new instance of structure S in which each field is assigned its default value, if any, or no value at all if no default was specified in the structure definition.

     new(S(V_1, ..., V_N)) creates a new instance of S in which fields are assigned the values V_1, ..., V_N.

     Examples:

          (%i1) defstruct (foo (w, x = %e, y = 42, z));
          (%o1)              [foo(w, x = %e, y = 42, z)]
          (%i2) new (foo);
          (%o2)               foo(w, x = %e, y = 42, z)
          (%i3) new (foo (1, 2, 4, 8));
          (%o3)            foo(w = 1, x = 2, y = 4, z = 8)

     Categories: Structures

 -- Operator: @

     @ is the structure field access operator. The expression X@ A refers to the value of field A of the structure instance X. The field name is not evaluated.

     If the field A in X has not been assigned a value, X@ A evaluates to itself.

     kill(X@ A) removes the value of field A in X.

     Examples:

          (%i1) defstruct (foo (x, y, z));
          (%o1)                    [foo(x, y, z)]
          (%i2) u : new (foo (123, a - b, %pi));
          (%o2)           foo(x = 123, y = a - b, z = %pi)
          (%i3) u@z;
          (%o3)                          %pi
          (%i4) u@z : %e;
          (%o4)                          %e
          (%i5) u;
          (%o5)            foo(x = 123, y = a - b, z = %e)
          (%i6) kill (u@z);
          (%o6)                         done
          (%i7) u;
          (%o7)              foo(x = 123, y = a - b, z)
          (%i8) u@z;
          (%o8)                          u@z

     The field name is not evaluated.

          (%i1) defstruct (bar (g, h));
          (%o1)                      [bar(g, h)]
          (%i2) x : new (bar);
          (%o2)                       bar(g, h)
          (%i3) x@h : 42;
          (%o3)                          42
          (%i4) h : 123;
          (%o4)                          123
          (%i5) x@h;
          (%o5)                          42
          (%i6) x@h : 19;
          (%o6)                          19
          (%i7) x;
          (%o7)                    bar(g, h = 19)
          (%i8) h;
          (%o8)                          123

     Categories: Structures Operators