createArray
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(
returns an
sz1,...,szN
)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(___,
returns an array of default values of class classname
)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(___,
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 Name=Value
)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:18 03:18 03:18
03:18 03:18 03:18
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
is0
, thenX
is an empty matrix.If
n
is negative, then it is treated as0
.
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
, thenX
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 of1
. 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
, thenX
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 of1
. 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
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 inFillValue
must be the same class asLike
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 theFillValue
or theLike
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 inFillValue
must be the same class asclassname
or convertible to that class.When you specify both
Like
andFillValue
, the value inFillValue
must be the same class asLike
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 theFillValue
or theLike
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
, andsz
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
, anddlarray
(Deep Learning Toolbox) objects usingcreateArray
.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 acreateArray
orcreateArrayLike
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 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:To create an array of structures based on a structure prototype, use thefunction out = createArrayError s = struct('field1', 3, 'field2', false); out = createArray(3,4,Like=s); end
FillValue
name-value argument. For example:Alternatively, use thefunction out = createArrayExample1 s = struct('field1', 3, 'field2', false); out = createArray(3,4,FillValue=s); end
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 agpuArray
without specifying aclassName
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
orcodistributed
array as the prototype array using theLike
name-value argument.Specifying the
FillValue
as adistributed
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 R2024aR2024b: C/C++ code generation support
You can generate code for the createArray
function, with some
limitations.
MATLAB-Befehl
Sie haben auf einen Link geklickt, der diesem MATLAB-Befehl entspricht:
Führen Sie den Befehl durch Eingabe in das MATLAB-Befehlsfenster aus. Webbrowser unterstützen keine MATLAB-Befehle.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)