octave: Manipulating Strings
5.5 Manipulating Strings
========================
Octave supports a wide range of functions for manipulating strings.
Since a string is just a matrix, simple manipulations can be
accomplished using standard operators. The following example shows how
to replace all blank characters with underscores.
quote = ...
"First things first, but not necessarily in that order";
quote( quote == " " ) = "_"
⇒ quote =
First_things_first,_but_not_necessarily_in_that_order
For more complex manipulations, such as searching, replacing, and
general regular expressions, the following functions come with Octave.
-- : deblank (S)
Remove trailing whitespace and nulls from S.
If S is a matrix, DEBLANK trims each row to the length of longest
string. If S is a cell array of strings, operate recursively on
each string element.
Examples:
deblank (" abc ")
⇒ " abc"
deblank ([" abc "; " def "])
⇒ [" abc " ; " def"]
See also: 
strtrim XREFstrtrim.
-- : strtrim (S)
Remove leading and trailing whitespace from S.
If S is a matrix, STRTRIM trims each row to the length of longest
string. If S is a cell array of strings, operate recursively on
each string element.
For example:
strtrim (" abc ")
⇒ "abc"
strtrim ([" abc "; " def "])
⇒ ["abc " ; " def"]
See also: deblank XREFdeblank.
-- : strtrunc (S, N)
Truncate the character string S to length N.
If S is a character matrix, then the number of columns is adjusted.
If S is a cell array of strings, then the operation is performed on
each cell element and the new cell array is returned.
-- : findstr (S, T)
-- : findstr (S, T, OVERLAP)
Return the vector of all positions in the longer of the two strings
S and T where an occurrence of the shorter of the two starts.
If the optional argument OVERLAP is true (default), the returned
vector can include overlapping positions. For example:
findstr ("ababab", "a")
⇒ [1, 3, 5];
findstr ("abababa", "aba", 0)
⇒ [1, 5]
*Caution:* ‘findstr’ is scheduled for deprecation. Use ‘strfind’
in all new code.
See also: strfind XREFstrfind, strmatch XREFstrmatch,
DONTPRINTYET strcmp XREFstrcmp, strncmp XREFstrncmp, *noteDONTPRINTYET DONTPRINTYET strcmp XREFstrcmp, strncmp XREFstrncmp,
strcmpi XREFstrcmpi, strncmpi XREFstrncmpi, *notefind:
DONTPRINTYET DONTPRINTYET strcmp XREFstrcmp, strncmp XREFstrncmp,
strcmpi XREFstrcmpi, strncmpi XREFstrncmpi, find
XREFfind.
-- : IDX = strchr (STR, CHARS)
-- : IDX = strchr (STR, CHARS, N)
-- : IDX = strchr (STR, CHARS, N, DIRECTION)
-- : [I, J] = strchr (...)
Search for the string STR for occurrences of characters from the
set CHARS.
The return value(s), as well as the N and DIRECTION arguments
behave identically as in ‘find’.
This will be faster than using regexp in most cases.
See also: find XREFfind.
-- : index (S, T)
-- : index (S, T, DIRECTION)
Return the position of the first occurrence of the string T in the
string S, or 0 if no occurrence is found.
S may also be a string array or cell array of strings.
For example:
index ("Teststring", "t")
⇒ 4
If DIRECTION is "first", return the first element found. If
DIRECTION is "last", return the last element found.
See also: find XREFfind, rindex XREFrindex.
-- : rindex (S, T)
Return the position of the last occurrence of the character string
T in the character string S, or 0 if no occurrence is found.
S may also be a string array or cell array of strings.
For example:
rindex ("Teststring", "t")
⇒ 6
The ‘rindex’ function is equivalent to ‘index’ with DIRECTION set
to "last".
See also: find XREFfind, index XREFindex.
-- : IDX = strfind (STR, PATTERN)
-- : IDX = strfind (CELLSTR, PATTERN)
-- : IDX = strfind (..., "overlaps", VAL)
Search for PATTERN in the string STR and return the starting index
of every such occurrence in the vector IDX.
If there is no such occurrence, or if PATTERN is longer than STR,
or if PATTERN itself is empty, then IDX is the empty array ‘[]’.
The optional argument "overlaps" determines whether the pattern can
match at every position in STR (true), or only for unique
occurrences of the complete pattern (false). The default is true.
If a cell array of strings CELLSTR is specified then IDX is a cell
array of vectors, as specified above.
Examples:
strfind ("abababa", "aba")
⇒ [1, 3, 5]
strfind ("abababa", "aba", "overlaps", false)
⇒ [1, 5]
strfind ({"abababa", "bebebe", "ab"}, "aba")
⇒
{
[1,1] =
1 3 5
[1,2] = [](1x0)
[1,3] = [](1x0)
}
See also: findstr XREFfindstr, strmatch XREFstrmatch,
DONTPRINTYET regexp XREFregexp, regexpi XREFregexpi, *notefind:
DONTPRINTYET regexp XREFregexp, regexpi XREFregexpi, find
XREFfind.
-- : STR = strjoin (CSTR)
-- : STR = strjoin (CSTR, DELIMITER)
Join the elements of the cell string array, CSTR, into a single
string.
If no DELIMITER is specified, the elements of CSTR are separated by
a space.
If DELIMITER is specified as a string, the cell string array is
joined using the string. Escape sequences are supported.
If DELIMITER is a cell string array whose length is one less than
CSTR, then the elements of CSTR are joined by interleaving the cell
string elements of DELIMITER. Escape sequences are not supported.
strjoin ({'Octave','Scilab','Lush','Yorick'}, '*')
⇒ 'Octave*Scilab*Lush*Yorick'
See also: strsplit XREFstrsplit.
-- : strmatch (S, A)
-- : strmatch (S, A, "exact")
Return indices of entries of A which begin with the string S.
The second argument A must be a string, character matrix, or a cell
array of strings.
If the third argument "exact" is not given, then S only needs to
match A up to the length of S. Trailing spaces and nulls in S and
A are ignored when matching.
For example:
strmatch ("apple", "apple juice")
⇒ 1
strmatch ("apple", ["apple "; "apple juice"; "an apple"])
⇒ [1; 2]
strmatch ("apple", ["apple "; "apple juice"; "an apple"], "exact")
⇒ [1]
*Caution:* ‘strmatch’ is scheduled for deprecation. Use ‘strncmp’
(normal case), or ‘strcmp’ ("exact" case), or ‘regexp’ in all new
code.
See also: strfind XREFstrfind, findstr XREFfindstr,
DONTPRINTYET strcmp XREFstrcmp, strncmp XREFstrncmp, *noteDONTPRINTYET DONTPRINTYET strcmp XREFstrcmp, strncmp XREFstrncmp,
strcmpi XREFstrcmpi, strncmpi XREFstrncmpi, *notefind:
DONTPRINTYET DONTPRINTYET strcmp XREFstrcmp, strncmp XREFstrncmp,
strcmpi XREFstrcmpi, strncmpi XREFstrncmpi, find
XREFfind.
-- : [TOK, REM] = strtok (STR)
-- : [TOK, REM] = strtok (STR, DELIM)
Find all characters in the string STR up to, but not including, the
first character which is in the string DELIM.
STR may also be a cell array of strings in which case the function
executes on every individual string and returns a cell array of
tokens and remainders.
Leading delimiters are ignored. If DELIM is not specified,
whitespace is assumed.
If REM is requested, it contains the remainder of the string,
starting at the first delimiter.
Examples:
strtok ("this is the life")
⇒ "this"
[tok, rem] = strtok ("14*27+31", "+-*/")
⇒
tok = 14
rem = *27+31
See also: index XREFindex, strsplit XREFstrsplit,
strchr XREFstrchr, isspace XREFisspace.
-- : [CSTR] = strsplit (STR)
-- : [CSTR] = strsplit (STR, DEL)
-- : [CSTR] = strsplit (..., NAME, VALUE)
-- : [CSTR, MATCHES] = strsplit (...)
Split the string STR using the delimiters specified by DEL and
return a cell string array of substrings.
If a delimiter is not specified the string is split at whitespace
‘{" ", "\f", "\n", "\r", "\t", "\v"}’. Otherwise, the delimiter,
DEL must be a string or cell array of strings. By default,
consecutive delimiters in the input string S are collapsed into one
resulting in a single split.
Supported NAME/VALUE pair arguments are:
• COLLAPSEDELIMITERS which may take the value of ‘true’
(default) or ‘false’.
• DELIMITERTYPE which may take the value of "simple" (default)
or "regularexpression". A simple delimiter matches the text
exactly as written. Otherwise, the syntax for regular
expressions outlined in ‘regexp’ is used.
The optional second output, MATCHES, returns the delimiters which
were matched in the original string.
Examples with simple delimiters:
strsplit ("a b c")
⇒
{
[1,1] = a
[1,2] = b
[1,3] = c
}
strsplit ("a,b,c", ",")
⇒
{
[1,1] = a
[1,2] = b
[1,3] = c
}
strsplit ("a foo b,bar c", {" ", ",", "foo", "bar"})
⇒
{
[1,1] = a
[1,2] = b
[1,3] = c
}
strsplit ("a,,b, c", {",", " "}, "collapsedelimiters", false)
⇒
{
[1,1] = a
[1,2] =
[1,3] = b
[1,4] =
[1,5] = c
}
Examples with regularexpression delimiters:
strsplit ("a foo b,bar c", ',|\s|foo|bar', "delimitertype", "regularexpression")
⇒
{
[1,1] = a
[1,2] = b
[1,3] = c
}
strsplit ("a,,b, c", '[, ]', "collapsedelimiters", false, "delimitertype", "regularexpression")
⇒
{
[1,1] = a
[1,2] =
[1,3] = b
[1,4] =
[1,5] = c
}
strsplit ("a,\t,b, c", {',', '\s'}, "delimitertype", "regularexpression")
⇒
{
[1,1] = a
[1,2] = b
[1,3] = c
}
strsplit ("a,\t,b, c", {',', ' ', '\t'}, "collapsedelimiters", false)
⇒
{
[1,1] = a
[1,2] =
[1,3] =
[1,4] = b
[1,5] =
[1,6] = c
}
DONTPRINTYET See also: ostrsplit XREFostrsplit, *notestrjoin:
DONTPRINTYET See also: ostrsplit XREFostrsplit, strjoin
XREFstrjoin, strtok XREFstrtok, regexp XREFregexp.
-- : [CSTR] = ostrsplit (S, SEP)
-- : [CSTR] = ostrsplit (S, SEP, STRIP_EMPTY)
Split the string S using one or more separators SEP and return a
cell array of strings.
Consecutive separators and separators at boundaries result in empty
strings, unless STRIP_EMPTY is true. The default value of
STRIP_EMPTY is false.
2-D character arrays are split at separators and at the original
column boundaries.
Example:
ostrsplit ("a,b,c", ",")
⇒
{
[1,1] = a
[1,2] = b
[1,3] = c
}
ostrsplit (["a,b" ; "cde"], ",")
⇒
{
[1,1] = a
[1,2] = b
[1,3] = cde
}
See also: strsplit XREFstrsplit, strtok XREFstrtok.
-- : [A, ...] = strread (STR)
-- : [A, ...] = strread (STR, FORMAT)
-- : [A, ...] = strread (STR, FORMAT, FORMAT_REPEAT)
-- : [A, ...] = strread (STR, FORMAT, PROP1, VALUE1, ...)
-- : [A, ...] = strread (STR, FORMAT, FORMAT_REPEAT, PROP1, VALUE1,
...)
Read data from a string.
The string STR is split into words that are repeatedly matched to
the specifiers in FORMAT. The first word is matched to the first
specifier, the second to the second specifier and so forth. If
there are more words than specifiers, the process is repeated until
all words have been processed.
The string FORMAT describes how the words in STR should be parsed.
It may contain any combination of the following specifiers:
‘%s’
The word is parsed as a string.
‘%f’
‘%n’
The word is parsed as a number and converted to double.
‘%d’
‘%u’
The word is parsed as a number and converted to int32.
‘%*’
‘%*f’
‘%*s’
The word is skipped.
For %s and %d, %f, %n, %u and the associated %*s ...
specifiers an optional width can be specified as %Ns, etc.
where N is an integer > 1. For %f, format specifiers like
%N.Mf are allowed.
‘literals’
In addition the format may contain literal character strings;
these will be skipped during reading.
Parsed word corresponding to the first specifier are returned in
the first output argument and likewise for the rest of the
specifiers.
By default, FORMAT is "%f", meaning that numbers are read from STR.
This will do if STR contains only numeric fields.
For example, the string
STR = "\
Bunny Bugs 5.5\n\
Duck Daffy -7.5e-5\n\
Penguin Tux 6"
can be read using
[A, B, C] = strread (STR, "%s %s %f");
Optional numeric argument FORMAT_REPEAT can be used for limiting
the number of items read:
-1
(default) read all of the string until the end.
N
Read N times NARGOUT items. 0 (zero) is an acceptable value
for FORMAT_REPEAT.
The behavior of ‘strread’ can be changed via property-value pairs.
The following properties are recognized:
"commentstyle"
Parts of STR are considered comments and will be skipped.
VALUE is the comment style and can be any of the following.
• "shell" Everything from ‘#’ characters to the nearest
end-of-line is skipped.
• "c" Everything between ‘/*’ and ‘*/’ is skipped.
• "c++" Everything from ‘//’ characters to the nearest
end-of-line is skipped.
• "matlab" Everything from ‘%’ characters to the nearest
end-of-line is skipped.
• user-supplied. Two options: (1) One string, or 1x1 cell
string: Skip everything to the right of it; (2) 2x1 cell
string array: Everything between the left and right
strings is skipped.
"delimiter"
Any character in VALUE will be used to split STR into words
(default value = any whitespace). Note that whitespace is
implicitly added to the set of delimiter characters unless a
"%s" format conversion specifier is supplied; see "whitespace"
parameter below. The set of delimiter characters cannot be
empty; if needed Octave substitutes a space as delimiter.
"emptyvalue"
Value to return for empty numeric values in non-whitespace
delimited data. The default is NaN. When the data type does
not support NaN (int32 for example), then default is zero.
"multipledelimsasone"
Treat a series of consecutive delimiters, without whitespace
in between, as a single delimiter. Consecutive delimiter
series need not be vertically "aligned".
"treatasempty"
Treat single occurrences (surrounded by delimiters or
whitespace) of the string(s) in VALUE as missing values.
"returnonerror"
If VALUE true (1, default), ignore read errors and return
normally. If false (0), return an error.
"whitespace"
Any character in VALUE will be interpreted as whitespace and
trimmed; the string defining whitespace must be enclosed in
double quotes for proper processing of special characters like
"\t". In each data field, multiple consecutive whitespace
characters are collapsed into one space and leading and
trailing whitespace is removed. The default value for
whitespace is " \b\r\n\t" (note the space). Whitespace is
always added to the set of delimiter characters unless at
least one "%s" format conversion specifier is supplied; in
that case only whitespace explicitly specified in "delimiter"
is retained as delimiter and removed from the set of
whitespace characters. If whitespace characters are to be
kept as-is (in e.g., strings), specify an empty value (i.e.,
"") for "whitespace"; obviously, whitespace cannot be a
delimiter then.
When the number of words in STR doesn’t match an exact multiple of
the number of format conversion specifiers, strread’s behavior
depends on the last character of STR:
last character = "\n"
Data columns are padded with empty fields or Nan so that all
columns have equal length
last character is not "\n"
Data columns are not padded; strread returns columns of
unequal length
DONTPRINTYET See also: textscan XREFtextscan, *notetextread:
DONTPRINTYET See also: textscan XREFtextscan, textread
XREFtextread, load XREFload, dlmread XREFdlmread,
fscanf XREFfscanf.
-- : NEWSTR = strrep (STR, PTN, REP)
-- : NEWSTR = strrep (CELLSTR, PTN, REP)
-- : NEWSTR = strrep (..., "overlaps", VAL)
Replace all occurrences of the pattern PTN in the string STR with
the string REP and return the result.
The optional argument "overlaps" determines whether the pattern can
match at every position in STR (true), or only for unique
occurrences of the complete pattern (false). The default is true.
S may also be a cell array of strings, in which case the
replacement is done for each element and a cell array is returned.
Example:
strrep ("This is a test string", "is", "&%$")
⇒ "Th&%$ &%$ a test string"
DONTPRINTYET See also: regexprep XREFregexprep, *notestrfind:
DONTPRINTYET See also: regexprep XREFregexprep, strfind
XREFstrfind, findstr XREFfindstr.
-- : substr (S, OFFSET)
-- : substr (S, OFFSET, LEN)
Return the substring of S which starts at character number OFFSET
and is LEN characters long.
Position numbering for offsets begins with 1. If OFFSET is
negative, extraction starts that far from the end of the string.
If LEN is omitted, the substring extends to the end of S. A
negative value for LEN extracts to within LEN characters of the end
of the string
Examples:
substr ("This is a test string", 6, 9)
⇒ "is a test"
substr ("This is a test string", -11)
⇒ "test string"
substr ("This is a test string", -11, -7)
⇒ "test"
This function is patterned after the equivalent function in Perl.
-- : [S, E, TE, M, T, NM, SP] = regexp (STR, PAT)
-- : [...] = regexp (STR, PAT, "OPT1", ...)
Regular expression string matching.
Search for PAT in STR and return the positions and substrings of
any matches, or empty values if there are none.
The matched pattern PAT can include any of the standard regex
operators, including:
‘.’
Match any character
‘* + ? {}’
Repetition operators, representing
‘*’
Match zero or more times
‘+’
Match one or more times
‘?’
Match zero or one times
‘{N}’
Match exactly N times
‘{N,}’
Match N or more times
‘{M,N}’
Match between M and N times
‘[...] [^...]’
List operators. The pattern will match any character listed
between "[" and "]". If the first character is "^" then the
pattern is inverted and any character except those listed
between brackets will match.
Escape sequences defined below can also be used inside list
operators. For example, a template for a floating point
number might be ‘[-+.\d]+’.
‘() (?:)’
Grouping operator. The first form, parentheses only, also
creates a token.
‘|’
Alternation operator. Match one of a choice of regular
expressions. The alternatives must be delimited by the
grouping operator ‘()’ above.
‘^ $’
Anchoring operators. Requires pattern to occur at the start
(‘^’) or end (‘$’) of the string.
In addition, the following escaped characters have special meaning.
‘\d’
Match any digit
‘\D’
Match any non-digit
‘\s’
Match any whitespace character
‘\S’
Match any non-whitespace character
‘\w’
Match any word character
‘\W’
Match any non-word character
‘\<’
Match the beginning of a word
‘\>’
Match the end of a word
‘\B’
Match within a word
Implementation Note: For compatibility with MATLAB, escape
sequences in PAT (e.g., "\n" => newline) are expanded even when PAT
has been defined with single quotes. To disable expansion use a
second backslash before the escape sequence (e.g., "\\n") or use
the ‘regexptranslate’ function.
The outputs of ‘regexp’ default to the order given below
S
The start indices of each matching substring
E
The end indices of each matching substring
TE
The extents of each matched token surrounded by ‘(...)’ in PAT
M
A cell array of the text of each match
T
A cell array of the text of each token matched
NM
A structure containing the text of each matched named token,
with the name being used as the fieldname. A named token is
denoted by ‘(?<name>...)’.
SP
A cell array of the text not returned by match, i.e., what
remains if you split the string based on PAT.
Particular output arguments, or the order of the output arguments,
can be selected by additional OPT arguments. These are strings and
the correspondence between the output arguments and the optional
argument are
’start’ S
’end’ E
’tokenExtents’ TE
’match’ M
’tokens’ T
’names’ NM
’split’ SP
Additional arguments are summarized below.
‘once’
Return only the first occurrence of the pattern.
‘matchcase’
Make the matching case sensitive. (default)
Alternatively, use (?-i) in the pattern.
‘ignorecase’
Ignore case when matching the pattern to the string.
Alternatively, use (?i) in the pattern.
‘stringanchors’
Match the anchor characters at the beginning and end of the
string. (default)
Alternatively, use (?-m) in the pattern.
‘lineanchors’
Match the anchor characters at the beginning and end of the
line.
Alternatively, use (?m) in the pattern.
‘dotall’
The pattern ‘.’ matches all characters including the newline
character. (default)
Alternatively, use (?s) in the pattern.
‘dotexceptnewline’
The pattern ‘.’ matches all characters except the newline
character.
Alternatively, use (?-s) in the pattern.
‘literalspacing’
All characters in the pattern, including whitespace, are
significant and are used in pattern matching. (default)
Alternatively, use (?-x) in the pattern.
‘freespacing’
The pattern may include arbitrary whitespace and also comments
beginning with the character ‘#’.
Alternatively, use (?x) in the pattern.
‘noemptymatch’
Zero-length matches are not returned. (default)
‘emptymatch’
Return zero-length matches.
‘regexp ('a', 'b*', 'emptymatch')’ returns ‘[1 2]’ because
there are zero or more ’b’ characters at positions 1 and
end-of-string.
Stack Limitation Note: Pattern searches are done with a recursive
function which can overflow the program stack when there are a high
number of matches. For example,
regexp (repmat ('a', 1, 1e5), '(a)+')
may lead to a segfault. As an alternative, consider constructing
pattern searches that reduce the number of matches (e.g., by
creatively using set complement), and then further processing the
return variables (now reduced in size) with successive ‘regexp’
searches.
See also: regexpi XREFregexpi, strfind XREFstrfind,
regexprep XREFregexprep.
-- : [S, E, TE, M, T, NM, SP] = regexpi (STR, PAT)
-- : [...] = regexpi (STR, PAT, "OPT1", ...)
Case insensitive regular expression string matching.
Search for PAT in STR and return the positions and substrings of
any matches, or empty values if there are none. regexp
XREFregexp, for details on the syntax of the search pattern.
See also: regexp XREFregexp.
-- : OUTSTR = regexprep (STRING, PAT, REPSTR)
-- : OUTSTR = regexprep (STRING, PAT, REPSTR, "OPT1", ...)
Replace occurrences of pattern PAT in STRING with REPSTR.
The pattern is a regular expression as documented for ‘regexp’.
regexp XREFregexp.
The replacement string may contain ‘$i’, which substitutes for the
ith set of parentheses in the match string. For example,
regexprep ("Bill Dunn", '(\w+) (\w+)', '$2, $1')
returns "Dunn, Bill"
Options in addition to those of ‘regexp’ are
‘once’
Replace only the first occurrence of PAT in the result.
‘warnings’
This option is present for compatibility but is ignored.
Implementation Note: For compatibility with MATLAB, escape
sequences in PAT (e.g., "\n" => newline) are expanded even when PAT
has been defined with single quotes. To disable expansion use a
second backslash before the escape sequence (e.g., "\\n") or use
the ‘regexptranslate’ function.
See also: regexp XREFregexp, regexpi XREFregexpi,
strrep XREFstrrep.
-- : regexptranslate (OP, S)
Translate a string for use in a regular expression.
This may include either wildcard replacement or special character
escaping.
The behavior is controlled by OP which can take the following
values
"wildcard"
The wildcard characters ‘.’, ‘*’, and ‘?’ are replaced with
wildcards that are appropriate for a regular expression. For
example:
regexptranslate ("wildcard", "*.m")
⇒ '.*\.m'
"escape"
The characters ‘$.?[]’, that have special meaning for regular
expressions are escaped so that they are treated literally.
For example:
regexptranslate ("escape", "12.5")
⇒ '12\.5'
See also: regexp XREFregexp, regexpi XREFregexpi,
regexprep XREFregexprep.
-- : untabify (T)
-- : untabify (T, TW)
-- : untabify (T, TW, DEBLANK)
Replace TAB characters in T with spaces.
The input, T, may be either a 2-D character array, or a cell array
of character strings. The output is the same class as the input.
The tab width is specified by TW, and defaults to eight.
If the optional argument DEBLANK is true, then the spaces will be
removed from the end of the character data.
The following example reads a file and writes an untabified version
of the same file with trailing spaces stripped.
fid = fopen ("tabbed_script.m");
text = char (fread (fid, "uchar")');
fclose (fid);
fid = fopen ("untabified_script.m", "w");
text = untabify (strsplit (text, "\n"), 8, true);
fprintf (fid, "%s\n", text{:});
fclose (fid);
See also: strjust XREFstrjust, strsplit XREFstrsplit,
deblank XREFdeblank.
Info Catalog
octave: Comparing Strings
octave: Strings
octave: String Conversions