Strings

A string constant consists of a sequence of characters enclosed in either double-quote or single-quote marks. For example, both of the following expressions

"parrot"
'parrot'

represent the string whose contents are `parrot'. Strings in Octave can be of any length.

Since the single-quote mark is also used for the transpose operator (see section Arithmetic Operators) but double-quote marks have no other purpose in Octave, it is best to use double-quote marks to denote strings.

Some characters cannot be included literally in a string constant. You represent them instead with escape sequences, which are character sequences beginning with a backslash (`\').

One use of an escape sequence is to include a double-quote (single-quote) character in a string constant that has been defined using double-quote (single-quote) marks. Since a plain double-quote would end the string, you must use `\"' to represent a single double-quote character as a part of the string. The backslash character itself is another character that cannot be included normally. You must write `\\' to put one backslash in the string. Thus, the string whose contents are the two characters `"\' may be written "\"\\" or '"\\'. Similarly, the string whose contents are the two characters `'\' may be written '\'\\' or "'\\".

Another use of backslash is to represent unprintable characters such as newline. While there is nothing to stop you from writing most of these characters directly in a string constant, they may look ugly.

Here is a table of all the escape sequences used in Octave. They are the same as those used in the C programming language.

\\

Represents a literal backslash, `\'.

\"

Represents a literal double-quote character, `"'.

\'

Represents a literal single-quote character, `''.

\0

Represents the "nul" character, control-@, ASCII code 0.

\a

Represents the "alert" character, control-g, ASCII code 7.

\b

Represents a backspace, control-h, ASCII code 8.

\f

Represents a formfeed, control-l, ASCII code 12.

\n

Represents a newline, control-j, ASCII code 10.

\r

Represents a carriage return, control-m, ASCII code 13.

\t

Represents a horizontal tab, control-i, ASCII code 9.

\v

Represents a vertical tab, control-k, ASCII code 11.

Strings may be concatenated using the notation for defining matrices. For example, the expression

[ "foo" , "bar" , "baz" ]

produces the string whose contents are `foobarbaz'. See section Numeric Data Types, for more information about creating matrices.

Creating Strings

@anchor{doc-blanks}

Function File: blanks (n)

Return a string of n blanks.

@anchor{doc-char}

Built-in Function: char (x)

Built-in Function: char (cell_array)

Built-in Function: char (s1, s2, ...)

Create a string array from a numeric matrix, cell array, or list of

If the argument is a numeric matrix, each element of the matrix is converted to the corresponding ASCII character. For example,

setstr ([97, 98, 99])
     => "abc"

If the argument is a cell array of strings, the result is a string array with each element corresponding to one element of the cell array.

For multiple string arguments, the result is a string array with each element corresponding to the arguments.

The returned values are padded with blanks as needed to make each row of the string array have the same length.

@anchor{doc-int2str}

Function File: int2str (n)

Function File: num2str (x, precision)

Function File: num2str (x, format)

Convert a number to a string. These functions are not very flexible, but are provided for compatibility with MATLAB. For better control over the results, use sprintf (see section Formatted Output).

@anchor{doc-com2str}

Function File: com2str (zz, flg)

convert complex number to a string Inputs

zz

complex number

flg

format flag 0 (default): -1, 0, 1, 1i, 1 + 0.5i 1 (for use with zpout): -1, 0, + 1, + 1i, + 1 + 0.5i

@anchor{doc-strcat}

Function File: strcat (s1, s2, ...)

Return a string containing all the arguments concatenated. For example,

s = [ "ab"; "cde" ];
strcat (s, s, s)
=> "ab ab ab "
        "cdecdecde"

@anchor{doc-string_fill_char}

Built-in Variable: string_fill_char

The value of this variable is used to pad all strings in a string matrix to the same length. It should be a single character. The default value is " " (a single space). For example,

string_fill_char = "X";
[ "these"; "are"; "strings" ]
     => "theseXX"
        "areXXXX"
        "strings"

@anchor{doc-str2mat}

Function File: str2mat (s_1, ..., s_n)

Return a matrix containing the strings s_1, ..., s_n as its rows. Each string is padded with blanks in order to form a valid matrix.

Note: This function is modelled after MATLAB. In Octave, you can create a matrix of strings by [s_1; ...; s_n] even if the strings are not all the same length.

@anchor{doc-isstr}

Built-in Function: isstr (a)

Return 1 if a is a string. Otherwise, return 0.

Searching and Replacing

@anchor{doc-deblank}

Function File: deblank (s)

Removes the trailing blanks and nulls from the string s. If s is a matrix, deblank trims each row to the length of longest string.

