\input texinfo   @c -*-texinfo-*-
@comment This is part of the netCDF documentation. See COPYRIGHT file
@comment $Id: netcdf-cxx.texi,v 1.3 2008/08/06 17:01:13 dmh Exp $
@comment %**start of header
@setfilename netcdf-cxx.info
@settitle NetCDF C++ Interface Guide
@setchapternewpage odd
@setcontentsaftertitlepage
@c Combine the variable and function indices.
@synindex vr cp
@synindex fn cp
@c %**end of header

@c version.texi is automatically generated by automake and contains
@c defined variables VERSION, UPDATED, UPDATED-MONTH.
@include version-cxx.texi
@include defines.texi

@ifinfo
@dircategory netCDF scientific data format
@direntry
* netcdf-cxx: (netcdf-cxx).         @value{cxx-man}
@end direntry
@end ifinfo

@titlepage
@title @value{cxx-man}
@subtitle Class Documentation
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Russ Rew
@author Unidata Program Center
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnottex
@node Top, Introduction, (dir), (dir)
@top @value{cxx-man}

This document describes the netCDF C++ API. It applies to netCDF
version @value{VERSION} release of the software, but the C++ interface
still only supports the ``classic'' data model from the netCDF-3
release. This document was last updated in @value{UPDATED}.

The netCDF library provides an application- and machine-independent
interface to self-describing, array-oriented data.  It supports an
abstract view of such data as a collection of named variables and
their attributes, and provides high-level access to data that is
faithful to the abstraction.  This on-line document describes the C++
interface to netCDF.  This C++ interface is still based on the classic
data model supported by netCDF-3 software; it has not yet been updated
to the enhanced data model supported by netCDF-4.

The first part of this master menu lists the major nodes in this Info
document.  The rest of the menu lists all the lower level nodes in the
document.

For a complete description of the netCDF format and utilities see 
@ref{Top,, , netcdf, @value{n-man}}.

@end ifnottex

@menu
* Introduction::                
* NetCDF Classes::              
* Auxiliary Classes::           
* Combined Index::              

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Class Hierarchy::             
* Auxiliary Types and Constants::  

NetCDF Classes

* Class NcFile::                Files
* Class NcDim::                 Dimensions
* Class NcTypedComponent::      Operations common to variables and attributes
* Class NcVar::                 Variables
* Class NcAtt::                 Attributes

Auxiliary Classes

* Class NcValues::              
* Class NcError::               

@end detailmenu
@end menu

@node Introduction, NetCDF Classes, Top, Top
@unnumbered Introduction
@cindex requirements of C++ interface

The main requirements for the design of the C++ interface are:

@itemize @bullet
@item
to provide the functionality of the C interface;
@item
to provide type safety by eliminating all use of @code{void*} pointers; and
@item
to provide an interface that is simpler to use than the C interface.
@end itemize

Some of the features of the C++ interface are:

@itemize @bullet
@item
No IDs needed for netCDF's variables, dimensions, or attributes.
@item
No explicit open or close calls needed for netCDF files; a constructor
opens and a destructor closes a file.
@item
No need to specify types for creating attributes; they will have the
type of the value provided.
@item
No use of @code{void*}: values are type-checked.
@item
Less indirection is needed for dimensions and dimension sizes than with
the C interface.  A variable's dimensions can be provided as arguments 
when defining a variable.
@item
Code for data types is isolated to make the addition of new
types easier.
@item
No explicit @code{ncredef} or @code{ncendef} calls are needed for
switching between define and data modes.  Whenever a mode switch is
required, it happens implicitly.
@end itemize

The header file @file{netcdfcpp.h} must be included in source code files
using this interface.

This release provides some of the functionality of netCDF version 4,
but not for the enhanced data model introduced with netCDF-4.

This manual assumes familiarity with the netCDF User's Guide, where
the concepts of netCDF dimensions, variables, and attributes are
discussed.

@menu
* Class Hierarchy::             
* Auxiliary Types and Constants::  
@end menu

@node Class Hierarchy, Auxiliary Types and Constants, Introduction, Introduction
@unnumberedsec Class Hierarchy
@cindex class hierarchy

The class for netCDF file objects is @code{NcFile}.

The components of a netCDF file are dimensions, variables, and
attributes.  There is a class for each of these kinds of objects;
@code{NcDim}, @code{NcVar}, and @code{NcAtt}.  Variables and attributes
share some common characteristics that are factored out in the
abstract base class @code{NcTypedComponent}.

An auxiliary class, @code{NcValues}, provides a type for arrays of values
that are read from or written to netCDF files.  Another auxiliary class,
@code{NcError}, provides facilities for handling errors.

@example
@group
@code{NcFile}                     netCDF file

@code{NcDim}                      dimension

@code{NcTypedComponent}           abstract base class
        @code{NcVar}                variable
        @code{NcAtt}                attribute

@code{NcValues}                   abstract base class for array
        @code{NcValues_ncbyte}      array of bytes
        @code{NcValues_char}        array of characters
        @code{NcValues_short}       array of shorts
        @code{NcValues_int}         array of ints
        @code{NcValues_long}        array of longs
        @code{NcValues_float}       array of floats
        @code{NcValues_double}      array of doubles

