@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997, 2007, 2009 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Data Types
@chapter Data Types
@cindex 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.  @xref{Dynamically Linked
Functions}, for more information about Octave's dynamic linking
capabilities.  @ref{User-defined Data Types} describes what you must do
to define a new data type for Octave.

@c ov-typeinfo.cc
@anchor{doc-typeinfo}
@deftypefn {Built-in Function} {} typeinfo (@var{expr})

Return the type of the expression @var{expr}, as a string.  If
@var{expr} is omitted, return an array of strings containing all the
currently installed data types.
@end deftypefn


@menu
* Built-in Data Types::         
* User-defined Data Types::     
* Object Sizes::                
@end menu

@node Built-in Data Types
@section Built-in Data Types
@cindex data types, built-in
@cindex 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.

@c ov-class.cc
@anchor{doc-class}
@deftypefn {Built-in Function} {} class (@var{expr})
@deftypefnx {Built-in Function} {} class (@var{s}, @var{id})
@deftypefnx {Built-in Function} {} class (@var{s}, @var{id}, @var{p}, @dots{})
Return the class of the expression @var{expr} or create a class with
fields from structure @var{s} and name (string) @var{id}.  Additional
arguments name a list of parent classes from which the new class is
derived.
@end deftypefn


@c ./general/isa.m
@anchor{doc-isa}
@deftypefn {Function File} {} isa (@var{x}, @var{class})
Return true if @var{x} is a value from the class @var{class}.
@end deftypefn


@c ./miscellaneous/cast.m
@anchor{doc-cast}
@deftypefn {Function File} {} cast (@var{val}, @var{type})
Convert @var{val} to data type @var{type}.
@seealso{@ref{doc-int8,,int8}, @ref{doc-uint8,,uint8}, @ref{doc-int16,,int16}, @ref{doc-uint16,,uint16}, @ref{doc-int32,,int32}, @ref{doc-uint32,,uint32}, @ref{doc-int64,,int64}, @ref{doc-uint64,,uint64}, @ref{doc-double,,double}}
@end deftypefn


@c ./DLD-FUNCTIONS/typecast.cc
@anchor{doc-typecast}
@deftypefn {Loadable Function} {} typecast (@var{x}, @var{type})
Convert from one datatype to another without changing the underlying
data.  The argument @var{type} defines the type of the return argument
and must be one of 'uint8', 'uint16', 'uint32', 'uint64', 'int8', 'int16',
'int32', 'int64', 'single' or 'double'.

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

@example
@group
@var{x} = uint16 ([1, 65535]);
typecast (@var{x}, 'uint8')
@result{} [   0,   1, 255, 255]
@end group
@end example
@seealso{@ref{doc-cast,,cast}, @ref{doc-swapbytes,,swapbytes}}
@end deftypefn


@c ./miscellaneous/swapbytes.m
@anchor{doc-swapbytes}
@deftypefn {Function File} {} swapbytes (@var{x})
Swaps the byte order on values, converting from little endian to big 
endian and vice versa.  For example

@example
@group
swapbytes (uint16 (1:4))
@result{} [   256   512   768  1024]
@end group
@end example

@seealso{@ref{doc-typecast,,typecast}, @ref{doc-cast,,cast}}
@end deftypefn


@menu
* Numeric Objects::             
* Missing Data::                
* String Objects::              
* Data Structure Objects::      
* Cell Array Objects::          
@end menu

@node Numeric Objects
@subsection Numeric Objects
@cindex numeric constant
@cindex numeric value

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
@tex
 $2.2251\times10^{-308}$ to $1.7977\times10^{308}$
@end tex
@ifnottex
 2.2251e-308 to 1.7977e+308
@end ifnottex
 can be stored, and the relative precision is approximately
@tex
 $2.2204\times10^{-16}$.
@end tex
@ifnottex
 2.2204e-16.
