What does the string.empty function do in MATLAB / RunMat?

string.empty constructs an empty string array. By default it returns a 0×0 array, and when you specify additional dimensions they define the trailing extents while the leading dimension remains zero, ensuring the total element count is zero. This mirrors MATLAB's static string.empty method.

How does the string.empty function behave in MATLAB / RunMat?

• string.empty with no arguments yields a 0×0 string array.
• string.empty(n) produces a 0×n array. The leading dimension is fixed at 0, so the result is still empty even if n > 0.
• string.empty(m, n, p, ...) returns a 0×n×p×… array. All trailing dimensions are honoured while the leading dimension remains zero.
• You can provide a single size vector such as string.empty([0 5 3]); the first entry is ignored beyond confirming it is non-negative, and the remaining entries set the trailing dimensions.
• string.empty(___, 'like', prototype) copies the trailing dimensions from prototype when you do not supply explicit sizes. Any dimensions you pass explicitly take precedence. GPU-resident prototypes are automatically gathered so their shape can be inspected.
• Size inputs must be finite, real, non-negative integers. Fractional or negative values produce a MATLAB-compatible error.
• The result always resides on the host; there is no GPU counterpart for string arrays.

string.empty GPU Execution Behaviour

string.empty does not allocate or interact with GPU memory. It is a pure host constructor that instantly returns the requested shape metadata and an empty data buffer. When the runtime is executing under RunMat Accelerate, no provider hooks are invoked. 'like' prototypes that happen to live on the GPU are gathered to the host before their shape is examined.

Examples of using the string.empty function in MATLAB / RunMat

Creating a 0x0 string array

S = string.empty;

Expected output:

S =
  0x0 string array

Building a 0xN string row vector

row = string.empty(5);

Expected output:

row =
  0x5 string array

Creating a 0xN string array with extra dimensions

cube = string.empty(0, 4, 3);

Expected output:

cube =
  0x4x3 string array

Using a size vector with string.empty

sz = [0 2 5];
grid = string.empty(sz);

Expected output:

grid =
  0x2x5 string array

Resetting a preallocated string array to empty

A = strings(3, 2);  % Some application-specific strings
A = string.empty(size(A));

Expected output:

A =
  0x2 string array

Preserving higher-dimensional layout while empty

layout = string.empty([2 0 4 6]);

Expected output:

layout =
  0x0x4x6 string array

Reusing the shape of an existing array with 'like'

proto = strings(3, 2);
sameCols = string.empty('like', proto);

Expected output:

sameCols =
  0x2 string array

GPU residency in RunMat (Do I need gpuArray?)

No. string.empty allocates metadata for an empty string array entirely on the host. Because the result contains no elements and string scalars are host-only, there is nothing to transfer to or from the GPU. Using gpuArray with string.empty has no effect and is unnecessary.

FAQ

Why is the first dimension always zero?

MATLAB defines classname.empty so that the leading dimension is zero, guaranteeing the result contains no elements. RunMat mirrors this rule for perfect compatibility.

Can I request negative or fractional dimensions?

No. Dimensions must be finite, non-negative integers. Any other input raises a descriptive error.

Does string.empty(n) create space for n elements?

No. It returns a 0×n array, which still has zero elements. Use strings(n) if you want an array of string scalars that you can fill later.

Can I combine scalars and size vectors?

Yes. Calls like string.empty([0 3], 5) flatten to string.empty(0, 3, 5) internally.

What does the 'like' option do?

'like', prototype copies the trailing dimensions from prototype when you omit explicit sizes. The first dimension is still forced to 0, so the result remains empty. The prototype is gathered automatically if it resides on the GPU.

Does the result share storage with existing arrays?

No. Every call returns a new handle. Because the array is empty, the data buffer is an empty vector and consumes negligible memory.

Is there a GPU-accelerated variant?

No. String arrays live on the host in RunMat, and this builtin never touches GPU memory.

How do I obtain a 0x0 string array quickly?

Call string.empty with no arguments. It is equivalent to strings(0) but makes the intention explicit.

Can I use size output directly?

Yes. Expressions like string.empty(size(existingArray)) are supported. The first element of the size vector is ignored when constructing the new array so that the first dimension is zero.

What happens if I pass an empty array as the size vector?

string.empty([]) returns the canonical 0×0 string array, just like calling string.empty with no arguments.

Does string.empty ever throw away extra arguments?

Only when they cannot be interpreted as dimensions. In that case RunMat throws an error rather than guessing.

See Also

string, strings, char, zeros, ones