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,
padextends each element to match the longest text in the input. - Providing a nonnegative scalar target guarantees a minimum length; single, double, and all eight integer classes are accepted from authoritative native storage, and 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. padCharmust 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 executes on the CPU. Numeric resident values in the text role reject without provider access, while an admitted automatic length control gathers through its owning provider.
GPU memory and residency
Text data is host-only. Automatically placed numeric length controls gather transparently; explicit gpuArray length controls reject before gather.
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?⌄
The text operation is host-only. Automatically placed numeric length controls gather transparently, while explicit gpuArray length controls reject.
Related Strings functions
Transform
append · deblank · erase · eraseBetween · erasePunctuation · eraseURLs · extractAfter · extractBefore · extractBetween · insertAfter · insertBefore · join · lower · replace · replaceBetween · reverse · split · splitlines · strcat · strip · strjoin · strjust · strrep · strsplit · strtrim · upper
Text Analytics
addDependencyDetails · addEntityDetails · addLemmaDetails · addPartOfSpeechDetails · addSentenceDetails · addTypeDetails · bagOfNgrams · bagOfWords · cosineSimilarity · doc2sequence · encode · extractFileText · extractHTMLText · fastTextWordEmbedding · findElement · getAttribute · htmlTree · ind2word · isVocabularyWord · normalizeWords · readWordEmbedding · removeLongWords · removeShortWords · removeStopWords · removeWords · stopWords · tokenDetails · tokenizedDocument · trainWordEmbedding · vaderSentimentScores · vec2word · word2ind · word2vec · wordEncoding · writeWordEmbedding
Core
blanks · char · compose · convertCharsToStrings · convertContainedStringsToChars · convertStringsToChars · genvarname · int2str · isletter · isspace · isStringScalar · isstrprop · mat2str · native2unicode · newline · num2str · sprintf · sscanf · str2double · str2num · strcmp · strcmpi · string · string.empty · strings · strlength · strncmp · strncmpi · strtok · unicode2native
Search
contains · endsWith · matches · startsWith · strfind
Pattern
digitsPattern · lettersPattern · pattern · regexpPattern · textBoundary · wildcardPattern
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.