struct2table

Convert structure array to table

Syntax

T = struct2table(S)

T = struct2table(S,Name=Value)

Description

T = struct2table(S) converts a structure array to a table. Each field of the input structure becomes a variable in the output table.

If the input is:

• A scalar structure with n fields, all of which have m rows, then the output is an m-by-n table.

  (For a scalar structure whose fields have different numbers of rows, use the AsArray name-value argument in the next syntax.)

• An m-by-1 or 1-by-m structure array with n fields, then the output is an m-by-n table. Each structure provides values for a corresponding row of the output table.

T = struct2table(S,Name=Value) specifies options using one or more name-value arguments in addition to the input argument in the previous syntax.

For example, you can force struct2table to treat the input as a structure array by setting AsArray to true. If the input is a scalar structure, then the output is a one-row table.

Examples

Convert Scalar Structure to Table

Convert a scalar structure to a table using the default options.

Create a structure array, S.

S.Name = ["Chang";"Brown";"Ruiz"];
S.Smoker = ["Y";"N";"Y"];
S.SystolicBP = [124;122;130];
S.DiastolicBP = [93;80;92];

The scalar structure, S, has four fields, each with three rows.

Convert the structure array to a table.

T = struct2table(S)

T=3×4 table
     Name      Smoker    SystolicBP    DiastolicBP
    _______    ______    __________    ___________

    "Chang"     "Y"         124            93     
    "Brown"     "N"         122            80     
    "Ruiz"      "Y"         130            92     

The structure field names in S become the variable names in the output table. The size of T is 3-by-4.

Change Name from a variable to row names by modifying the table property, T.Properties.RowNames, and then deleting the variable Name.

T.Properties.RowNames = T.Name;
T.Name = [];

T

T=3×3 table
             Smoker    SystolicBP    DiastolicBP
             ______    __________    ___________

    Chang     "Y"         124            93     
    Brown     "N"         122            80     
    Ruiz      "Y"         130            92     

Convert Nonscalar Structure Array to Table

Create a nonscalar structure array, S.

S(1,1).Name = "Chang";
S(1,1).Smoker = "Y";
S(1,1).SystolicBP = 124;
S(1,1).DiastolicBP = 93;

S(2,1).Name = "Brown";
S(2,1).Smoker = "N";
S(2,1).SystolicBP = 122;
S(2,1).DiastolicBP = 80;

S(3,1).Name = "Ruiz";
S(3,1).Smoker = "Y";
S(3,1).SystolicBP = 130;
S(3,1).DiastolicBP = 92;

S

S=3×1 struct array with fields:
    Name
    Smoker
    SystolicBP
    DiastolicBP

S is a 3-by-1 structure array with four fields.

Convert the structure array to a table.

T = struct2table(S)

T=3×4 table
     Name      Smoker    SystolicBP    DiastolicBP
    _______    ______    __________    ___________

    "Chang"     "Y"         124            93     
    "Brown"     "N"         122            80     
    "Ruiz"      "Y"         130            92     

The structure field names in S become the variable names in the output table. The size of T is 3-by-4.

Treat Scalar Structure as Structure Array

To create a table from a scalar structure whose fields have different numbers of rows, treat the scalar structure as a structure array.

Create a scalar structure with fields name, billing, and test.

S.name = "John Doe";
S.billing = 127.00;
S.test = [79 75 73; 180 178 177.5; 220 210 205]

S = struct with fields:
       name: "John Doe"
    billing: 127
       test: [3×3 double]

In this case, you cannot use struct2table(S) because the fields have different number of rows.

Instead, treat the input as a structure array by setting the AsArray name-value argument. This syntax enables you to convert a scalar structure to a one-row table even when the fields have different numbers of rows.

T = struct2table(S,AsArray=true)

T=1×3 table
       name       billing        test    
    __________    _______    ____________

    "John Doe"      127      {3×3 double}

Input Arguments

S — Input array

scalar structure | structure array

Input array, specified as a scalar structure or a structure array.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: struct2table(S,AsArray=true) converts S to a one-row table when S is a scalar structure.

RowNames — Row names

{} (default) | string array | cell array of character vectors

Row names, specified as a string array or cell array of character vectors, whose elements are nonempty and distinct. The number of row names must equal the number of rows of the input array.

Row names can have any Unicode^® characters, including spaces and non-ASCII characters, except for the colon character, :.

If you specify row names that have leading or trailing white space characters, then struct2table removes them from the row names.

DimensionNames — Dimension names

two-element string array | two-element cell array of character vectors

Dimension names, specified as a two-element string array or two-element cell array of character vectors whose elements are nonempty and distinct.

Dimension names can have any Unicode characters, including spaces and non-ASCII characters. However, a dimension name cannot match any table variable name or the reserved names Properties, RowNames, VariableNames, or the colon character, :.

As an alternative, in all releases you can specify dimension names by setting the DimensionNames property of the table.

AsArray — Flag to treat input as structure array

true or 1 | false or 0

Flag to treat the input as a structure array, specified as a numeric or logical 1 (true) or 0 (false).

true Default if input is nonscalar structure array

Converts structure array to a table with one row for each structure and one variable for each field of the structure array. The fields can have different sizes. If the values in field S(1:m).fieldname have: Compatible sizes and data types, and each value has one row, then the corresponding table variable is a homogeneous array. Example: S(1).a = [1 2] S(2).a = [3 4] S(1).b = 5 S(2).b = 6 T = struct2table(S) T = 2×2 table a b ______ _ 1 2 5 3 4 6 Different sizes, incompatible data types, or any value has more than one row, then the corresponding table variable is a cell array. Example: S(1).a = [1 2] S(2).a = [3 4 5 6] S(1).b = 7 S(2).b = 8 T = struct2table(S) T = 2×2 table a b ___________ _ {[ 1 2]} 7 {[3 4 5 6]} 8

false Default if input is scalar structure

Converts a scalar structure with n fields into an m-by-n table. Each field must have m rows. Example: S.a = [1;2;3] S.b = [4 5;6 7;8 9] T = struct2table(S) T = 3×2 table a b _ ______ 1 4 5 2 6 7 3 8 9

Output Arguments

T — Output table

table

Output table, returned as a table. The table can store metadata such as descriptions, variable units, variable names, and row names. For more information, see the Properties section of table.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• For more information, see Code Generation for Tables (MATLAB Coder) and Table Limitations for Code Generation (MATLAB Coder).

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

Introduced in R2013b