Data Types
**********

All versions of Octave include a number of built-in data types, including real and complex scalars and matrices, character strings, a data structure type, and an array that can contain all data types.

It is also possible to define new specialized data types by writing a small amount of C++ code.  On some systems, new data types can be loaded dynamically while Octave is running, so it is not necessary to recompile all of Octave just to add a new type.  See External Code Interface, for more information about Octave's dynamic linking capabilities. User-defined Data Types describes what you must do to define a new data type for Octave.

 -- TYPESTR =: typeinfo (EXPR)
 -- CSTR =: typeinfo ()

     Return the type of the expression EXPR, as a string.

     If EXPR is omitted, return a cell array of strings containing all the currently installed data types. class, isa

Built-in Data Types
===================

The standard built-in data types are real and complex scalars and matrices, ranges, character strings, a data structure type, and cell arrays.  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.

The data type of a variable can be determined and changed through the use of the following functions.

 -- CLASSNAME =: class (OBJ)
 -- CLS =: class (S, CLASSNAME)
 -- CLS =: class (S, CLASSNAME, PARENT1, ...)
     Return the class of the object OBJ, or create a class with fields from structure S and name (string) CLASSNAME.

     Additional arguments name a list of parent classes from which the new class is derived. typeinfo, isa

 -- TF =: isa (OBJ, CLASSNAME)
     Return true if OBJ is an object from the class CLASSNAME.

     CLASSNAME may also be one of the following class categories:

     "float"
          Floating point value comprising classes "double" and "single".

     "integer"
          Integer value comprising classes (u)int8, (u)int16, (u)int32, (u)int64.

     "numeric"
          Numeric value comprising either a floating point or integer value.

     If CLASSNAME is a cell array of string, a logical array of the same size is returned, containing true for each class to which OBJ belongs to.

     class, typeinfo

 -- Y =: cast (X, "TYPE")
 -- Y =: cast (X, "LIKE", VAR)
     Convert X to data type TYPE.

     The input X may be a scalar, vector, or matrix of a class that is convertible to the target class (see below).

     If a variable VAR is specified after "like", X is converted to the same data type and sparsity attribute.  If VAR is complex, X will be complex, too.

     VAR may be and TYPE may name any of the following built-in numeric classes:

          "double"
          "single"
          "logical"
          "char"
          "int8"
          "int16"
          "int32"
          "int64"
          "uint8"
          "uint16"
          "uint32"
          "uint64"

     The value X may be modified to fit within the range of the new type.

     Examples:

          cast (-5, "uint8")
             => 0
          cast (300, "int8")
             => 127

     Programming Note: This function relies on the object X having a conversion method named TYPE.  User-defined classes may implement only a subset of the full list of types shown above.  In that case, it may be necessary to call cast twice in order to reach the desired type. For example, the conversion to double is nearly always implemented, but the conversion to uint8 might not be.  In that case, the following code will work:

          cast (cast (USER_DEFINED_VAL, "double"), "uint8")

     typecast, int8, uint8, int16, uint16, int32, uint32, int64, uint64, double, single, logical, char, class, typeinfo

 -- Y =: typecast (X, "CLASS")
     Return a new array Y resulting from interpreting the data of X in memory as data of the numeric class CLASS.

     Both the class of X and CLASS must be one of the built-in numeric classes:

          "logical"
          "char"
          "int8"
          "int16"
          "int32"
          "int64"
          "uint8"
          "uint16"
          "uint32"
          "uint64"
          "double"
          "single"
          "double complex"
          "single complex"

     the last two are only used with CLASS; they indicate that a complex-valued result is requested.  Complex arrays are stored in memory as consecutive pairs of real numbers.  The sizes of integer types are given by their bit counts.  Both logical and char are typically one byte wide; however, this is not guaranteed by C++.  If your system is IEEE conformant, single and double will be 4 bytes and 8 bytes wide, respectively. "logical" is not allowed for CLASS.

     If the input is a row vector, the return value is a row vector, otherwise it is a column vector.

     If the bit length of X is not divisible by that of CLASS, an error occurs.

     An example of the use of typecast on a little-endian machine is

          X = uint16 ([1, 65535]);
          typecast (X, "uint8")
          => [   1,   0, 255, 255]

     cast, bitpack, bitunpack, swapbytes

 -- Y =: swapbytes (X)
     Swap the byte order on values, converting from little endian to big endian and vice versa.

     For example:

          swapbytes (uint16 (1:4))
          =>   256   512   768  1024

     typecast, cast

 -- Y =: bitpack (X, CLASS)
     Return a new array Y resulting from interpreting the logical array X as raw bit patterns for data of the numeric class CLASS.

     CLASS must be one of the built-in numeric classes:

          "double"
          "single"
          "double complex"
          "single complex"
          "char"
          "int8"
          "int16"
          "int32"
          "int64"
          "uint8"
          "uint16"
          "uint32"
          "uint64"

     The number of elements of X should be divisible by the bit length of CLASS.  If it is not, excess bits are discarded.  Bits come in increasing order of significance, i.e., x(1) is bit 0, x(2) is bit 1, etc.

     The result is a row vector if X is a row vector, otherwise it is a column vector. bitunpack, typecast

 -- Y =: bitunpack (X)
     Return a logical array Y corresponding to the raw bit patterns of X.

     X must belong to one of the built-in numeric classes:

          "double"
          "single"
          "char"
          "int8"
          "int16"
          "int32"
          "int64"
          "uint8"
          "uint16"
          "uint32"
          "uint64"

     The result is a row vector if X is a row vector; otherwise, it is a column vector. bitpack, typecast

