@c Copyright (C) 1996-2025 The Octave Project Developers
@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
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License 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 <https://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{External Code Interface}, 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.

@DOCSTRING(typeinfo)

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

@DOCSTRING(class)

@DOCSTRING(isa)

@DOCSTRING(cast)

@DOCSTRING(typecast)

@DOCSTRING(swapbytes)

@DOCSTRING(bitpack)

@DOCSTRING(bitunpack)

@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
IEEE@tie{}754 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 NA (short
for ``@w{Not} @w{Available}'').  This is helpful in distinguishing between a
property of the data (i.e., some of it was not recorded) and calculations on
the data which generated an error (i.e., created NaN values).  In short, if you
do not get the result you expect is it your data or your algorithm?

The missing data marker is a special case of the representation of NaN.
Because of that, it can only be used with data represented by floating point
numbers---no integer, logical, or char values.

In general, use NA and the test @code{isna}, to describe the dataset or to
reduce the dataset to only valid entries.  Numerical calculations with NA will
generally "poison" the results and conclude with an output NA.  However, this
can not be guaranteed on all platforms and NA may be replaced by NaN.

Example 1 : Describing the dataset

@example
@group
data = [1, NA, 3];
percent_missing = 100 * sum (isna (data(:))) / numel (data);
printf ('%2.0f%% of the dataset is missing\n', percent_missing);
@print{} 33% of the dataset is missing
@end group
@end example

Example 2 : Restrict calculations to valid data

@example
@group
raw_data = [1, NA, 3];
printf ('mean of raw data is %.1f\n', mean (raw_data));
@print{} mean of raw data is NA
valid_data = raw_data (! isna (raw_data));
printf ('mean of valid data is %.1f\n', mean (valid_data));
@print{} mean of valid data is 2.0
@end group
@end example

@DOCSTRING(NA)

@DOCSTRING(isna)

@node String Objects
@subsection String Objects
@cindex strings
@cindex character strings
@opindex "
@opindex @code{'}

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

@DOCSTRING(ndims)

@DOCSTRING(columns)

@DOCSTRING(rows)

@DOCSTRING(numel)

@DOCSTRING(length)

@DOCSTRING(size)

@DOCSTRING(isempty)

@DOCSTRING(isnull)

@DOCSTRING(sizeof)

@DOCSTRING(size_equal)

@DOCSTRING(squeeze)