@end ifnottex
The exact values are given by the variables @code{realmin},
@code{realmax}, and @code{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.  @xref{Index Expressions}.

@xref{Numeric Data Types}, for more information.

@node Missing Data
@subsection Missing Data
@cindex missing data

It is possible to represent missing data explicitly in Octave using
@code{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 @code{NaN}.

@c data.cc
@anchor{doc-NA}
@deftypefn  {Built-in Function} {} NA
@deftypefnx {Built-in Function} {} NA (@var{n})
@deftypefnx {Built-in Function} {} NA (@var{n}, @var{m})
@deftypefnx {Built-in Function} {} NA (@var{n}, @var{m}, @var{k}, @dots{})
@deftypefnx {Built-in Function} {} NA (@dots{}, @var{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 @code{isna} function.

When called with no arguments, return a scalar with the value @samp{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.
The optional argument @var{class} specifies the return type and may be
either "double" or "single".
@seealso{@ref{doc-isna,,isna}}
@end deftypefn


@c mappers.cc
@anchor{doc-isna}
@deftypefn {Mapping Function} {} isna (@var{x})
Return 1 for elements of @var{x} that are NA (missing) values and zero
otherwise.  For example,

@example
@group
isna ([13, Inf, NA, NaN])
     @result{} [ 0, 0, 1, 0 ]
@end group
@end example
@seealso{@ref{doc-isnan,,isnan}}
@end deftypefn


@node String Objects
@subsection String Objects
@cindex strings
@cindex character strings
@opindex "
@opindex '

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.

@xref{Strings}, for more information.

@node Data Structure Objects
@subsection Data Structure Objects
@cindex structures
@cindex data structures

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.

@xref{Data Structures}, for more information.

@node Cell Array Objects
@subsection Cell Array Objects
@cindex cell arrays

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

@xref{Cell Arrays}, for more information.

@node User-defined Data Types
@section User-defined Data Types
@cindex user-defined data types
@cindex data types, user-defined

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 @file{ov.h}, @file{ops.h}, and related files from Octave's
@file{src} directory.

@node Object Sizes
@section 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
@minus{}1 when the operation doesn't make sense.  For example, Octave's
data structure type doesn't have rows or columns, so the @code{rows} and
@code{columns} functions return @minus{}1 for structure arguments.

@c data.cc
@anchor{doc-ndims}
@deftypefn {Built-in Function} {} ndims (@var{a})
Returns the number of dimensions of array @var{a}.
For any array, the result will always be larger than or equal to 2.
Trailing singleton dimensions are not counted.
@end deftypefn


@c data.cc
@anchor{doc-columns}
@deftypefn {Built-in Function} {} columns (@var{a})
Return the number of columns of @var{a}.
@seealso{@ref{doc-size,,size}, @ref{doc-numel,,numel}, @ref{doc-rows,,rows}, @ref{doc-length,,length}, @ref{doc-isscalar,,isscalar}, @ref{doc-isvector,,isvector}, @ref{doc-ismatrix,,ismatrix}}
@end deftypefn


@c data.cc
@anchor{doc-rows}
@deftypefn {Built-in Function} {} rows (@var{a})
Return the number of rows of @var{a}.
@seealso{@ref{doc-size,,size}, @ref{doc-numel,,numel}, @ref{doc-columns,,columns}, @ref{doc-length,,length}, @ref{doc-isscalar,,isscalar}, @ref{doc-isvector,,isvector}, @ref{doc-ismatrix,,ismatrix}}
@end deftypefn


@c data.cc
@anchor{doc-numel}
@deftypefn {Built-in Function} {} numel (@var{a})
Returns the number of elements in the object @var{a}.
@seealso{@ref{doc-size,,size}}
@end deftypefn


@c data.cc
@anchor{doc-length}
@deftypefn {Built-in Function} {} length (@var{a})
Return the `length' of the object @var{a}.  For matrix objects, the
length is the number of rows or columns, whichever is greater (this
odd definition is used for compatibility with @sc{matlab}).
@end deftypefn


@c data.cc
@anchor{doc-size}
@deftypefn {Built-in Function} {} size (@var{a}, @var{n})
Return the number rows and columns of @var{a}.

With one input argument and one output argument, the result is returned
in a row vector.  If there are multiple output arguments, the number of
rows is assigned to the first, and the number of columns to the second,
etc.  For example,

@example
@group
size ([1, 2; 3, 4; 5, 6])
     @result{} [ 3, 2 ]

[nr, nc] = size ([1, 2; 3, 4; 5, 6])
     @result{} nr = 3
     @result{} nc = 2
@end group
@end example

If given a second argument, @code{size} will return the size of the
corresponding dimension.  For example

@example
@group
size ([1, 2; 3, 4; 5, 6], 2)
     @result{} 2
@end group
@end example

@noindent
returns the number of columns in the given matrix.
@seealso{@ref{doc-numel,,numel}}
@end deftypefn


@c data.cc
@anchor{doc-isempty}
@deftypefn {Built-in Function} {} isempty (@var{a})
Return 1 if @var{a} is an empty matrix (either the number of rows, or
the number of columns, or both are zero).  Otherwise, return 0.
@end deftypefn


@c ov-null-mat.cc
@anchor{doc-isnull}
@deftypefn {Built-in Function} {} isnull (@var{x})
Return 1 if @var{x} is a special null matrix, string or single quoted string.
Indexed assignment with such a value as right-hand side should delete array elements.
This function should be used when overloading indexed assignment for user-defined 
classes instead of @code{isempty}, to distinguish the cases:
@table @asis
@item @code{A(I) = []}
This should delete elements if @code{I} is nonempty.
@item @code{X = []; A(I) = X}
This should give an error if @code{I} is nonempty.
@end table
@end deftypefn


@c ov.cc
@anchor{doc-sizeof}
@deftypefn {Built-in Function} {} sizeof (@var{val})
Return the size of @var{val} in bytes
@end deftypefn


@c data.cc
@anchor{doc-size_equal}
@deftypefn {Built-in Function} {} size_equal (@var{a}, @var{b}, @dots{})
Return true if the dimensions of all arguments agree.
Trailing singleton dimensions are ignored.
Called with a single argument, size_equal returns true.
@seealso{@ref{doc-size,,size}, @ref{doc-numel,,numel}}
@end deftypefn


@c data.cc
@anchor{doc-squeeze}
@deftypefn {Built-in Function} {} squeeze (@var{x})
Remove singleton dimensions from @var{x} and return the result.
Note that for compatibility with @sc{matlab}, all objects have
a minimum of two dimensions and row vectors are left unchanged.
@end deftypefn