@code{NcError}                    for error handling
@end group
@end example

@node Auxiliary Types and Constants,  , Class Hierarchy, Introduction
@unnumberedsec Auxiliary Types and Constants
@cindex auxiliary types and constants

The netCDF classes use several auxiliary types for arguments and return
types from member functions: @code{NcToken}, @code{NcType},
@code{NcBool}, and @code{ncbyte}.

@table @code
@vindex NcToken
@item NcToken
Used for names for netCDF objects, in particular variable names, dimension
names, and attribute names.  Currently this is just a typedef for
@code{const char*}.

@vindex NcType
@item NcType
Used for specifying netCDF external value types.  Currently this is an
enumerated type with the following legitimate values: @code{ncByte},
@code{ncChar}, @code{ncShort}, @code{ncInt}, @code{ncLong} (deprecated),
@code{ncFloat}, and @code{ncDouble}.

@vindex NcBool
@item NcBool
Used for the return type of some member functions.  If the member
function fails, 0 is returned, otherwise some non-zero value.  Currently
this is just a typedef for @code{unsigned int}.  It will be changed to
@code{bool} when all C++ compilers support the new @code{bool} type.

@vindex ncbyte
@item ncbyte
Used to declare values of type @code{ncByte}, for 8-bit integer data.
(This is currently a typedef for @code{unsigned char}, but it may be
changed to a typedef for @code{signed char}, so don't depend on the
underlying representation.)
@end table

@node NetCDF Classes, Auxiliary Classes, Introduction, Top
@unnumbered     NetCDF Classes

@menu
* Class NcFile::                Files
* Class NcDim::                 Dimensions
* Class NcTypedComponent::      Operations common to variables and attributes
* Class NcVar::                 Variables
* Class NcAtt::                 Attributes
@end menu

@vindex NcFile
@node Class NcFile, Class NcDim, NetCDF Classes, NetCDF Classes
@unnumberedsec Class NcFile

@code{NcFile} is the class for netCDF files,
providing methods for netCDF file operations.

Some member functions return pointers to dimensions (@code{NcDim}) or
variables (@code{NcVar}).  These objects are owned by the @code{NcFile}
they are associated with, and will be deleted automatically by the
@code{NcFile} destructor (or by the @code{close} member function, if
this is called earlier than the destructor), so users should not delete
these.  Member functions that return pointers to attributes
(@code{NcAtt}) pass ownership to the calling function; users
should delete attributes when they are finished with them.  

Member functions that return @code{NcBool} yield @code{TRUE} on success
and @code{FALSE} on failure.  Member functions that return a pointer
value return a @code{NULL} pointer on failure.

This class interface hides the distinction in the C and Fortran
interfaces between @dfn{define mode} (when dimensions, variables, or
attributes are being defined or renamed), and @dfn{data mode} (when data
values are being accessed), by automatically switching between the modes
when necessary.  Be aware that switching from accessing data to adding
or renaming dimensions, variables and attributes can be expensive, since
it may entail a copy of the data.

@unnumberedsubsec Public Member Functions

@table @code
@findex NcFile
@findex NcFile::NcFile
@item NcFile( const char * path, FileMode = ReadOnly, size_t *chunksizeptr = NULL, size_t initialsize = 0, FileFormat = Classic)

The constructor creates a new netCDF file or opens an existing netCDF
file.  
The path argument may be an OPenDAP DAP URL if DAP support is enabled.

The @code{FileMode} argument can be any of @code{ReadOnly} (the
default) to open an existing file for reading, @code{Write} to open an
existing file for reading or writing, @code{Replace} to create a new
empty file even if the named file already exists, or
@code{New} to create a new file only if the named file does not already
exist.

The optional @code{FileFormat} argument can be any of @code{Classic}
(the default), @code{Offset64Bits}, @code{Netcdf4}, or
@code{Netcdf4Classic}.

The optional @code{chunksizeptr} and @code{initialsize} tuning
parameters are as described in the corresponding @code{nc__create()}
function in the C interface.

The constructor will not fail, but in the case of a bad path name,
improper permissions, or if the file already exists and you have
specified @code{FileMode} as @code{New}, no netCDF file will be created
or opened.  If the constructor fails to create or open a netCDF file, a
subsequent call to the @code{is_valid()} member function will return
@code{False}.

@findex ~NcFile
@findex NcFile::~NcFile
@item ~NcFile( void )
Destructor.  The file is closed and all resources associated with it are
released, including the associated @code{NcVar} and @code{NcDim}
objects.  If you wish to close the file earlier, you may explicitly call
the @code{close} member function; a subsequent destructor call will work
properly.

@findex close
@findex NcFile::close
@item NcBool close( void )
Close netCDF file earlier than it would be closed by the @code{NcFile}
destructor.

@findex is_valid
@findex NcFile::is_valid
@item NcBool is_valid( void ) const
Returns @code{TRUE} if valid netCDF file, @code{FALSE} otherwise (e.g.
if constructor could not open file).

@findex num_dims
@findex NcFile::num_dims
@item int num_dims( void ) const
Returns the number of dimensions in the netCDF file.

@findex num_vars
@findex NcFile::num_vars
@item int num_vars( void ) const
Returns the number of variables in the netCDF file.

