Octave Data Types
* Menu:
* Built-in Data Types::
* User-defined Data Types::
* Object Sizes::
Built-in Data Types
===================
The standard built-in data types are real and complex scalars and
matrices, ranges, character strings, and a data structure type.
Additional built-in data types may be added in future versions. If you
need a specialized data type that is not currently provided as a
built-in type, you are encouraged to write your own user-defined data
type and contribute it for distribution in a future release of Octave.
* Menu:
* Numeric Objects::
* String Objects::
* Data Structure Objects::
Numeric Objects
---------------
Octave's built-in numeric objects include real and complex scalars
and matrices. All built-in numeric data is currently stored as double
precision numbers. On systems that use the IEEE floating point format,
values in the range of approximately 2.2251e-308 to 1.7977e+308 can
be stored, and the relative precision is approximately 2.2204e-16.
The exact values are given by the variables `realmin', `realmax', and
`eps', respectively.
Matrix objects can be of any size, and can be dynamically reshaped
and resized. It is easy to extract individual rows, columns, or
submatrices using a variety of powerful indexing features. *Note Index
Expressions::.
*Note Numeric Data Types::, for more information.
String Objects
--------------
A character string in Octave consists of a sequence of characters
enclosed in either double-quote or single-quote marks. Internally,
Octave currently stores strings as matrices of characters. All the
indexing operations that work for matrix objects also work for strings.
*Note Strings::, for more information.
Data Structure Objects
----------------------
Octave's data structure type can help you to organize related
objects of different types. The current implementation uses an
associative array with indices limited to strings, but the syntax is
more like C-style structures.
*Note Data Structures::, for more information.
User-defined Data Types
=======================
Someday I hope to expand this to include a complete description of
Octave's mechanism for managing user-defined data types. Until this
feature is documented here, you will have to make do by reading the code
in the `ov.h', `ops.h', and related files from Octave's `src' directory.
Object Sizes
============
The following functions allow you to determine the size of a
variable or expression. These functions are defined for all objects.
They return -1 when the operation doesn't make sense. For example,
Octave's data structure type doesn't have rows or columns, so the
`rows' and `columns' functions return -1 for structure arguments.
- Function File: columns (A)
Return the number of columns of A.
- Function File: rows (A)
Return the number of rows of A.
- Built-in Function: length (A)
Return the `lenghth' of the object A. For matrix objects, the
length is the number of rows or columns, whichever is greater (this
odd definition is used for compatibility with Matlab).
- Built-in Function: size (A, N)
Return the number rows and columns of A.
With one input argument and one output argument, the result is
returned in a 2 element row vector. If there are two output
arguments, the number of rows is assigned to the first, and the
number of columns to the second. For example,
size ([1, 2; 3, 4; 5, 6])
=> [ 3, 2 ]
[nr, nc] = size ([1, 2; 3, 4; 5, 6])
=> nr = 3
=> nc = 2
If given a second argument of either 1 or 2, `size' will return
only the row or column dimension. For example
size ([1, 2; 3, 4; 5, 6], 2)
=> 2
returns the number of columns in the given matrix.
- Built-in Function: isempty (A)
Return 1 if A is an empty matrix (either the number of rows, or
the number of columns, or both are zero). Otherwise, return 0.
Numeric Data Types
******************
A "numeric constant" may be a scalar, a vector, or a matrix, and it
may contain complex values.
The simplest form of a numeric constant, a scalar, is a single number
that can be an integer, a decimal fraction, a number in scientific
(exponential) notation, or a complex number. Note that all numeric
constants are represented within Octave in double-precision floating
point format (complex constants are stored as pairs of double-precision
floating point values). Here are some examples of real-valued numeric
constants, which all have the same value:
105
1.05e+2
1050e-1
To specify complex constants, you can write an expression of the form
3 + 4i
3.0 + 4.0i
0.3e1 + 40e-1i
all of which are equivalent. The letter `i' in the previous example
stands for the pure imaginary constant, defined as `sqrt (-1)'.
For Octave to recognize a value as the imaginary part of a complex
constant, a space must not appear between the number and the `i'. If
it does, Octave will print an error message, like this:
octave:13> 3 + 4 i
parse error:
3 + 4 i
^
You may also use `j', `I', or `J' in place of the `i' above. All
four forms are equivalent.
* Menu:
* Matrices::
* Ranges::
* Logical Values::
* Predicates for Numeric Objects::
Matrices
========
It is easy to define a matrix of values in Octave. The size of the
matrix is determined automatically, so it is not necessary to explicitly
state the dimensions. The expression
a = [1, 2; 3, 4]
results in the matrix
/ \
| 1 2 |
a = | |
| 3 4 |
\ /
Elements of a matrix may be arbitrary expressions, provided that the
dimensions all make sense when combining the various pieces. For
example, given the above matrix, the expression
[ a, a ]
produces the matrix
ans =
1 2 1 2
3 4 3 4
but the expression
[ a, 1 ]
produces the error
error: number of rows must match near line 13, column 6
(assuming that this expression was entered as the first thing on line
13, of course).
Inside the square brackets that delimit a matrix expression, Octave
looks at the surrounding context to determine whether spaces and newline
characters should be converted into element and row separators, or
simply ignored, so commands like
[ linspace (1, 2) ]
and
a = [ 1 2
3 4 ]
will work. However, some possible sources of confusion remain. For
example, in the expression
[ 1 - 1 ]
the `-' is treated as a binary operator and the result is the scalar 0,
but in the expression
[ 1 -1 ]
the `-' is treated as a unary operator and the result is the vector `[
1, -1 ]'.
Given `a = 1', the expression
[ 1 a' ]
results in the single quote character `'' being treated as a transpose
operator and the result is the vector `[ 1, 1 ]', but the expression
[ 1 a ' ]
produces the error message
error: unterminated string constant
because to not do so would make it impossible to correctly parse the
valid expression
[ a 'foo' ]
For clarity, it is probably best to always use commas and semicolons
to separate matrix elements and rows. It is possible to enforce this
style by setting the built-in variable `whitespace_in_literal_matrix' to
`"ignore"'.
- Built-in Variable: whitespace_in_literal_matrix
Control auto-insertion of commas and semicolons in literal
matrices.
- Built-in Variable: warn_separator_insert
Print warning if commas or semicolons might be inserted
automatically in literal matrices.
When you type a matrix or the name of a variable whose value is a
matrix, Octave responds by printing the matrix in with neatly aligned
rows and columns. If the rows of the matrix are too large to fit on the
screen, Octave splits the matrix and displays a header before each
section to indicate which columns are being displayed. You can use the
following variables to control the format of the output.
- Built-in Variable: output_max_field_width
This variable specifies the maximum width of a numeric output
field. The default value is 10.
- Built-in Variable: output_precision
This variable specifies the minimum number of significant figures
to display for numeric output. The default value is 5.
It is possible to achieve a wide range of output styles by using
different values of `output_precision' and `output_max_field_width'.
Reasonable combinations can be set using the `format' function. *Note
Basic Input and Output::.
- Built-in Variable: split_long_rows
For large matrices, Octave may not be able to display all the
columns of a given row on one line of your screen. This can
result in missing information or output that is nearly impossible
to decipher, depending on whether your terminal truncates or wraps
long lines.
If the value of `split_long_rows' is nonzero, Octave will display
the matrix in a series of smaller pieces, each of which can fit
within the limits of your terminal width. Each set of rows is
labeled so that you can easily see which columns are currently
being displayed. For example:
octave:13> rand (2,10)
ans =
Columns 1 through 6:
0.75883 0.93290 0.40064 0.43818 0.94958 0.16467
0.75697 0.51942 0.40031 0.61784 0.92309 0.40201
Columns 7 through 10:
0.90174 0.11854 0.72313 0.73326
0.44672 0.94303 0.56564 0.82150
The default value of `split_long_rows' is nonzero.
Octave automatically switches to scientific notation when values
become very large or very small. This guarantees that you will see
several significant figures for every value in a matrix. If you would
prefer to see all values in a matrix printed in a fixed point format,
you can set the built-in variable `fixed_point_format' to a nonzero
value. But doing so is not recommended, because it can produce output
that can easily be misinterpreted.
- Built-in Variable: fixed_point_format
If the value of this variable is nonzero, Octave will scale all
values in a matrix so that the largest may be written with one
leading digit. The scaling factor is printed on the first line of
output. For example,
octave:1> logspace (1, 7, 5)'
ans =
1.0e+07 *
0.00000
0.00003
0.00100
0.03162
1.00000
Notice that first value appears to be zero when it is actually 1.
For this reason, you should be careful when setting
`fixed_point_format' to a nonzero value.
The default value of `fixed_point_format' is 0.
* Menu:
* Empty Matrices::
Empty Matrices
--------------
A matrix may have one or both dimensions zero, and operations on
empty matrices are handled as described by Carl de Boor in `An Empty
Exercise', SIGNUM, Volume 25, pages 2-6, 1990 and C. N. Nett and W. M.
Haddad, in `A System-Theoretic Appropriate Realization of the Empty
Matrix Concept', IEEE Transactions on Automatic Control, Volume 38,
Number 5, May 1993. Briefly, given a scalar S, an M by N matrix
`M(mxn)', and an M by N empty matrix `[](mxn)' (with either one or both
dimensions equal to zero), the following are true:
s * [](mxn) = [](mxn) * s = [](mxn)
[](mxn) + [](mxn) = [](mxn)
[](0xm) * M(mxn) = [](0xn)
M(mxn) * [](nx0) = [](mx0)
[](mx0) * [](0xn) = 0(mxn)
By default, dimensions of the empty matrix are printed along with the
empty matrix symbol, `[]'. The built-in variable
`print_empty_dimensions' controls this behavior.
- Built-in Variable: print_empty_dimensions
If the value of `print_empty_dimensions' is nonzero, the
dimensions of empty matrices are printed along with the empty
matrix symbol, `[]'. For example, the expression
zeros (3, 0)
will print
ans = [](3x0)
Empty matrices may also be used in assignment statements as a
convenient way to delete rows or columns of matrices. *Note Assignment
Expressions: Assignment Ops.
Octave will normally issue a warning if it finds an empty matrix in
the list of elements that make up another matrix. You can use the
variable `empty_list_elements_ok' to suppress the warning or to treat
it as an error.
- Built-in Variable: empty_list_elements_ok
This variable controls whether Octave ignores empty matrices in a
matrix list.
For example, if the value of `empty_list_elements_ok' is nonzero,
Octave will ignore the empty matrices in the expression
a = [1, [], 3, [], 5]
and the variable `a' will be assigned the value `[ 1, 3, 5 ]'.
The default value is `"warn"'.
When Octave parses a matrix expression, it examines the elements of
the list to determine whether they are all constants. If they are, it
replaces the list with a single matrix constant.
- Built-in Variable: propagate_empty_matrices
If the value of `propagate_empty_matrices' is nonzero, functions
like `inverse' and `svd' will return an empty matrix if they are
given one as an argument. The default value is 1.
Ranges
======
A "range" is a convenient way to write a row vector with evenly
spaced elements. A range expression is defined by the value of the
first element in the range, an optional value for the increment between
elements, and a maximum value which the elements of the range will not
exceed. The base, increment, and limit are separated by colons (the
`:' character) and may contain any arithmetic expressions and function
calls. If the increment is omitted, it is assumed to be 1. For
example, the range
1 : 5
defines the set of values `[ 1, 2, 3, 4, 5 ]', and the range
1 : 3 : 5
defines the set of values `[ 1, 4 ]'.
Although a range constant specifies a row vector, Octave does _not_
convert range constants to vectors unless it is necessary to do so.
This allows you to write a constant like `1 : 10000' without using
80,000 bytes of storage on a typical 32-bit workstation.
Note that the upper (or lower, if the increment is negative) bound on
the range is not always included in the set of values, and that ranges
defined by floating point values can produce surprising results because
Octave uses floating point arithmetic to compute the values in the
range. If it is important to include the endpoints of a range and the
number of elements is known, you should use the `linspace' function
instead (*note Special Utility Matrices::).
When Octave parses a range expression, it examines the elements of
the expression to determine whether they are all constants. If they
are, it replaces the range expression with a single range constant.
Logical Values
==============
- Built-in Variable: true
Logical true value.
- Built-in Variable: false
Logical false value.
Predicates for Numeric Objects
==============================
- Built-in Function: isnumeric (X)
Return nonzero if X is a numeric object.
- Built-in Function: isreal (X)
Return true if X is a real-valued numeric object.
- Built-in Function: is_complex (X)
Return true if X is a complex-valued numeric object.
- Built-in Function: is_matrix (A)
Return 1 if A is a matrix. Otherwise, return 0.
- Function File: is_vector (A)
Return 1 if A is a vector. Otherwise, return 0.
- Function File: is_scalar (A)
Return 1 if A is a scalar. Otherwise, return 0.
- Function File: is_square (X)
If X is a square matrix, then return the dimension of X.
Otherwise, return 0.
- Function File: is_symmetric (X, TOL)
If X is symmetric within the tolerance specified by TOL, then
return the dimension of X. Otherwise, return 0. If TOL is
omitted, use a tolerance equal to the machine precision.
- Built-in Functio: is_bool (X)
Return true if X is a boolean object.
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
(*note Arithmetic Ops::) 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, `''.
`\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'. *Note Numeric Data
Types::, for more information about creating matrices.
* Menu:
* Creating Strings::
* Searching and Replacing::
* String Conversions::
* Character Class Functions::
Creating Strings
================
- Function File: blanks (N)
Return a string of N blanks.
- Function File: int2str (N)
- Function File: num2str (X)
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' (*note Formatted
Output::).
- 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
- Built-in Function: setstr (X)
Convert a matrix to a string. Each element of the matrix is
converted to the corresponding ASCII character. For example,
setstr ([97, 98, 99])
=> "abc"
- 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"
- 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"
- 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.
- Built-in Function: isstr (A)
Return 1 if A is a string. Otherwise, return 0.
Searching and Replacing
=======================
- Function File: deblank (S)
Removes the trailing blanks from the string S.
- 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 ]
- 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.
- 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.
- 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"
- 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.
- 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"
- 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
==================
- Function File: bin2dec (S)
Return the decimal number corresponding to the binary number
represented by the string S. For example,
bin2dec ("1110")
=> 14
- 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"
- Function File: dec2hex (N)
Return the hexadecimal number corresponding to the nonnegative
decimal number N, as a string. For example,
dec2hex (2748)
=> "abc"
- Function File: hex2dec (S)
Return the decimal number corresponding to the hexadecimal number
stored in the string S. For example,
hex2dec ("12B")
=> 299
hex2dec ("12b")
=> 299
- Function File: str2num (S)
Convert the string S to a number.
- Mapping Function: toascii (S)
Return ASCII representation of S in a matrix. For example,
toascii ("ASCII")
=> [ 65, 83, 67, 73, 73 ]
- 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"
- 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"
- Built-in Function: do_string_escapes (STRING)
Convert special characters in STRING to their escaped forms.
- 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.
- 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"
- 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.
- 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 ]
- Mapping Function: isalnum (S)
Return 1 for characters that are letters or digits (`isalpha (A)'
or `isdigit (A)' is true).
- Mapping Function: isalpha (S)
Return true for characters that are letters (`isupper (A)' or
`islower ()' is true).
- Mapping Function: isascii (S)
Return 1 for characters that are ASCII (in the range 0 to 127
decimal).
- Mapping Function: iscntrl (S)
Return 1 for control characters.
- Mapping Function: isdigit (S)
Return 1 for characters that are decimal digits.
- Mapping Function: isgraph (S)
Return 1 for printable characters (but not the space character).
- Mapping Function: islower (S)
Return 1 for characters that are lower case letters.
- Mapping Function: isprint (S)
Return 1 for printable characters (including the space character).
- Mapping Function: ispunct (S)
Return 1 for punctuation characters.
- Mapping Function: isspace (S)
Return 1 for whitespace characters (space, formfeed, newline,
carriage return, tab, and vertical tab).
- Mapping Function: isupper (S)
Return 1 for upper case letters.
- Mapping Function: isxdigit (S)
Return 1 for characters that are hexadecimal digits.