@anchor{doc-findstr}

Function File: 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 nonzero, the returned vector can include overlapping positions (this is the default). For example,

findstr ("ababab", "a")
=> [ 1, 3, 5 ]
findstr ("abababa", "aba", 0)
=> [ 1, 5 ]

@anchor{doc-index}

Function File: index (s, t)

Return the position of the first occurrence of the string t in the string s, or 0 if no occurrence is found. For example,

index ("Teststring", "t")
=> 4

Note: This function does not work for arrays of strings.

@anchor{doc-rindex}

Function File: rindex (s, t)

Return the position of the last occurrence of the string t in the string s, or 0 if no occurrence is found. For example,

rindex ("Teststring", "t")
=> 6

Note: This function does not work for arrays of strings.

@anchor{doc-split}

Function File: split (s, t)

Divides the string s into pieces separated by t, returning the result in a string array (padded with blanks to form a valid matrix). For example,

split ("Test string", "t")
=> "Tes "
        " s  "
        "ring"

@anchor{doc-strcmp}

Function File: strcmp (s1, s2)

Compares two strings, returning 1 if they are the same, and 0 otherwise.

Note: For compatibility with MATLAB, Octave's strcmp function returns 1 if the strings are equal, and 0 otherwise. This is just the opposite of the corresponding C library function.

@anchor{doc-strrep}

Function File: strrep (s, x, y)

Replaces all occurrences of the substring x of the string s with the string y. For example,

strrep ("This is a test string", "is", "&%$")
=> "Th&%$ &%$ a test string"

@anchor{doc-substr}

Function File: substr (s, beg, len)

Return the substring of s which starts at character number beg and is len characters long.

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.

For example,

substr ("This is a test string", 6, 9)
=> "is a test"

Note: This function is patterned after AWK. You can get the same result by s (beg : (beg + len - 1)).

String Conversions

@anchor{doc-bin2dec}

Function File: hex2dec (s)

Return the decimal number corresponding to the binary number stored in the string s. For example,

hex2dec ("1110")
=> 14

If s is a string matrix, returns a column vector of converted numbers, one per row of s. Invalid rows evaluate to NaN.

@seealso{dec2hex, base2dec, dec2base, bin2dec, dec2bin}

@anchor{doc-dec2bin}

Function File: dec2bin (n)

Return a binary number corresponding the nonnegative decimal number n, as a string of ones and zeros. For example,

dec2bin (14)
=> "1110"

If n is a vector, returns a string matrix, one row per value, padded with leading zeros to the width of the largest value.

@seealso{bin2dec, dec2base, base2dec, hex2dec, dec2hex}

@anchor{doc-dec2hex}

Function File: dec2hex (n)

Return the hexadecimal string corresponding to the nonnegative integer n. For example,

dec2hex (2748)
=> "ABC"

If n is a vector, returns a string matrix, one row per value, padded with leading zeros to the width of the largest value.

@seealso{hex2dec, dec2base, base2dec, bin2dec, dec2bin}

@anchor{doc-hex2dec}

Function File: hex2dec (s)

Returns the integer corresponding to the hexadecimal number stored in the string s. For example,

hex2dec ("12B")
=> 299
hex2dec ("12b")
=> 299

If s is a string matrix, returns a column vector of converted numbers, one per row of s. Invalid rows evaluate to NaN.

@seealso{dec2hex, base2dec, dec2base, bin2dec, dec2bin}

@anchor{doc-dec2base}

Function File: dec2base (n, b)

Return a string of symbols in base b corresponding to the the nonnegative integer n.

dec2base (123, 3)
=> "11120"

If n is a vector, return a string matrix with one row per value, padded with leading zeros to the width of the largest value.

If b is a string then the characters of b are used as the symbols for the digits of n. Space (' ') may not be used as a symbol.

dec2base (123, "aei")
=> "eeeia"

@seealso{base2dec, dec2bin, bin2dec, hex2dec, dec2hex}

@anchor{doc-base2dec}

Function File: base2dec (s, b)

Convert s from a string of digits of base b into an integer.

base2dec ("11120", 3)
=> 123

If s is a matrix, returns a column vector with one value per row of s. If a row contains invalid symbols then the corresponding value will be NaN. Rows are right-justified before converting so that trailing spaces are ignored.

If b is a string, the characters of b are used as the symbols for the digits of s. Space (' ') may not be used as a symbol.

base2dec ("yyyzx", "xyz")
=> 123

@seealso{dec2base, dec2bin, bin2dec, hex2dec, dec2hex}

@anchor{doc-strjust}