@findex num_atts
@findex NcFile::num_atts
@item int num_atts( void ) const
Returns the number of global attributes in the netCDF file.

@findex get_dim
@findex NcFile::get_dim
@item NcDim* get_dim(NcToken name) const
Get a dimension by name.

@findex get_var
@findex NcFile::get_var
@item NcVar* get_var(NcToken name) const
Get a variable by name.

@findex get_att
@findex NcFile::get_att
@item NcAtt* get_att(NcToken name) const
Get a global attribute by name.

@findex get_dim
@findex NcFile::get_dim
@item NcDim* get_dim(int n) const
Get the @var{n}th dimension (beginning with the 0th).

@findex get_var
@findex NcFile::get_var
@item NcVar* get_var(int n) const
Get the @var{n}th variable (beginning with the 0th).

@findex get_att
@findex NcFile::get_att
@item NcAtt* get_att(int n) const
Get the @var{n}th global attribute (beginning with the 0th).

@findex rec_dim
@findex NcFile::rec_dim
@item NcDim* rec_dim( void ) const
Get the unlimited dimension, if any.
@end table

The following @code{add_} member functions put the file in @dfn{define
mode}, so could be expensive.  To avoid copying of data, invoke
these before writing data to variables.

@table @code
@findex add_dim
@findex NcFile::add_dim
@item NcDim* add_dim(NcToken dimname)
Add an unlimited dimension named @code{dimname} to the netCDF file.

@findex add_dim
@findex NcFile::add_dim
@item NcDim* add_dim(NcToken dimname, long dimsize)
Add a dimension named @code{dimname} of size @code{dimsize}.

@findex add_var
@findex NcFile::add_var
@item NcVar* add_var(NcToken varname, NcType type, const NcDim*, @dots{})
Add a variable named @code{varname} of the specified type
(@code{ncByte}, @code{ncChar}, @code{ncShort}, @code{ncInt},
@code{ncFloat}, @code{ncDouble}) to the open netCDF file.  The variable
is defined with a shape that depends on how many
dimension arguments are provided.  A scalar variable would have 0
dimensions, a vector would have 1 dimension, and so on.  Supply as many
dimensions as needed, up to 5.  If more than 5 dimensions are required,
use the n-dimensional version of this member function instead.

@findex add_var
@findex NcFile::add_var
@item NcVar* add_var(NcToken varname, NcType type, int ndims, const NcDim** dims)
Add a variable named @code{varname} of @code{ndims} dimensions and of
the specified type.  This method must be used when dealing with
variables of more than 5 dimensions.

@findex add_att
@findex NcFile::add_att
@item  NcBool add_att(NcToken name, ncbyte val)
@itemx NcBool add_att(NcToken name, char val)
@itemx NcBool add_att(NcToken name, short val)
@itemx NcBool add_att(NcToken name, int val)
@itemx NcBool add_att(NcToken name, float val)
@itemx NcBool add_att(NcToken name, double val)
Add global scalar attributes of the specified name and with the
supplied value.

@item NcBool add_att(NcToken name, const char* val)
Add global string-valued attribute with the specified name and C string
value (terminated with a @code{\0} character).

@findex add_att
@findex NcFile::add_att
@item  NcBool add_att(NcToken name, int n, const ncbyte* val)
@itemx NcBool add_att(NcToken name, int n, const char* val)
@itemx NcBool add_att(NcToken name, int n, const short* val)
@itemx NcBool add_att(NcToken name, int n, const int* val)
@itemx NcBool add_att(NcToken name, int n, const float* val)
@itemx NcBool add_att(NcToken name, int n, const double* val)
Add global vector attributes with the specified name, length, and values.

@findex set_fill
@findex NcFile::set_fill
@item NcBool set_fill(FillMode mode = Fill)
Sets fill-mode to either @code{NcFile::Fill} or @code{NcFile::NoFill}.
Default is @code{Fill}, in which case unwritten values are pre-written
with appropriate type-specific or variable-specific fill values.

@findex get_fill
@findex NcFile::get_fill
@item enum NcFile::FillMode get_fill( void ) const
Returns fill mode of the file, either @code{NcFile::Fill} or
@code{NcFile::NoFill}.

@findex get_format
@findex NcFile::get_format
@item enum NcFile::FileFormat get_format( void ) const
Returns format version of the file, either @code{NcFile::Classic},
@code{NcFile:Offset64Bits}, @code{NcFile:Netcdf4}, or 
@code{NcFile::Netcdf4Classic}.

@findex sync
@findex NcFile::sync
@item NcBool sync( void )
Synchronizes file to disk.  This flushes buffers so that readers
of the file will see recent changes.

@findex abort
@findex NcFile::abort
@item NcBool abort( void )
Either just closes file (if recently it has been in data mode as the
result of accessing data), or backs out of the most recent sequence of
changes to the file schema (dimensions, variables, and attributes).
@end table

@vindex NcDim
@node Class NcDim, Class NcTypedComponent, Class NcFile, NetCDF Classes
@unnumberedsec  Class NcDim

A netCDF dimension has a name and a size.  Dimensions are only created and
destroyed by NcFile member functions, because they cannot exist
independently of an open netCDF file.  Hence there are no public
constructors or destructors.

@unnumberedsubsec Public Member Functions

