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³

Report an issue
<< setfield	Data Structures	tlist >>