# 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` returns the scalar `0`.`

example

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

example

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

example

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

example

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

example

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

collapse all

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

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

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' ```

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 12:23 12:23 12:23 12:23 12:23 12:23 ```

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

collapse all

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`

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`

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`

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"`

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.

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.

## Version History

Introduced in R2024a