@table @code
@findex name
@findex NcDim::name
@item NcToken name( void ) const

Returns the name of the dimension if it exists, 0 otherwise.

@findex size
@findex NcDim::size
@item long size( void ) const

Returns the dimension size.

@findex is_valid
@findex NcDim::is_valid
@item NcBool is_valid( void ) const

Returns @code{TRUE} if file and dimension are both valid, @code{FALSE}
otherwise.

@findex is_unlimited
@findex NcDim::is_unlimited
@item NcBool is_unlimited( void ) const

Returns @code{TRUE} if the dimension is the unlimited dimension,
@code{FALSE} if either not a valid netCDF file, or if the dimension is
not the unlimited dimension.

@findex rename
@findex NcDim::rename
@item NcBool rename( NcToken newname )

Renames the dimension to @code{newname}.

@findex sync
@findex NcDim::sync
@item NcBool sync( void )

If the dimension may have been renamed, make sure its name is updated.

@end table

@vindex NcTypedComponent
@node Class NcTypedComponent, Class NcVar, Class NcDim, NetCDF Classes
@unnumberedsec  Class NcTypedComponent

@code{NcTypedComponent} is an abstract base class for @code{NcVar} and
@code{NcAtt} that captures the similarities between netCDF variables and
attributes.  We list here the member functions that variables and
attributes inherit from @code{NcTypedComponent}, but these member
functions are also documented under the @code{NcVar} and @code{NcAtt}
classes for convenience.

@unnumberedsubsec Public Member Functions

@table @code
@findex name
@findex NcTypedComponent::name
@item NcToken name( void ) const

Returns the name of the variable or attribute.

@findex type
@findex NcTypedComponent::type
@item NcType type( void ) const

Returns the type of the variable or attribute.  The type will be one of
@code{ncByte}, @code{ncChar}, @code{ncShort}, @code{ncInt},
@code{ncFloat}, or @code{ncDouble}.

@findex is_valid
@findex NcTypedComponent::is_valid
@item NcBool is_valid( void ) const

Returns @code{TRUE} if the component is valid, @code{FALSE} otherwise.

@findex num_vals
@findex NcTypedComponent::num_vals
@item long num_vals( void ) const

Returns the number of values for an attribute or variable.  For an
attribute, this is just 1 for a scalar attribute, the number of values
for a vector-valued attribute, and the number of characters for a
string-valued attribute.  For a variable, this is the product of the
dimension sizes for all the variable's dimensions.

@findex rename
@findex NcTypedComponent::rename
@item NcBool rename( NcToken newname )

Renames the variable or attribute.

@findex values
@findex NcTypedComponent::values
@item NcValues* values( void ) const

Returns a pointer to the block of all values for the variable or
attribute.  The caller is responsible for deleting this block of values
when no longer needed, as well as the pointer returned by the
@code{values} method.  Note that this is not a good way to read
selected values of a variable; use the @code{get} member function
instead, to get single values or selected cross-sections of values.

@findex as_ncbyte
@findex NcTypedComponent::as_ncbyte
@item ncbyte as_ncbyte( int n ) const
@findex as_char
@findex NcTypedComponent::as_char
@itemx char as_char( int n ) const
@findex as_short
@findex NcTypedComponent::as_short
@itemx short as_short( int n ) const
@findex as_int
@findex NcTypedComponent::as_int
@itemx int as_int( int n ) const
@findex as_nclong
@findex NcTypedComponent::as_nclong
@itemx nclong as_nclong( int n ) const // deprecated
@findex as_long
@findex NcTypedComponent::as_long
@itemx long as_long( int n ) const
@findex as_float
@findex NcTypedComponent::as_float
@itemx float as_float( int n ) const
@findex as_double
@findex NcTypedComponent::as_double
@itemx double as_double( int n ) const
@findex as_string
@findex NcTypedComponent::as_string
@itemx char* as_string( int n ) const

Get the n-th value of the attribute or variable.  These member functions
provide conversions from the value type of the variable or attribute to
the specified type.  If the value is out-of-range, the
fill-value of the appropriate type is returned.
@end table


@vindex NcVar
@node Class NcVar, Class NcAtt, Class NcTypedComponent, NetCDF Classes
@unnumberedsec  Class NcVar

@code{NcVar} is derived from NcTypedComponent, and represents a netCDF
variable.  A netCDF variable has a name, a type, a shape, zero or more
attributes, and a block of values associated with it.  Because variables
are only associated with open netCDF files, there are no public
constructors for this class.  Use member functions of @code{NcFile} to
get variables or add new variables.

@unnumberedsubsec Public Member Functions

@table @code
@findex name
@findex NcTypedComponent::name
@item NcToken name( void ) const

Returns the name of the variable.

@findex type
@findex NcTypedComponent::type
@item NcType type( void ) const

Returns the type of the variable.  The type will be one of
@code{ncByte}, @code{ncChar}, @code{ncShort}, @code{ncInt},
@code{ncFloat}, or @code{ncDouble}.

@findex num_dims
@findex NcVar::num_dims
@item int num_dims( void ) const
Returns number of dimensions for this variable.

@findex get_dim
@findex NcVar::get_dim
@item NcDim* get_dim( int n ) const
Returns a pointer to the n-th dimension (starting at 0).  Returns a
NULL-pointer if an invalid dimension is requested.