Numeric Objects
---------------

Octave's built-in numeric objects include real, complex, and integer scalars and matrices.  All built-in floating point 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.  See Index Expressions.

See Numeric Data Types, for more information.

Missing Data
------------

It is possible to represent missing data explicitly in Octave using NA (short for ``Not Available'').  Missing data can only be represented when data is represented as floating point numbers.  In this case missing data is represented as a special case of the representation of NaN.

 -- VAL =: NA
 -- VAL =: NA (N)
 -- VAL =: NA (N, M)
 -- VAL =: NA (N, M, K, ...)
 -- VAL =: NA (..., "like", VAR)
 -- VAL =: NA (..., CLASS)
     Return a scalar, matrix, or N-dimensional array whose elements are all equal to the special constant used to designate missing values.

     Note that NA always compares not equal to NA (NA != NA). To find NA values, use the isna function.

     When called with no arguments, return a scalar with the value NA.

     When called with a single argument, return a square matrix with the dimension specified.

     When called with more than one scalar argument the first two arguments are taken as the number of rows and columns and any further arguments specify additional matrix dimensions.

     If a variable VAR is specified after "like", the output VAL will have the same data type, complexity, and sparsity as VAR.

     The optional argument CLASS specifies the return type and may be either "double" or "single". isna

 -- TF =: isna (X)
     Return a logical array which is true where the elements of X are NA (missing) values and false where they are not.

     For example:

          isna ([13, Inf, NA, NaN])
               => [ 0, 0, 1, 0 ]

     isnan, isinf, isfinite

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.

See 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.

See Structures, for more information.

Cell Array Objects
------------------

A Cell Array in Octave is general array that can hold any number of different data types.

