struct Builds a structure or an array of structures

## Syntax

                st = struct(field1, value1, field2, value2, ...)

## Arguments

field1, field2, ...
  strings: Case-sensitive names of the fields of the structure.

value1, value2, ...

  Data assigned to the respective fields. All data types are supported.

  If several values are non-scalar cells arrays, then they must have the same size. For any scalar cell, the cell's container is stripped off, and its content is considered and assigned to the field as a whole. The processing of non-scalar cells is described here-below.

st
  Scalar structure, or array of structures if at least one value is a non-scalar cells array.

## Description

### Scalar structure

If none of values `value1`, `value2`, ..., `valueN` is a non-scalar cells array, `st = struct(field1, value1, field2, value2, ...)` builds a scalar structure `st` (of size 1×1) with fields and values `st.field1=value1`, `st.field2=value2`, ..., `st.fieldN=valueN`.

The value of any field of such a scalar structure can be a scalar or an array. The sizes of values of distinct fields can be distinct. Example: `st = struct("u",[2 3], "v",[%t %f ; %f %t], "w","Hello")` is perfectly allowed and sets `st.u=[2 3]`, `st.v=[%t %f ; %f %t]`, and `st.w="Hello"`

It is possible to assign a scalar or non-scalar cells array to the field of a scalar structure by embedding it in a scalar cell. Examples: `st = struct("num",1:3, "c",{{sin}})` will set `st.num=1:3` and `st.c={sin}` ; while `st = struct("text","Hello", "test",{{1, sin ; %t %z}})` will set `st.text="Hello"` and `st.test={1,sin;%t,%z}`.

### Array of structures

struct(..) allows to build any array -- vector, matrix or ND-array -- of structures. All elements of the array have then the same set of fields `field1`, `field2`, .., `fieldN`.

Indeed, when at least one of the given values is a non-scalar cells array `C`, `st=struct(..,field,C,..)` builds an array of structures with `size(st)==size(C)`, and sets `st(i).field=C{i}` for any index i.

In this case, any scalar values defined for some other specified fields are replicated and set for all `st` elements.

Example #1: `st=struct("u", {-1,%f,%z})` defines a 1×3 row vector of structures with a single field "u" with values `st(1).u=-1`, `st(2).u=%f`, and `st(3).u=%z`.

Example #2: `st=struct("u", {-1 ; %f}, "t", "Hi")` defines a 2×1 column vector of structures with two fields "u" and "t" with values `st(1,1).u=-1`, `st(1,1).t="Hi"`, `st(2,1).u=%f`, `st(2,1).t="Hi"`.

`type(st)` returns `17`, and `typeof(st)` returns `"st"`.

## Examples

    // Create a scalar Dates structure
    Dates = struct('day',25, 'month','DEC', 'year',2006)
    Dates.month = 'AUG'         // change the month
    Dates.year  = 1973;         // change the year
    Dates.weekday = "Saturday"  // Add a new field

    // Create a 2nd element, to make Dates a vector of dates:
    Dates(1,2).year = 2020
    Dates(2) // Note that the default fields value is []

    // Building the full Dates(2) structure element for all fields.
    // The same fields can be declared in any other order:
    Dates(2) = struct('year',2000, 'day',29, 'weekday',"Tuesday", 'month', "FEB")
    Dates(2)
    Dates(2,3) = struct('weekday',"Sunday", 'day',7, 'month',"FEB", 'year',2021)
    Dates(2,3)
    size(Dates)
    length(Dates)

    --> Dates = struct('day',25, 'month','DEC', 'year',2006)
     Dates  =
      day = 25
      month = "DEC"
      year = 2006

    --> Dates.month = 'AUG'         // change the month
     Dates  =
      day = 25
      month = "AUG"
      year = 2006

    --> Dates.year  = 1973;         // change the year
    --> Dates.weekday = "Saturday"  // Add a new field
     Dates  =
      day = 25
      month = "AUG"
      year = 1973
      weekday = "Saturday"

    --> // Create a 2nd element, to make Dates a vector of dates:
    --> Dates(1,2).year = 2020
     Dates  =
      1x2 struct with fields:
      ["day", "month", "year", "weekday"]

    --> Dates(2) // Note that the default fields value is []
     ans  =
      day = []
      month = []
      year = 2020
      weekday = []

    --> // Building the full Dates(2) structure element for all fields.
    --> // The same fields can be declared in any other order:
    --> Dates(2) = struct('year',2000, 'day',29, 'weekday',"Tuesday", 'month', "FEB")
     Dates  =
      1x2 struct with fields:
      ["day", "month", "year", "weekday"]

    --> Dates(2)
     ans  =
      day = 29
      month = "FEB"
      year = 2000
      weekday = "Tuesday"

    --> Dates(2,3) = struct('weekday',"Sunday", 'day',7, 'month',"FEB", 'year',2021)
     Dates  =
      2x3 struct with fields:
      ["day", "month", "year", "weekday"]

    --> Dates(2,3)
     ans  =
      day = 7
      month = "FEB"
      year = 2021
      weekday = "Sunday"

    --> size(Dates)
     ans  =
       2.   3.

    --> length(Dates)
     ans  =
       6.

Array of structures built from scratch:

    Dates = struct("day",{10 3 ; 25 17}, "month",{"SEP" "JUN" ; "APR" "NOV"}, "year",2020)
    Dates(2,1)

    --> Dates = struct("day",{10 3 ; 25 17}, "month",{"SEP" "JUN" ; "APR" "NOV"}, "year",2020)
     Dates  =
      2x2 struct with fields:
      ["day", "month", "year"]

    --> Dates(2,1)
     ans  =
      day = 25
      month = "APR"
      year = 2020

Structure with cells as a field's value:

    test = struct("number", %pi, "bool",[%f %f], "myCell",{{2 "-5";(1-%z)^3,%t}})
    test.myCell
    test.myCell{2,1}

    --> test = struct("number", %pi, "bool",[%f %f], "myCell",{{2 "-5";(1-%z)^3,%t}})
     test  =
      number = 3.1415927
      bool = [%f,%f]
      myCell: [2x2 cell]

    --> test.myCell
     ans  =
      [1x1 constant  ]  [1x1 string ]
      [1x1 polynomial]  [1x1 boolean]

    --> test.myCell{2,1}
     ans  =
      1 -3z +3z² -z³

## See also

- fieldnames
- tree_show
- makecell
- mlist
- tlist