@findex edges
@findex NcVar::edges
@item long* edges( void ) const
Returns the shape of the variable, in the form of a vector containing
the sizes of the dimensions of the variable.  The caller is responsible
for deleting the returned edge vector when no longer needed.

@findex num_atts
@findex NcVar::num_atts
@item int num_atts( void ) const
Returns the number of attributes attached to the variable.

@findex get_att
@findex NcVar::get_att
@item NcAtt* get_att( NcToken attname ) const
@item NcAtt* get_att( int n ) const
The first member function returns a variable attribute by name.  The
second returns the n-th (starting at 0) attribute of the variable.  In
either case, if no such attribute has been attached to the variable,
zero is returned.  Attributes returned in this way belong to the caller,
and hence should eventually be deleted by the caller to avoid memory
leaks.

@findex is_valid
@findex NcTypedComponent::is_valid
@item NcBool is_valid( void ) const

Returns @code{TRUE} if the variable is valid, @code{FALSE} otherwise.

@findex num_vals
@findex NcTypedComponent::num_vals
@item long num_vals( void ) const

Returns the number of values for a variable.  This is just 1 for a
scalar variable, or the product of the dimension sizes for all the
variable's dimensions.

@findex values
@findex NcTypedComponent::values
@item NcValues* values( void ) const

Returns a pointer to the block of all values for the variable.  
The caller is responsible for deleting this block of values
when no longer needed.
Note that this is not a good way to read selected values of
a variable; use the @code{get} member function instead, to get single
values or selected cross-sections of values.

@findex put
@findex NcVar::put
@item  NcBool put(const ncbyte* vals, long c0, long c1, long c2, long c3, long c4)
@itemx NcBool put(const char*   vals, long c0, long c1, long c2, long c3, long c4)
@itemx NcBool put(const short*  vals, long c0, long c1, long c2, long c3, long c4)
@itemx NcBool put(const int* vals, long c0, long c1, long c2, long c3, long c4)
@itemx NcBool put(const long* vals, long c0, long c1, long c2, long c3, long c4)
@itemx NcBool put(const float*  vals, long c0, long c1, long c2, long c3, long c4)
@itemx NcBool put(const double* vals, long c0, long c1, long c2, long c3, long c4)

Write scalar or 1 to 5-dimensional arrays by providing enough arguments.
The @code{vals} argument points to a contiguous block of values in
memory to be written.  This means if you allocate each row of an
array with a ``new'' call for example, you must not write more than one row
at a time, because the rows may not be contiguous in memory.
Other arguments are edge lengths, and their number must not exceed variable's
dimensionality.  Start corner is @code{[0,0,..., 0]} by default, but may
be reset using the @code{set_cur()} member function for this variable.
@code{FALSE} is returned if type of values does not match type for
variable.  For more than 5 dimensions, use the overloaded n-dimensional
form of the @code{put} member function.

@findex put
@findex NcVar::put
@item  NcBool put(const ncbyte* vals, const long* counts)
@itemx NcBool put(const char*   vals, const long* counts)
@itemx NcBool put(const short*  vals, const long* counts)
@itemx NcBool put(const int* vals, const long* counts)
@itemx NcBool put(const long* vals, const long* counts)
@itemx NcBool put(const float*  vals, const long* counts)
@itemx NcBool put(const double* vals, const long* counts)

Write n-dimensional arrays, starting at @code{[0, 0, ..., 0]} by
default, may be reset with @code{set_cur()}.  @code{FALSE} is returned
if type of values does not match type for variable.
The @code{vals} argument points to a contiguous block of values in
memory to be written.  This means if you allocate each row of an
array with a ``new'' call for example, you must not write more than one row
at a time, because the rows may not be contiguous in memory.

@findex get
@findex NcVar::get
@item  NcBool get(ncbyte* vals, long c0, long c1, long c2, long c3, long c4) const
@itemx NcBool get(char*   vals, long c0, long c1, long c2, long c3, long c4) const
@itemx NcBool get(short*  vals, long c0, long c1, long c2, long c3, long c4) const
@itemx NcBool get(int* vals, long c0, long c1, long c2, long c3, long c4) const
@itemx NcBool get(long* vals, long c0, long c1, long c2, long c3, long c4) const
@itemx NcBool get(float*  vals, long c0, long c1, long c2, long c3, long c4) const
@itemx NcBool get(double* vals, long c0, long c1, long c2, long c3, long c4) const

Get scalar or 1 to 5 dimensional arrays by providing enough arguments.
The @code{vals} argument points to a contiguous block of values in
memory into which values will be read.  This means if you allocate each row of an
array with a ``new'' call for example, you must not read more than one row
at a time, because the rows may not be contiguous in memory.
Other arguments are edge lengths, and their number must not exceed variable's
dimensionality.  Start corner is @code{[0,0,..., 0]} by default, but may
be reset using the @code{set_cur()} member function.  @code{FALSE} is
returned if type of values does not match type for variable.