Function File: strjust (s, ["left"|"right"|"center"])

Shift the non-blank text of s to the left, right or center of the string. If s is a string array, justify each string in the array. Null characters are replaced by blanks. If no justification is specified, then all rows are right-justified.

@anchor{doc-str2num}

Function File: str2num (s)

Convert the string s to a number.

@anchor{doc-toascii}

Mapping Function: toascii (s)

Return ASCII representation of s in a matrix. For example,

toascii ("ASCII")
     => [ 65, 83, 67, 73, 73 ]

@anchor{doc-tolower}

Mapping Function: tolower (s)

Return a copy of the string s, with each upper-case character replaced by the corresponding lower-case one; nonalphabetic characters are left unchanged. For example,

tolower ("MiXeD cAsE 123")
     => "mixed case 123"

@anchor{doc-toupper}

Built-in Function: toupper (s)

Return a copy of the string s, with each lower-case character replaced by the corresponding upper-case one; nonalphabetic characters are left unchanged. For example,

toupper ("MiXeD cAsE 123")
     => "MIXED CASE 123"

@anchor{doc-do_string_escapes}

Built-in Function: do_string_escapes (string)

Convert special characters in string to their escaped forms.

@anchor{doc-undo_string_escapes}

Built-in Function: undo_string_escapes (s)

Converts special characters in strings back to their escaped forms. For example, the expression

bell = "\a";

assigns the value of the alert character (control-g, ASCII code 7) to the string variable bell. If this string is printed, the system will ring the terminal bell (if it is possible). This is normally the desired outcome. However, sometimes it is useful to be able to print the original representation of the string, with the special characters replaced by their escape sequences. For example,

octave:13> undo_string_escapes (bell)
ans = \a

replaces the unprintable alert character with its printable representation.

@anchor{doc-implicit_num_to_str_ok}

Built-in Variable: implicit_num_to_str_ok

If the value of implicit_num_to_str_ok is nonzero, implicit conversions of numbers to their ASCII character equivalents are allowed when strings are constructed using a mixture of strings and numbers in matrix notation. Otherwise, an error message is printed and control is returned to the top level. The default value is 0. For example,

[ "f", 111, 111 ]
     => "foo"

@anchor{doc-implicit_str_to_num_ok}

Built-in Variable: implicit_str_to_num_ok

If the value of implicit_str_to_num_ok is nonzero, implicit conversions of strings to their numeric ASCII equivalents are allowed. Otherwise, an error message is printed and control is returned to the top level. The default value is 0.

@anchor{doc-warn_single_quote_string}

Built-in Variable: warn_single_quote_string

Print warning if a signle quote character is used to introduce a string constant.

Character Class Functions

Octave also provides the following character class test functions patterned after the functions in the standard C library. They all operate on string arrays and return matrices of zeros and ones. Elements that are nonzero indicate that the condition was true for the corresponding character in the string array. For example,

isalpha ("!Q@WERT^Y&")
     => [ 0, 1, 0, 1, 1, 1, 1, 0, 1, 0 ]

@anchor{doc-isalnum}

Mapping Function: isalnum (s)

Return 1 for characters that are letters or digits (isalpha (s) or isdigit (s) is true).

@anchor{doc-isalpha}

Mapping Function: isalpha (s)

Mapping Function: isletter (s)

Return true for characters that are letters (isupper (s) or islower (s) is true).

@anchor{doc-isascii}

Mapping Function: isascii (s)

Return 1 for characters that are ASCII (in the range 0 to 127 decimal).

@anchor{doc-iscntrl}

Mapping Function: iscntrl (s)

Return 1 for control characters.

@anchor{doc-isdigit}

Mapping Function: isdigit (s)

Return 1 for characters that are decimal digits.

@anchor{doc-isgraph}

Mapping Function: isgraph (s)

Return 1 for printable characters (but not the space character).

@anchor{doc-islower}

Mapping Function: islower (s)

Return 1 for characters that are lower case letters.

@anchor{doc-isprint}

Mapping Function: isprint (s)

Return 1 for printable characters (including the space character).

@anchor{doc-ispunct}

Mapping Function: ispunct (s)

Return 1 for punctuation characters.

@anchor{doc-isspace}

Mapping Function: isspace (s)

Return 1 for whitespace characters (space, formfeed, newline, carriage return, tab, and vertical tab).

@anchor{doc-isupper}

Mapping Function: isupper (s)

Return 1 for upper case letters.

@anchor{doc-isxdigit}

Mapping Function: isxdigit (s)

Return 1 for characters that are hexadecimal digits.

Go to the first, previous, next, last section, table of contents.