createArray

Create array of specified class and value

Since R2024a

Syntax

X = createArray

X = createArray(n)

X = createArray(sz1,...,szN)

X = createArray(sz)

X = createArray(___,classname)

X = createArray(___,Name=Value)

Description

X = createArray creates an array of objects of a given class and value, depending on the combination of input arguments passed to the function. When called with no input arguments, it returns the scalar 0.

X = createArray(n) returns an n-by-n matrix of zeros.

X = createArray(sz1,...,szN) returns an sz1-by-...-by-szN array of zeros, where sz1,...,szN indicate the size of each dimension. For example, createArray(2,3) returns a 2-by-3 matrix of zeros.

X = createArray(sz) returns an array of zeros where size vector sz defines size(X). For example, createArray([2 3]) returns a 2-by-3 matrix of zeros.

X = createArray(___,classname) returns an array of default values of class classname. You can use this argument with any of the input arguments from the previous syntaxes. For example, createArray(3,"int8") returns a 3-by-3 matrix of 8-bit integer zeros.

X = createArray(___,Name=Value) specifies options using one or more name-value arguments. You can combine name-value arguments with any of the input arguments from the previous syntaxes, with the exception of classname and the Like name-value argument, which cannot be used together. For example, createArray(2,3,Like=single(1+1i),FillValue=NaN) returns a 2-by-3 matrix filled with single(NaN+0i).

Examples

Dimensions of Array

You can specify the dimensions of an array using one of three syntaxes.

When you specify a scalar, createArray returns a square matrix. Create a 3-by-3 array of zeros using a scalar as input.

A = createArray(3)

A = 3×3

     0     0     0
     0     0     0
     0     0     0

You can specify the dimensions individually. Create a 2-by-3 array of zeros by specifying both dimensions.

B = createArray(2,3)

B = 2×3

     0     0     0
     0     0     0

You can also use a vector to specify the size of the array. Create a 4-by-3-by-2 array of zeros using a vector input.

d = [4 3 2];
C = createArray(d)

C = 
C(:,:,1) =

     0     0     0
     0     0     0
     0     0     0
     0     0     0


C(:,:,2) =

     0     0     0
     0     0     0
     0     0     0
     0     0     0

Class of Array

When you specify a class but not a fill value, createArray fills the array with the default value of that class. Create a 1-by-5 array of class single. The array is filled with 0, which is the default value of single.

S = createArray(1,5,"single")

S = 1x5 single row vector

     0     0     0     0     0

createArray can return arrays of almost any MATLAB class. Create a 5-by-1 array of class datetime. The array is filled with NaT, which is the default value of datetime.

D = createArray(5,1,"datetime")

D = 5x1 datetime
   NaT
   NaT
   NaT
   NaT
   NaT

You can also use the Like name-value argument to specify a class. createArray uses the class of the prototype to determine a default value. Create a 1-by-3 array using a uint16 prototype. The returned array preserves the class of the prototype value and substitutes in the default value of uint16.

E = createArray(1,3,Like=uint16(12))

E = 1x3 uint16 row vector

   0   0   0

Using Prototypes

The Like name-value argument enables you to create an array based on a prototype. The returned array takes on the class, complexity, sparsity, and other properties of the prototype.

Define a complex variable of class uint8.

p = uint8(7 + 3i)

p = uint8

7 +   3i

Create a 3-by-3 array using p as a prototype. The returned array has the same class and complexity as p, but createArray uses the default value of the class, which is 0, instead of the actual value of p.

X = createArray(3,Like=p)

X = 3x3 uint8 matrix

   0 +   0i   0 +   0i   0 +   0i
   0 +   0i   0 +   0i   0 +   0i
   0 +   0i   0 +   0i   0 +   0i

Using a prototype also preserves other properties of the prototype, including general formatting. Create a 2-by-3 array with a duration prototype.

Y = createArray(2,3,Like=seconds(30))

Y = 2x3 duration
   0 sec   0 sec   0 sec
   0 sec   0 sec   0 sec

The value of elements of Y is the default value of duration, but they have the same format as the prototype.

Y.Format

ans = 
's'

Fill Value for Array

Use the FillValue name-value argument to set the value of all elements of an array.

Create a 2-by-3 array of 10 seconds as a duration.

A = createArray(2,3,FillValue=seconds(10))