@findex get
@findex NcVar::get
@item  NcBool get(ncbyte* vals, const long* counts) const
@itemx NcBool get(char*   vals, const long* counts) const
@itemx NcBool get(short*  vals, const long* counts) const
@itemx NcBool get(int* vals, const long* counts) const
@itemx NcBool get(long* vals, const long* counts) const
@itemx NcBool get(float*  vals, const long* counts) const
@itemx NcBool get(double* vals, const long* counts) const
Get n-dimensional arrays, starting at @code{[0, 0, ..., 0]} by default,
may be reset with @code{set_cur()} member function.  @code{FALSE} is
returned if type of values does not match type for variable.
Get scalar or 1 to 5 dimensional arrays by providing enough arguments.
The @code{vals} argument points to a contiguous block of values in
memory into which values will be read.  This means if you allocate each row of an
array with a ``new'' call for example, you must not read more than one row
at a time, because the rows may not be contiguous in memory.

@findex set_cur
@findex NcVar::set_cur
@item NcBool set_cur(long c0=-1, long c1=-1, long c2=-1, long c3=-1, long c4=-1)
@itemx NcBool set_cur(long* cur)
Resets the starting corner to the values supplied.  The first form works
for a variable of dimensionality from scalar to 5 dimensions.  For more
than five dimensions, use the second form, in which the number of longs
supplied must match the rank of the variable.  The method returns FALSE if
any argument is greater than the size of the corresponding dimension.

@findex NcVar::add_att
@findex add_att
@item  NcBool add_att( NcToken, char )
@item  NcBool add_att( NcToken, ncbyte )
@itemx NcBool add_att( NcToken, short )
@itemx NcBool add_att( NcToken, int )
@itemx NcBool add_att( NcToken, long )
@itemx NcBool add_att( NcToken, float )
@itemx NcBool add_att( NcToken, double )
@itemx NcBool add_att( NcToken, const char* )
@itemx NcBool add_att( NcToken, int, const char* )
@itemx NcBool add_att( NcToken, int, const ncbyte* )
@itemx NcBool add_att( NcToken, int, const short* )
@itemx NcBool add_att( NcToken, int, const int* )
@itemx NcBool add_att( NcToken, int, const long* )
@itemx NcBool add_att( NcToken, int, const float* )
@itemx NcBool add_att( NcToken, int, const double* )

Add scalar or vector attribute of any type to a variable, given the
name, number of values, and the vector of values.  These put file in
define mode, so could be expensive.  To avoid the expense of copying
data, add attributes to variables before writing data.

@findex rename
@findex NcTypedComponent::rename
@item NcBool rename( NcToken newname )

Renames the variable.  If variable is renamed to a longer name, this
puts file in define mode, so could be expensive.

@findex as_ncbyte
@findex NcTypedComponent::as_ncbyte
@item ncbyte as_ncbyte( int n ) const
@findex as_char
@findex NcTypedComponent::as_char
@itemx char as_char( int n ) const
@findex as_short
@findex NcTypedComponent::as_short
@itemx short as_short( int n ) const
@findex as_int
@findex NcTypedComponent::as_int
@itemx int as_int( int n ) const
@findex as_nclong
@findex NcTypedComponent::as_nclong
@itemx nclong as_nclong( int n ) const // deprecated
@findex as_long
@findex NcTypedComponent::as_long
@itemx long as_long( int n ) const
@findex as_float
@findex NcTypedComponent::as_float
@itemx float as_float( int n ) const
@findex as_double
@findex NcTypedComponent::as_double
@itemx double as_double( int n ) const
@findex as_string
@findex NcTypedComponent::as_string
@itemx char* as_string( int n ) const

Get the n-th value of the variable, ignoring its shape.  These member
functions provide conversions from the value type of the variable to the
specified type.  If the requested value is out-of-range, the fill-value of the
appropriate type is returned.

@findex id
@findex NcVar::id
@item int id( void ) const

Return the variable number.  This is not needed in the C++ interface,
but might be needed in calling a C-function that requires that a variable
be identified by number instead of name.

@findex sync
@findex NcVar::sync
@item NcBool sync( void )

If the variable may have been renamed, make sure its name is updated.

@findex ~NcVar
@findex NcVar::~NcVar
@item ~NcVar( void )
Destructor.
@end table

The following member functions are intended for record variables.  They
will also work for non-record variables, if the first dimension is
interpreted as the record dimension.

@table @code
@findex rec_size
@findex NcVar::rec_size
@item long rec_size( void )
@item long rec_size( NcDim* )

Return the number of values per record or the number of values per
dimension slice for the specified dimension.

@findex get_rec
@findex NcVar::get_rec
@item NcValues* get_rec( void )
@itemx NcValues* get_rec( long n )

Get the data for this variable for the current record or for the
@var{n}th record.

@item NcValues* get_rec( NcDim* )
@itemx NcValues* get_rec( NcDim*, long n )

Get the data for this variable for the current dimension slice or for the
@var{n}th dimension slice.

@findex put_rec
@findex NcVar::put_rec
@item  NcBool put_rec( const ncbyte* vals )
@itemx NcBool put_rec( const char* vals )
@itemx NcBool put_rec( const short* vals )
@itemx NcBool put_rec( const int* vals )
@itemx NcBool put_rec( const long* vals )
@itemx NcBool put_rec( const float* vals )
@itemx NcBool put_rec( const double* vals )

Put a record's worth of data for this variable in the current record.

