createArray - Create array of specified class and value - MATLAB (original) (raw)

Create array of specified class and value

Since R2024a

Syntax

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](#mw%5F10cd2c55-9bc9-4dfa-b2f0-78853088da05)) returns ann-by-n matrix of zeros.

example

X = createArray([sz1,...,szN](#mw%5Fe96549af-e025-4156-bbd3-68189e7617da)) returns ansz1-by-...-by-szN array of zeros, wheresz1,...,szN indicate the size of each dimension. For example,createArray(2,3) returns a 2-by-3 matrix of zeros.

example

X = createArray([sz](#mw%5Fdcb8cefa-04d7-4569-ada9-5a817a675915)) 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.

example

X = createArray(___,[classname](#mw%5Fe1f3d933-b5d2-4352-895f-2948a4d57b12)) 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.

example

X = createArray(___,[Name=Value](#namevaluepairarguments)) 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).

example

Examples

collapse all

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 = 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.

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.

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.

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 01:40 01:40 01:40 01:40 01:40 01:40

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.

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.

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]

Input Arguments

collapse all

`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 as0.

`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, thenX is an empty array.
If the size of any dimension is negative, then it is treated as0.
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.

`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, thenX is an empty array.
If the size of any dimension is negative, then it is treated as0.
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.

`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 togetDefaultScalarElement.
Class that customizes parentheses indexing — Call toparenAssign.
Other classes — Call to no-argument constructor.

When you specify both classname andFillValue, 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 asName1=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 andLike are specified at the same time, even if the prototype is the same class or convertible to the class specified byclassname.
When you specify both Like andFillValue, 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 theLike value, even if they are different from those of theFillValue. 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 andFillValue, the value in FillValue must be the same class as classname or convertible to that class.
When you specify both Like andFillValue, 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 theLike value, even if they are different from those of theFillValue. If either the FillValue or the Like value is complex, the returned array is complex.

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 usecreateArray 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 usecreateArray to create a scalar string, you must specify theFillValue 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 theLike 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 adistributed 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 orcodistributed array without specifying aclassName or a prototype array.

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

Version History

Introduced in R2024a

expand all

R2024b: C/C++ code generation support

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

createArray - Create array of specified class and value - MATLAB (original) (raw)

Syntax

Description

Examples

Dimensions of Array

Class of Array

Using Prototypes

Fill Value for Array

Object Array of User-Defined Class

Input Arguments

n — Size of square matrix

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

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

classname — Class to create

Name-Value Arguments

Like — Prototype of array to create

Dependencies

FillValue — Value to fill array with

Dependencies

Extended Capabilities

C/C++ Code Generation

GPU Arrays

Distributed Arrays

Version History

R2024b: C/C++ code generation support

`n` — Size of square matrix

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

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

`classname` — Class to create

`Like` — Prototype of array to create

`FillValue` — Value to fill array with