Main Content

createArray

Create array of specified class and value

Since R2024a

    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.

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

    example

    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
       03:18   03:18   03:18
       03:18   03:18   03:18
    
    

    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.

    Extended Capabilities

    Version History

    Introduced in R2024a

    expand all