A = 2x3 duration
   10 sec   10 sec   10 sec
   10 sec   10 sec   10 sec

createArray preserves the class of the fill value. Create a 3-by-3 array of pi as a single.

P = createArray(3,FillValue=single(pi))

P = 3x3 single matrix

    3.1416    3.1416    3.1416
    3.1416    3.1416    3.1416
    3.1416    3.1416    3.1416

Using classname and FillValue Together

You can specify the classname and FillValue arguments at the same time, but the FillValue class must match the class specified by classname or be convertible to that class.

Create a 3-by-3 array using a duration as the fill value but specify "string" as classname. MATLAB converts the duration to a string.

f = duration(0,30,0,Format="hh:mm");
C = createArray(3,"string",FillValue=f)

C = 3x3 string
    "00:30"    "00:30"    "00:30"
    "00:30"    "00:30"    "00:30"
    "00:30"    "00:30"    "00:30"

Using Like and FillValue Together

When Like and FillValue are both specified, createArray attempts to convert the FillValue to the same class, complexity, sparsity, and other properties as the prototype value.

Create a 2-by-4 matrix using a FillValue of 8 and a single, complex-valued prototype p. The returned matrix is filled with complex 8 of class single.

p = single(3 + 1i);
Y = createArray(2,4,Like=p,FillValue=8)

Y = 2x4 single matrix

   8.0000 + 0.0000i   8.0000 + 0.0000i   8.0000 + 0.0000i   8.0000 + 0.0000i
   8.0000 + 0.0000i   8.0000 + 0.0000i   8.0000 + 0.0000i   8.0000 + 0.0000i

Create a 2-by-3 matrix by specifying a prototype datetime value with hh:mm format and a FillValue of the current time. The returned array has datetime values in the same format as the prototype.

T = datetime(NaT,Format="hh:mm");
Z = createArray(2,3,Like=T,FillValue="now")

Z = 2x3 datetime
   03:45   03:45   03:45
   03:45   03:45   03:45

Object Array of User-Defined Class

Create an array of objects of a user-defined class named BasicClass. (For more information on this class, see Creating a Simple Class.)

classdef BasicClass
    properties
        Value {mustBeNumeric} = 0
    end
    methods
        function obj = BasicClass(val)
            if nargin == 1
                obj.Value = val;
            end
        end
        function r = roundOff(obj)
            r = round([obj.Value],2);
        end
        function r = multiplyBy(obj,n)
            r = [obj.Value] * n;
        end
        function r = plus(o1,o2)
            r = [o1.Value] + [o2.Value];
        end
    end
end

Create a 2-by-3 object array. Use "BasicClass" as the classname input argument. createArray calls the no-argument constructor once to create a default object. The array is filled with copies of that default object.

A = createArray(2,3,"BasicClass")

A=2×3 BasicClass array with properties:
    Value

Because all elements are copies of the default object, the Value property of each instance takes the default property value of 0.

[A.Value]

ans = 1×6

     0     0     0     0     0     0

Create a new 2-by-2 array using A as a prototype. Set the FillValue to NaN. MATLAB converts the fill value to the class of the prototype by calling the BasicClass constructor with the fill value as an argument.

B = createArray(2,Like=A,FillValue=NaN)

B=2×2 BasicClass array with properties:
    Value

Because all elements are copies of the result of one call to the one-argument constructor, the Value property of each instance is assigned the value NaN.

[B.Value]

ans = 1×4

   NaN   NaN   NaN   NaN

Set the FillValue to an instance of BasicClass with an input argument to get a 2-by-2 array with the property Value set to -1.

C = createArray(2,FillValue=BasicClass(-1));
[C.Value]

ans = 1×4

    -1    -1    -1    -1

Input Arguments

n — Size of square matrix

integer value

Size of square matrix, specified as an integer value.

• If n is 0, then X is an empty matrix.

• If n is negative, then it is treated as 0.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

sz1,...,szN — Size of each dimension (as separate arguments)

integer values

Size of each dimension, specified as separate arguments of integer values.

• If the size of any dimension is 0, then X is an empty array.

• If the size of any dimension is negative, then it is treated as 0.

• Beyond the second dimension, createArray ignores trailing dimensions with a size of 1. For example, createArray(3,1,1,1) produces a 3-by-1 vector of zeros.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

sz — Size of each dimension (as a row vector)

integer values