See Cell Arrays, 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.

 -- N =: ndims (A)
     Return the number of dimensions of A.

     For any array, the result will always be greater than or equal to 2. Trailing singleton dimensions are not counted, i.e., trailing dimensions D greater than 2 for which size (A, D) = 1.

          ndims (ones (4, 1, 2, 1))
              => 3

     size

 -- NC =: columns (A)
     Return the number of columns of A.

     This is equivalent to size (A, 2). rows, size, length, numel, isscalar, isvector, ismatrix

 -- NR =: rows (A)
     Return the number of rows of A.

     This is equivalent to size (A, 1). columns, size, length, numel, isscalar, isvector, ismatrix

 -- N =: numel (A)
 -- N =: numel (A, IDX1, IDX2, ...)
     Return the number of elements in the object A.

     Optionally, if indices IDX1, IDX2, ... are supplied, return the number of elements that would result from the indexing

          A(IDX1, IDX2, ...)

     Note that the indices do not have to be scalar numbers.  For example,

          A = 1;
          B = ones (2, 3);
          numel (A, B)

     will return 6, as this is the number of ways to index with B. Or the index could be the string ":" which represents the colon operator.  For example,

          A = ones (5, 3);
          numel (A, 2, ":")

     will return 3 as the second row has three column entries.

     This method is also called when an object appears as lvalue with cs-list indexing, i.e., object{...} or object(...).field. size, length, ndims

 -- N =: length (A)
     Return the length of the object A.

     The length is 0 for empty objects, 1 for scalars, and the number of elements for vectors.  For matrix or N-dimensional objects, the length is the number of elements along the largest dimension (equivalent to max (size (A))). numel, size

 -- SZ =: size (A)
 -- DIM_SZ =: size (A, DIM)
 -- DIM_SZ =: size (A, D1, D2, ...)
 -- [ROWS, COLS, ..., DIM_N_SZ] =: size (...)
     Return a row vector with the size (number of elements) of each dimension for the object A.

     When given a second argument, DIM, return the size of the corresponding dimension.  If DIM is a vector, return each of the corresponding dimensions.  Multiple dimensions may also be specified as separate arguments.

     With a single output argument, size returns a row vector.  When called with multiple output arguments, size returns the size of dimension N in the Nth argument.  The number of rows, dimension 1, is returned in the first argument, the number of columns, dimension 2, is returned in the second argument, etc.  If there are more dimensions in A than there are output arguments, size returns the total number of elements in the remaining dimensions in the final output argument.  If the requested dimension DIM is greater than the number of dimensions in A, size returns 1 (not 0).

     Example 1: single row vector output

          size ([1, 2; 3, 4; 5, 6])
             => [ 3, 2 ]

     Example 2: number of elements in 2nd dimension (columns)

          size ([1, 2; 3, 4; 5, 6], 2)
              => 2

     Example 3: number of output arguments == number of dimensions

          [nr, nc] = size ([1, 2; 3, 4; 5, 6])
              => nr = 3
              => nc = 2

     Example 4: number of output arguments < number of dimensions

          [nr, remainder] = size (ones (2, 3, 4, 5))
              => nr = 2
              => remainder = 60

     Example 5: number of elements in dimension > number of actual dimensions

          sz4 = size (ones (2, 3), 4)
              => sz4 = 1

     numel, ndims, length, rows, columns, size_equal, common_size

 -- TF =: isempty (A)
     Return true if A is an empty object (any one of its dimensions is zero). isnull, isa

 -- TF =: isnull (X)
     Return true if X is a special null array, string, or single quoted string.

     Indexed assignment with such a null value on the right-hand side should delete array elements.  This function is used in place of isempty when overloading the indexed assignment method (subsasgn) for user-defined classes.  isnull is used to distinguish between these two cases:

     A(I) = []

     and

     X = []; A(I) = X

     In the first assignment, the right-hand side is [] which is a special null value.  As long as the index I is not empty, this code should delete elements from A rather than perform assignment.

     In the second assignment, the right-hand side is empty (because X is []), but it is not null.  This code should assign the empty value to elements in A.

     An example from Octave's built-in char class demonstrates the interpreter behavior when isnull is used correctly.

          str = "Hello World";
          nm = "Wally";
          str(7:end) = nm                # indexed assignment
            => str = Hello Wally
          str(7:end) = ""                # indexed deletion
            => str = Hello

     isempty, isindex

 -- SZ =: sizeof (VAL)
     Return the size of VAL in bytes. whos

 -- TF =: size_equal (A, B)
 -- TF =: size_equal (A, B, ...)
     Return true if the dimensions of all arguments agree.

     Trailing singleton dimensions are ignored.  When called with a single argument, or no argument, size_equal returns true. size, numel, ndims, common_size

 -- B =: squeeze (A)
     Remove singleton dimensions from A and return the result.

     Note that for compatibility with MATLAB, all objects have a minimum of two dimensions and row vectors are left unchanged. reshape