# struct

Structure array

## Description

A structure array is a data type that groups related data using data containers called fields. Each field can contain any type of data. Access data in a field using dot notation of the form `structName.fieldName`.

## Creation

When you have data to put into a new structure, create the structure using dot notation to name its fields one at a time:

```s.a = 1; s.b = {'A','B','C'}```
```s = struct with fields: a: 1 b: {'A' 'B' 'C'} ```

Field names can contain ASCII letters (A–Z, a–z), digits (0–9), and underscores, and must begin with a letter. The maximum length of a field name is `namelengthmax`.

You also can create a structure array using the `struct` function, described below. You can specify many fields simultaneously, or create a nonscalar structure array.

### Syntax

``s = struct``
``s = struct(field,value)``
``s = struct(field1,value1,...,fieldN,valueN)``
``s = struct([])``
``s = struct(obj)``

### Description

````s = struct` creates a scalar (1-by-1) structure with no fields.```

example

````s = struct(field,value)` creates a structure array with the specified field and value. The `value` input argument can be any data type, such as a numeric, logical, character, or cell array.If `value` is not a cell array, or if `value` is a scalar cell array, then `s` is a scalar structure. For instance, `s = struct('a',[1 2 3])` creates a 1-by-1 structure, where `s.a = [1 2 3]`.If `value` is a nonscalar cell array, then `s` is a structure array with the same dimensions as `value`. Each element of `s` contains the corresponding element of `value`. For example, ```s = struct('x',{'a','b'})``` returns ```s(1).x = 'a'``` and `s(2).x = 'b'`.If `value` is an empty cell array `{}`, then `s` is an empty (0-by-0) structure.```

example

````s = struct(field1,value1,...,fieldN,valueN)` creates a structure array with multiple fields.If none of the `value` inputs are cell arrays, or if all `value` inputs that are cell arrays are scalars, then `s` is a scalar structure.If any of the `value` inputs is a nonscalar cell array, then `s` has the same dimensions as that cell array. Also, if two or more `value` inputs are nonscalar cell arrays, then they all must have the same dimensions.For any `value` that is a scalar cell array or an array of any other data type, `struct` inserts the contents of `value` in the relevant field for all elements of `s`. For example, ```s = struct('x',{'a','b'},'y','c')``` returns ```s(1).x = 'a'```, `s(2).x = 'b'`, `s(1).y = 'c'`, and ```s(2).y = 'c'```.If any `value` input is an empty cell array, `{}`, then output `s` is an empty (0-by-0) structure. To specify an empty field and keep the values of the other fields, use `[]` as a `value` input instead.```
````s = struct([])` creates an empty (0-by-0) structure with no fields.```
````s = struct(obj)` creates a scalar structure with field names and values that correspond to properties of `obj`. The `struct` function does not convert `obj`, but rather creates `s` as a new structure. This structure does not retain the class information, so private, protected, and hidden properties become public fields in `s`. The `struct` function issues a warning when you use this syntax.```

### Input Arguments

expand all

Field name, specified as a character vector or string scalar.

Values, specified as any type of array. If any `value` input is a nonscalar cell array, then all nonscalar cell array inputs must have the same dimensions.

If any `value` input is an empty cell array, `{}`, then the output is an empty structure array. To specify a single empty field, use `[]`.

The `struct` function copies the properties of `obj` to the fields of a new scalar structure.

The `struct` function does not create a structure from most of the fundamental data types. For example, if `obj` has the `double` or `char` data type, then `struct` issues an error message. However, `struct` does return the properties of a table or timetable as a structure. See Fundamental MATLAB Classes for the list of fundamental data types.

## Examples

collapse all

Store related pieces of data in the fields of a structure. You can give the fields human-readable names that describe the data.

Create a structure by adding fields to it using dot notation. The fields contain x- and y-values for a sine wave, and text that describes the data.

```data.x = linspace(0,2*pi); data.y = sin(data.x); data.title = 'y = sin(x)'```
```data = struct with fields: x: [0 0.0635 0.1269 0.1904 0.2539 0.3173 0.3808 0.4443 0.5077 ... ] y: [0 0.0634 0.1266 0.1893 0.2511 0.3120 0.3717 0.4298 0.4862 ... ] title: 'y = sin(x)' ```

Plot the sine wave. You can refer to the arrays of x- and y-values by their field names. Then add the title.

```plot(data.x,data.y) title(data.title)```

Create a nonscalar structure that contains a single field.

```field = 'f'; value = {'some text'; [10, 20, 30]; magic(5)}; s = struct(field,value)```
```s=3×1 struct array with fields: f ```

View the contents of each element.

`s.f`
```ans = 'some text' ```
```ans = 1×3 10 20 30 ```
```ans = 5×5 17 24 1 8 15 23 5 7 14 16 4 6 13 20 22 10 12 19 21 3 11 18 25 2 9 ```

When you access a field of a nonscalar structure, such as `s.f`, MATLAB® returns a comma-separated list. In this case, `s.f` is equivalent to `s(1).f, s(2).f, s(3).f`.

Create a nonscalar structure that contains several fields.

```field1 = 'f1'; value1 = zeros(1,10); field2 = 'f2'; value2 = {'a', 'b'}; field3 = 'f3'; value3 = {pi, pi.^2}; field4 = 'f4'; value4 = {'fourth'}; s = struct(field1,value1,field2,value2,field3,value3,field4,value4)```
```s=1×2 struct array with fields: f1 f2 f3 f4 ```

The cell arrays for `value2` and `value3` are 1-by-2, so `s` is also 1-by-2. Because `value1` is a numeric array and not a cell array, both `s(1).f1` and `s(2).f1` have the same contents. Similarly, because the cell array for `value4` has a single element, `s(1).f4` and `s(2).f4` have the same contents.

`s(1)`
```ans = struct with fields: f1: [0 0 0 0 0 0 0 0 0 0] f2: 'a' f3: 3.1416 f4: 'fourth' ```
`s(2)`
```ans = struct with fields: f1: [0 0 0 0 0 0 0 0 0 0] f2: 'b' f3: 9.8696 f4: 'fourth' ```

Create a structure that contains an empty field. Use `[]` to specify the value of the empty field.

`s = struct('f1','a','f2',[])`
```s = struct with fields: f1: 'a' f2: [] ```

Create a structure with a field that contains a cell array.

```field = 'mycell'; value = {{'a','b','c'}}; s = struct(field,value)```
```s = struct with fields: mycell: {'a' 'b' 'c'} ```

Create an empty structure that contains several fields.

`s = struct('a',{},'b',{},'c',{})`
```s = 0x0 empty struct array with fields: a b c ```

Assign a value to a field in an empty structure.

`s(1).a = 'a'`
```s = struct with fields: a: 'a' b: [] c: [] ```

Create a nested structure, where `a` is a structure with a field that contains another structure.

`a.b = struct('c',{},'d',{})`
```a = struct with fields: b: [0x0 struct] ```

View the names of the fields of `a.b`.

`fieldnames(a.b)`
```ans = 2x1 cell {'c'} {'d'} ```

## Version History

Introduced before R2006a

expand all