`pad` — Pad text values to target lengths with MATLAB-compatible direction and fill-character options.

pad extends string/char/cellstr text values to requested lengths by adding fill characters on left, right, or both sides, using MATLAB-compatible defaults and option parsing.

Syntax

out = pad(str)
out = pad(str, len)
out = pad(str, direction)
out = pad(str, padCharacter)
out = pad(str, len, direction)
out = pad(str, len, padCharacter)
out = pad(str, direction, padCharacter)
out = pad(str, len, direction, padCharacter)

Inputs

Name	Type	Required	Default	Description
`str`	`Any`	Yes	—	Input text (string/char/cell).
`len`	`IntegerScalar`	Yes	—	Target length (non-negative integer).
`direction`	`StringScalar`	Yes	`"right"`	Padding direction (`"left"\|"right"\|"both"`).
`padCharacter`	`StringScalar`	Yes	`" "`	Single-character padding value.

Returns

Name	Type	Description
`out`	`Any`	Padded text preserving input container kind and shape.

Errors

Identifier	When	Message
`RunMat:pad:InvalidInput`	First argument is not a string array, char array, or cell array of text scalars.	`pad: first argument must be a string array, character array, or cell array of character vectors`
`RunMat:pad:Length`	Length argument is not a non-negative integer scalar.	`pad: target length must be a non-negative integer scalar`
`RunMat:pad:Direction`	Direction argument is not one of left/right/both.	`pad: direction must be 'left', 'right', or 'both'`
`RunMat:pad:PadChar`	Padding character is not a single-character string/char scalar.	`pad: padding character must be a string scalar or character vector containing one character`
`RunMat:pad:CellElement`	Cell arrays contain non-text elements or non-row char arrays.	`pad: cell array elements must be string scalars or character vectors`
`RunMat:pad:ArgumentConfig`	Second/third arguments cannot be interpreted as valid pad argument combinations.	`pad: unable to interpret input arguments`
`RunMat:pad:ArgCount`	More than four total arguments are supplied.	`pad: too many input arguments`
`RunMat:pad:InternalError`	Internal output container construction failed.	`pad: internal error`

How `pad` works

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.

Does RunMat run `pad` on the GPU?

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 memory and residency

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

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     "

Using `pad` with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how pad changes the result.

Run a small pad example, explain the result, then change one input and compare the output.

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.

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how pad is executed, line by line, in Rust.

View the source for pad in Rust on GitHub
Learn how the RunMat runtime works
Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing

pad — Pad text values to target lengths with MATLAB-compatible direction and fill-character options.

Syntax

Inputs

Returns

Errors

How pad works

Does RunMat run pad on the GPU?

GPU memory and residency

Examples

Pad Strings To A Common Width

Pad Strings On The Left With Zeros

Center Text With Both-Sided Padding

Pad Character Array Rows

Pad A Cell Array Of Character Vectors

Leave Missing Strings Unchanged

Using pad with coding agents

FAQ

Related Strings functions

Transform

Core

Search

Regex

Open-source implementation

About RunMat

Download RunMat

`pad` — Pad text values to target lengths with MATLAB-compatible direction and fill-character options.

How `pad` works

Does RunMat run `pad` on the GPU?

Using `pad` with coding agents