@item  NcBool put_rec( NcDim*, const ncbyte* vals )
@itemx NcBool put_rec( NcDim*, const char* vals )
@itemx NcBool put_rec( NcDim*, const short* vals )
@itemx NcBool put_rec( NcDim*, const int* vals )
@itemx NcBool put_rec( NcDim*, const long* vals )
@itemx NcBool put_rec( NcDim*, const float* vals )
@itemx NcBool put_rec( NcDim*, const double* vals )

Put a dimension slice worth of data for this variable in the current
dimension slice.

@findex put_rec
@findex NcVar::put_rec
@item  NcBool put_rec( const ncbyte* vals, long rec )
@itemx NcBool put_rec( const char* vals, long rec )
@itemx NcBool put_rec( const short* vals, long rec )
@itemx NcBool put_rec( const int* vals, long rec )
@itemx NcBool put_rec( const long* vals, long rec )
@itemx NcBool put_rec( const float* vals, long rec )
@itemx NcBool put_rec( const double* vals, long rec )

Put a record's worth of data for this variable in the specified record.

@item  NcBool put_rec( NcDim*, const ncbyte* vals, long slice )
@itemx NcBool put_rec( NcDim*, const char* vals, long slice )
@itemx NcBool put_rec( NcDim*, const short* vals, long slice )
@itemx NcBool put_rec( NcDim*, const int* vals, long slice )
@itemx NcBool put_rec( NcDim*, const long* vals, long slice )
@itemx NcBool put_rec( NcDim*, const float* vals, long slice )
@itemx NcBool put_rec( NcDim*, const double* vals, long slice )

Put a dimension slice worth of data for this variable in the specified
dimension slice.

@findex get_index
@findex NcVar::get_index
@item  long get_index( const ncbyte* vals )
@itemx long get_index( const char* vals )
@itemx long get_index( const short* vals )
@itemx long get_index( const int* vals )
@itemx long get_index( const long* vals )
@itemx long get_index( const float* vals )
@itemx long get_index( const double* vals )

Get first record index for this variable corresponding to the specified
key value(s).

@item  long get_index( NcDim*, const ncbyte* vals )
@itemx long get_index( NcDim*, const char* vals )
@itemx long get_index( NcDim*, const short* vals )
@itemx long get_index( NcDim*, const int* vals )
@itemx long get_index( NcDim*, const long* vals )
@itemx long get_index( NcDim*, const float* vals )
@itemx long get_index( NcDim*, const double* vals )

Get first index of specified dimension for this variable corresponding
to the specified key value(s).

@findex set_rec
@findex NcVar::set_rec
@item void set_rec ( long rec )

Set the current record for this variable.

@item void set_rec ( NcDim*, long rec )

Set the current dimension slice for the specified dimension for this variable.

@end table

@vindex NcAtt
@node Class NcAtt,  , Class NcVar, NetCDF Classes
@unnumberedsec  Class NcAtt

@code{NcAtt} is derived from @code{NcTypedComponent}, and represents a netCDF
attribute.  A netCDF attribute has a name and a type, and may be either
a scalar attribute or a vector attribute.  Scalar attributes have one
value and vector attributes have multiple values.  In addition, each
attribute is attached to a specific netCDF variable or is global to an
entire netCDF file.  Because attributes are only associated with open
netCDF files, there are no public constructors for this class.  Use
member functions of @code{NcFile} and @code{NcVar} to get netCDF
attributes or add new attributes.  Most of the useful member functions
for @code{NcAtt} are
inherited from class @code{NcTypedComponent}.

@unnumberedsubsec Public Member Functions

@table @code
@findex name
@findex NcTypedComponent::name
@item NcToken name( void ) const

Returns the name of the attribute.

@findex type
@findex NcTypedComponent::type
@item NcType type( void ) const

Returns the type of the attribute.  The type will be one of
@code{ncByte}, @code{ncChar}, @code{ncShort}, @code{ncInt},
@code{ncFloat}, or @code{ncDouble}.

@findex is_valid
@findex NcTypedComponent::is_valid
@item NcBool is_valid( void ) const

Returns @code{TRUE} if the attribute is valid, @code{FALSE} otherwise.

@findex num_vals
@findex NcTypedComponent::num_vals
@item long num_vals( void ) const

Returns the number of values for an attribute.  This is just 1 for a
scalar attribute, the number of values for a vector-valued attribute,
and the number of characters for a string-valued attribute.

@findex rename
@findex NcTypedComponent::rename
@item NcBool rename( NcToken newname )

Renames the attribute.

@findex values
@findex NcTypedComponent::values
@item NcValues* values( void ) const

Returns a pointer to the block of all values for the
attribute.  The caller is responsible for deleting this block of values
when no longer needed.

@findex as_ncbyte
@findex NcTypedComponent::as_ncbyte
@item ncbyte as_ncbyte( int n ) const
@findex as_char
@findex NcTypedComponent::as_char
@itemx char as_char( int n ) const
@findex as_short
@findex NcTypedComponent::as_short
@itemx short as_short( int n ) const

@findex as_int
@findex NcTypedComponent::as_int
@itemx int as_int( int n ) const

@findex as_nclong
@findex NcTypedComponent::as_nclong
@itemx nclong as_nclong( int n ) const // deprecated

