Function s = textblockpad(s)
s = textblockpad(s,opt)
inserts filling characters and empty lines to obtain a
text block with a desired width and a desired number of
lines, and returns the resulting string.
The input argument s is a character row vector or a
cell-array of character row vectors. The output argument
will have the same form as the input argument s.
The optional input arugment opt is a struct or a row
cell-array of key-value pairs. Below, settings are
indicated by opt as a struct, and the default value of
each field are given too:
opt.nlinetotal = 10;
opt.nlinetotal indicates the desired total number of
lines. (*)
opt.nlinetop = 0;
opt.nlinetop indicates the desired number of empty
lines which are inserted on top of the given lines. If
it has the value of inf, the effect is of a stretched
vertical whitespace. (*)
opt.nlinebottom = inf;
opt.nlinebottom indicates the desired number of empty
lines which are appended below the given lines. If it
has the value of inf, the effect is of a stretched
vertical whitespace. (*)
opt.widthtotal = 20;
opt.widthtotal indicates the desired total number of
characters on each line. (*)
opt.widthleft = 0;
opt.widthleft indicates the desired number of
opt.fillchar which are inserted left to each given
line. If it has the value of inf, the effect is of a
stretched horizontal whitespace. (*)
opt.widthright = inf;
opt.widthright indicates the desired number of
opt.fillchar which are appended right to each given
line. If it has the value of inf, the effect is of a
stretched horizontal whitespace. (*)
opt.linedelim = "\n";
opt.linedelim contains the line delimiter, i.e. the
character by which lines are separated within a
string.
opt.fillchar = " ";
opt.fillchar contains the filling character. If
opt.fillchar contains more than one character, it is
repeated and clipped (!) to get the exact number of
characters needed for filling.
(*) These options may contain scalars, or matrices with
the same sizes as the input argument s, if s is a
cell-array of character row vectors.
The function takes care of the utf-8 encoding of strings,
and accounts for the real number of characters instead of
simply counting the number of bytes in a string.
The function internally calls the following non-standard
m-files:
-- kvpairs2struct.m
-- unicodelength.m
-- repmatfit.m
(c) 2026 fabien van mook
2026.08.20 release of this file within package "fvm-textblock" under GNU GPLv3+
