doc/info/defstruct.texi

   1 @c -----------------------------------------------------------------------------
   2 @page
   3 @node Structures, , Arrays, Data Types and Structures
   4 @section Structures
   5 @c -----------------------------------------------------------------------------
   6
   7 @menu
   8 * Introduction to Structures::
   9 * Functions and Variables for Structures::
  10 @end menu
  11
  12 @c -----------------------------------------------------------------------------
  13 @node Introduction to Structures, Functions and Variables for Structures, Structures, Structures
  14 @subsection Introduction to Structures
  15 @c -----------------------------------------------------------------------------
  16
  17 Maxima provides a simple data aggregate called a structure.
  18 A structure is an expression in which arguments are identified by name (the field name)
  19 and the expression as a whole is identified by its operator (the structure name).
  20 A field value can be any expression.
  21
  22 A structure is defined by the @code{defstruct} function;
  23 the global variable @code{structures} is the list of user-defined structures.
  24 The function @code{new} creates instances of structures.
  25 The @code{@@} operator refers to fields.
  26 @code{kill(@var{S})} removes the structure definition @var{S},
  27 and @code{kill(@var{x}@@ @var{a})} unbinds the field @var{a} of the structure instance @var{x}.
  28
  29 In the pretty-printing console display (with @mref{display2d} equal to @code{true}),
  30 structure instances are displayed with the value of each field
  31 represented as an equation, with the field name on the left-hand side
  32 and the value on the right-hand side.
  33 (The equation is only a display construct; only the value is actually stored.)
  34 In 1-dimensional display (via @code{grind} or with @mref{display2d} equal to @code{false}),
  35 structure instances are displayed without the field names.
  36
  37 There is no way to use a field name as a function name,
  38 although a field value can be a lambda expression.
  39 Nor can the values of fields be restricted to certain types; any field can be assigned any kind of expression.
  40 There is no way to make some fields accessible or inaccessible in different contexts;
  41 all fields are always visible.
  42
  43 @c -----------------------------------------------------------------------------
  44 @node Functions and Variables for Structures,  , Introduction to Structures, Structures
  45 @subsection Functions and Variables for Structures
  46 @c -----------------------------------------------------------------------------
  47
  48 @c -----------------------------------------------------------------------------
  49 @anchor{structures}
  50 @defvr {Global variable} structures
  51
  52 @code{structures} is the list of user-defined structures defined by @code{defstruct}.
  53
  54 @opencatbox{Categories:}
  55 @category{Structures}
  56 @category{Global variables}
  57 @closecatbox
  58 @end defvr
  59
  60 @c -----------------------------------------------------------------------------
  61 @anchor{defstruct}
  62 @deffn  {Function} defstruct @
  63 @fname{defstruct} (@var{S}(@var{a_1}, @dots{}, @var{a_n})) @
  64 @fname{defstruct} (@var{S}(@var{a_1} = @var{v_1}, @dots{}, @var{a_n} = @var{v_n}))
  65
  66 Define a structure, which is a list of named fields @var{a_1}, @dots{},
  67 @var{a_n} associated with a symbol @var{S}.
  68 An instance of a structure is just an expression which has operator @var{S}
  69 and exactly @code{n} arguments.
  70 @code{new(@var{S})} creates a new instance of structure @var{S}.
  71
  72 An argument which is just a symbol @var{a} specifies the name of a field.
  73 An argument which is an equation @code{@var{a} = @var{v}} specifies the field name @var{a}
  74 and its default value @var{v}.
  75 The default value can be any expression.
  76
  77 @code{defstruct} puts @var{S} on the list of user-defined structures, @code{structures}.
  78
  79 @code{kill(@var{S})} removes @var{S} from the list of user-defined structures,
  80 and removes the structure definition.
  81
  82 Examples:
  83
  84 @c ===beg===
  85 @c defstruct (foo (a, b, c));
  86 @c structures;
  87 @c new (foo);
  88 @c defstruct (bar (v, w, x = 123, y = %pi));
  89 @c structures;
  90 @c new (bar);
  91 @c kill (foo);
  92 @c structures;
  93 @c ===end===
  94 @example
  95 (%i1) defstruct (foo (a, b, c));
  96 (%o1)                    [foo(a, b, c)]
  97 (%i2) structures;
  98 (%o2)                    [foo(a, b, c)]
  99 (%i3) new (foo);
 100 (%o3)                     foo(a, b, c)
 101 (%i4) defstruct (bar (v, w, x = 123, y = %pi));
 102 (%o4)             [bar(v, w, x = 123, y = %pi)]
 103 (%i5) structures;
 104 (%o5)      [foo(a, b, c), bar(v, w, x = 123, y = %pi)]
 105 (%i6) new (bar);
 106 (%o6)              bar(v, w, x = 123, y = %pi)
 107 (%i7) kill (foo);
 108 (%o7)                         done
 109 (%i8) structures;
 110 (%o8)             [bar(v, w, x = 123, y = %pi)]
 111 @end example
 112
 113 @opencatbox{Categories:}
 114 @category{Structures}
 115 @closecatbox
 116 @end deffn
 117
 118 @c -----------------------------------------------------------------------------
 119 @anchor{new}
 120 @deffn {Function} new @
 121 @fname{new} (@var{S}) @
 122 @fname{new} (@var{S} (@var{v_1}, @dots{}, @var{v_n}))
 123
 124 @code{new} creates new instances of structures.
 125
 126 @code{new(@var{S})} creates a new instance of structure @var{S}
 127 in which each field is assigned its default value, if any,
 128 or no value at all if no default was specified in the structure definition.
 129
 130 @code{new(@var{S}(@var{v_1}, ..., @var{v_n}))} creates a new instance of @var{S}
 131 in which fields are assigned the values @var{v_1}, @dots{}, @var{v_n}.
 132
 133 Examples:
 134
 135 @c ===beg===
 136 @c defstruct (foo (w, x = %e, y = 42, z));
 137 @c new (foo);
 138 @c new (foo (1, 2, 4, 8));
 139 @c ===end===
 140 @example
 141 (%i1) defstruct (foo (w, x = %e, y = 42, z));
 142 (%o1)              [foo(w, x = %e, y = 42, z)]
 143 (%i2) new (foo);
 144 (%o2)               foo(w, x = %e, y = 42, z)
 145 (%i3) new (foo (1, 2, 4, 8));
 146 (%o3)            foo(w = 1, x = 2, y = 4, z = 8)
 147 @end example
 148
 149 @opencatbox{Categories:}
 150 @category{Structures}
 151 @closecatbox
 152 @end deffn
 153
 154 @c -----------------------------------------------------------------------------
 155 @deffn {Operator} @@
 156
 157 @code{@@} is the structure field access operator.
 158 The expression @code{@var{x}@@ @var{a}} refers to the value of field @var{a} of the structure instance @var{x}.
 159 The field name is not evaluated.
 160
 161 If the field @var{a} in @var{x} has not been assigned a value,
 162 @code{@var{x}@@ @var{a}} evaluates to itself.
 163
 164 @code{kill(@var{x}@@ @var{a})} removes the value of field @var{a} in @var{x}.
 165
 166 Examples:
 167
 168 @c ===beg===
 169 @c defstruct (foo (x, y, z));
 170 @c u : new (foo (123, a - b, %pi));
 171 @c u@z;
 172 @c u@z : %e;
 173 @c u;
 174 @c kill (u@z);
 175 @c u;
 176 @c u@z;
 177 @c ===end===
 178 @example
 179 (%i1) defstruct (foo (x, y, z));
 180 (%o1)                    [foo(x, y, z)]
 181 (%i2) u : new (foo (123, a - b, %pi));
 182 (%o2)           foo(x = 123, y = a - b, z = %pi)
 183 (%i3) u@@z;
 184 (%o3)                          %pi
 185 (%i4) u@@z : %e;
 186 (%o4)                          %e
 187 (%i5) u;
 188 (%o5)            foo(x = 123, y = a - b, z = %e)
 189 (%i6) kill (u@@z);
 190 (%o6)                         done
 191 (%i7) u;
 192 (%o7)              foo(x = 123, y = a - b, z)
 193 (%i8) u@@z;
 194 (%o8)                          u@@z
 195 @end example
 196
 197 The field name is not evaluated.
 198
 199 @c ===beg===
 200 @c defstruct (bar (g, h));
 201 @c x : new (bar);
 202 @c x@h : 42;
 203 @c h : 123;
 204 @c x@h;
 205 @c x@h : 19;
 206 @c x;
 207 @c h;
 208 @c ===end===
 209 @example
 210 (%i1) defstruct (bar (g, h));
 211 (%o1)                      [bar(g, h)]
 212 (%i2) x : new (bar);
 213 (%o2)                       bar(g, h)
 214 (%i3) x@@h : 42;
 215 (%o3)                          42
 216 (%i4) h : 123;
 217 (%o4)                          123
 218 (%i5) x@@h;
 219 (%o5)                          42
 220 (%i6) x@@h : 19;
 221 (%o6)                          19
 222 (%i7) x;
 223 (%o7)                    bar(g, h = 19)
 224 (%i8) h;
 225 (%o8)                          123
 226 @end example
 227
 228 @opencatbox{Categories:}
 229 @category{Structures}
 230 @category{Operators}
 231 @closecatbox
 232 @end deffn
 233