@findex as_long
@findex NcTypedComponent::as_long
@itemx long as_long( int n ) const

@findex as_float
@findex NcTypedComponent::as_float
@itemx float as_float( int n ) const
@findex as_double
@findex NcTypedComponent::as_double
@itemx double as_double( int n ) const
@findex as_string
@findex NcTypedComponent::as_string
@itemx char* as_string( int n ) const

Get the n-th value of the attribute.  These member functions provide
conversions from the value type of the attribute to the specified type.
If the value is out-of-range, the fill-value of the appropriate type is
returned.

@findex remove
@findex NcAtt::remove
@item NcBool remove( void )
Deletes the attribute from the file and detaches it from the variable.
Does not call the destructor.  Subsequent calls to @code{is_valid()} will
return @code{FALSE}.

@findex ~NcAtt
@findex NcAtt::~NcAtt
@item ~NcAtt( void )
Destructor.
@end table

@node Auxiliary Classes, Combined Index, NetCDF Classes, Top
@unnumbered  Auxiliary Classes

Auxiliary classes include the abstract base class @code{NcValues}, its
type-specific derived subclasses, and the error-handling class
@code{NcError}.

@menu
* Class NcValues::              
* Class NcError::               
@end menu

@vindex NcValues
@node Class NcValues, Class NcError, Auxiliary Classes, Auxiliary Classes
@unnumberedsec  Class NcValues

@vindex NcValues_ncbyte
@vindex NcValues_char
@vindex NcValues_short
@vindex NcValues_int
@vindex NcValues_nclong
@vindex NcValues_long
@vindex NcValues_float
@vindex NcValues_double
Class @code{NcValues} is an abstract base class for a block of typed
values.  The derived classes are @code{NcValues_ncbyte},
@code{NcValues_char}, @code{NcValues_short}, @code{NcValues_int},
@code{NcValues_nclong} (deprecated), and  @code{NcValues_long},
@code{NcValues_float}, @code{NcValues_double}.
These classes are used as the return type of the
@code{NcTypedComponent::values()} member function, for typed-value
arrays associated with variables and attributes.

@unnumberedsubsec Public Member Functions

@table @code
@findex NcValues
@findex NcValues::NcValues
@item NcValues( void )
Default constructor.

@findex NcValues
@findex NcValues::NcValues
@item NcValues(NcType, long)
Constructor for a value block of the specified type and length.

@findex ~NcValues
@findex NcValues::~NcValues
@item ~NcValues( void )
Destructor.

@findex num
@findex NcValues::num
@item long num( void )
Returns the number of values in the value block.

@findex print
@findex NcValues::print
@item ostream& print(ostream&) const
Used to print the comma-delimited sequence of values of the value block.

@findex base
@findex NcValues::base
@item void* base( void ) const
Returns a bland pointer to the beginning of the value block.

@findex bytes_for_one
@findex NcValues::bytes_for_one
@item int bytes_for_one( void ) const
Returns the number of bytes required for one value.

@findex as_ncbyte
@findex NcValues::as_ncbyte
@item ncbyte as_ncbyte( int n ) const
@findex as_char
@findex NcValues::as_char
@itemx char as_char( int n ) const
@findex as_short
@findex NcValues::as_short
@itemx short as_short( int n ) const

@findex as_int
@findex NcValues::as_int
@itemx int as_int( int n ) const

@findex as_nclong
@findex NcValues::as_nclong
@itemx nclong as_nclong( int n ) const // deprecated

@findex as_long
@findex NcValues::as_long
@itemx long as_long( int n ) const

@findex as_float
@findex NcValues::as_float
@itemx float as_float( int n ) const
@findex as_double
@findex NcValues::as_double
@itemx double as_double( int n ) const
@findex as_string
@findex NcValues::as_string
@itemx char* as_string( int n ) const
Provide conversions for the nth value from the value type to a desired
basic type.  If the value is out of range, the default "fill-value" for
the appropriate type is returned.
@end table

@vindex NcError
@node Class NcError,  , Class NcValues, Auxiliary Classes
@unnumberedsec  Class NcError

This class provides control for netCDF error handling.  Declaring an
@code{NcError} object temporarily changes the error-handling behavior
for all netCDF classes until the @code{NcError} object is destroyed
(typically by going out of scope), at which time the previous
error-handling behavior is restored.

@unnumberedsubsec Public Member Functions

@table @code
@findex NcError
@item NcError( Behavior b = verbose_fatal )
The constructor saves the previous error state for restoration when the
destructor is invoked, and sets a new specified state.  Valid error
states are @code{NcError::silent_nonfatal},
@code{NcError::verbose_nonfatal}, @code{NcError::silent_fatal}, or
@code{NcError::verbose_fatal}, to control whether error messages are
output from the underlying library and whether such messages are fatal
or nonfatal.

@findex ~NcError
@findex NcError::~NcError
@item ~NcError( void )
Destructor, restores previous error state.

@findex get_err
@findex NcError::get_err
@item int get_err( void )
Returns most recent error, as enumerated in @file{netcdf.h}.
@end table

@node Combined Index,  , Auxiliary Classes, Top
@unnumbered Index

@printindex cp

@bye
End: