RunMat
GitHub

View all functions

CategoryStrings: Transform

What does the pad function do in MATLAB / RunMat?

pad adds characters to the beginning, end, or both sides of strings so that each element reaches a specified length. It mirrors MATLAB semantics for string arrays, character arrays, and cell arrays of character vectors, including direction keywords, default space padding, and optional custom characters.

How does the pad function behave in MATLAB / RunMat?

  • Without a target length, pad extends each element to match the longest text in the input.
  • Providing a numeric target guarantees a minimum length; existing text that already meets or exceeds the target is returned unchanged.
  • Direction keywords ('left', 'right', 'both') are case-insensitive; 'right' is the default. When an odd number of pad characters is required for 'both', the extra character is appended to the end.
  • padChar must be a single character (string scalar or 1×1 char array). The default is a space.
  • Character arrays remain rectangular. Each row is padded independently and then widened with spaces so the array keeps MATLAB’s column-major layout.
  • Cell arrays preserve their structure. Elements must be string scalars or 1×N character vectors and are padded while keeping their original type.
  • Missing strings (string(missing)) and empty character vectors pass through unchanged, preserving metadata.

pad Function GPU Execution Behaviour

pad always executes on the CPU. When an argument (or a value nested inside a cell array) lives on the GPU, RunMat gathers it, performs the padding step, and produces a host result or re-wraps the padded value inside the cell. No provider hooks exist yet for string padding, so providers and fusion planners treat pad as a sink that terminates device residency.

GPU residency in RunMat (Do I need gpuArray?)

No. Text data in RunMat lives on the host today. If text happens to originate from a GPU computation, pad automatically gathers it before padding, so you never have to manage residency manually for this builtin.

Examples of using the pad function in MATLAB / RunMat

Pad Strings To A Common Width

labels = ["GPU"; "Accelerate"; "RunMat"];
aligned = pad(labels);

Expected output:

aligned =
  3×1 string
    "GPU       "
    "Accelerate"
    "RunMat    "

Pad Strings On The Left With Zeros

ids = ["42"; "7"; "512"];
zero_padded = pad(ids, 4, 'left', '0');

Expected output:

zero_padded =
  3×1 string
    "0042"
    "0007"
    "0512"

Center Text With Both-Sided Padding

titles = ["core"; "planner"];
centered = pad(titles, 10, 'both', '*');

Expected output:

centered =
  2×1 string
    "***core***"
    "*planner**"

Pad Character Array Rows

chars = char("GPU", "RunMat");
out = pad(chars, 8);

Expected output:

out =

  2×8 char array

    'GPU     '
    'RunMat  '

Pad A Cell Array Of Character Vectors

C = {'solver', "planner", 'jit'};
cell_out = pad(C, 'right', '.');

Expected output:

cell_out = 1×3 cell array
    {'solver.'}    {"planner"}    {'jit....'}

Leave Missing Strings Unchanged

values = ["RunMat", "<missing>", "GPU"];
kept = pad(values, 8);

Expected output:

kept =
  1×3 string
    "RunMat  "    <missing>    "GPU     "

FAQ

What inputs does pad accept?

String scalars, string arrays, character arrays, and cell arrays containing string scalars or character vectors. Other types raise MATLAB-compatible errors.

How are direction keywords interpreted?

'left', 'right', and 'both' are supported (case-insensitive). 'right' is the default. With 'both', extra characters are added to the end when an odd number of padding characters is required.

Can I shorten text with pad?

No. When the existing text is already longer than the requested target length, it is returned unchanged.

What happens when I supply a custom padding character?

The character must be length one. RunMat repeats it as many times as needed in the specified direction.

Do missing strings get padded?

Missing strings (<missing>) are passed through untouched so downstream code that checks for missing values continues to work.

How are cell array elements returned?

Each cell retains its type: string scalars remain strings and character vectors remain 1×N character arrays after padding.

Does pad change the orientation of row or column string arrays?

No. The shape of the input array is preserved exactly; only element lengths change.

Will pad run on the GPU in the future?

Possibly, but today it always gathers to the CPU. Providers may add device-side implementations later, and the behaviour documented here will remain the reference.

See Also

strip, strcat, lower, upper, compose

Source & Feedback