Size of each dimension, specified as a row vector of integer values. Each element of this vector indicates the size of the corresponding dimension:

• If the size of any dimension is 0, then X is an empty array.

• If the size of any dimension is negative, then it is treated as 0.

• Beyond the second dimension, createArray ignores trailing dimensions with a size of 1. For example, createArray([3 1 1 1]) produces a 3-by-1 vector of zeros.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

classname — Class to create

string scalar | character vector

Class to create, specified as a string scalar or character vector. Valid inputs include names of fundamental MATLAB^® classes (see Fundamental MATLAB Classes) as well as user-defined classes. If you do not specify a FillValue, the array is filled with the default value the class uses for array expansion. For example, numeric and logical types have a default value of zero. For other fundamental MATLAB classes, see their individual reference pages.

For user-defined classes, the default values are determined by a method call based on the type of class:

• Heterogeneous hierarchy superclass — Call to getDefaultScalarElement.

• Class that customizes parentheses indexing — Call to parenAssign.

• Other classes — Call to no-argument constructor.

When you specify both classname and FillValue, the value in FillValue must be the same class as classname or convertible to that class.

MATLAB errors if classname and Like are specified at the same time, even if the prototype is the same class or convertible to the class specified by classname.

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: FillValue = "text"

Like — Prototype of array to create

array

Prototype of the array to create, specified as an array. The returned array has the same class, sparsity, and other array attributes as the prototype. The elements of the array take the default value of the prototype class.

Dependencies

• MATLAB errors if classname and Like are specified at the same time, even if the prototype is the same class or convertible to the class specified by classname.

• When you specify both Like and FillValue, the value in FillValue must be the same class as Like or convertible to that class. The returned array takes the class, sparsity, and other attributes of the Like value, even if they are different from those of the FillValue. If either the FillValue or the Like value is complex, the returned array is complex.

FillValue — Value to fill array with

scalar

The value to fill the array with, specified as a scalar. The value can be a fundamental MATLAB class or a user-defined class, and complex numbers are supported.

Dependencies

• When you specify both classname and FillValue, the value in FillValue must be the same class as classname or convertible to that class.

• When you specify both Like and FillValue, the value in FillValue must be the same class as Like or convertible to that class. The returned array takes the class, sparsity, and other attributes of the Like value, even if they are different from those of the FillValue. If either the FillValue or the Like value is complex, the returned array is complex.

Tips

For information on customizing createArray, see Class Support for Array-Creation Functions.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• The n, sz1,…,szN, and sz arguments must be non-negative and non-empty.

• Code generation does not support object arrays. You can use createArray to create scalar objects.

• You cannot create table, timetable, categorical, datetime, and dlarray (Deep Learning Toolbox) objects using createArray.

• If you use createArray to create a handle class object or to create an instance of a class that customizes parentheses indexing, the class must implement a createArray or createArrayLike method. See Class Support for Array-Creation Functions.

• Code generation does not support arrays of strings. To use createArray to create a scalar string, you must specify the FillValue name-value argument. For example:

  function out = createString 
  out = createArray(1,1,"string",FillValue="")
  end

• The Like name-value argument does not support structures. For example, code generation fails for this function:

  function out = createArrayError 
  s = struct('field1', 3, 'field2', false);
  out = createArray(3,4,Like=s);
  end

  To create an array of structures based on a structure prototype, use the FillValue name-value argument. For example:

  function out = createArrayExample1 
  s = struct('field1', 3, 'field2', false);
  out = createArray(3,4,FillValue=s);
  end

  Alternatively, use the classname argument to create an array of empty structures. For example:

  function out = createArrayExample2 
  out = createArray(3,4,"struct");
  end

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™. (since R2024a)

This function fully supports GPU arrays. You can create a gpuArray object by doing one of the following:

• Specifying className as "gpuArray".

• Specifying a gpuArray as the prototype array using the Like name-value argument.

• Specifying the FillValue as a gpuArray without specifying a className or a prototype array.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™. (since R2024a)

This function fully supports distributed arrays. You can create a distributed or codistributed array by doing one of the following:

• Specifying className as "distributed" or "codistributed".

• Specifying a distributed or codistributed array as the prototype array using the Like name-value argument.

• Specifying the FillValue as a distributed or codistributed array without specifying a className or a prototype array.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2024a

R2024b: C/C++ code generation support

You can generate code for the createArray function, with some limitations.