   This file documents the prototype experimental Unidata C++ netCDF
interface.

   Copyright (C) 1993 University Corporation for Atmospheric Research.
Permission is granted to make and distribute verbatim copies of this
file provided the copyright notice and this permission notice are
preserved on all copies.

NetCDF C++ Interface
********************

   This manual is preliminary documentation for the prototype,
experimental C++ interface for netCDF (version 0).

Introduction
************

   This is an early release for a prototype implementation of a C++
interface for the netCDF data access library.

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

   * to provide the functionality of the C interface;

   * to keep the C++ interface state consistent with the C interface
     state;

   * to provide type safety by eliminating all use of `void*' pointers;
     and

   * to provide an interface that is simpler to use than the C
     interface.

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

   * No IDs needed for netCDF's variables, dimensions, or attributes.

   * No explicit open or close calls needed for netCDF files; a
     constructor opens and a destructor closes a file.

   * No need to specify types for creating attributes; they will have
     the type of the value provided.

   * No use of `void*': values are type-checked.

   * Less indirection is needed for dimensions & dimension sizes than
     with the C interface.  Dimensions can be given as arguments in
     variable definitions.

   * Code for data types is isolated, which should make the addition of
     new types easier.

   * No explicit `ncredef' or `ncendef' calls are needed for switching
     between define and data modes.  Whenever a mode switch is
     required, it happens implicitly.  Note: this may change; there
     appear to be advantages to not allowing `ncredef' functionality in
     the C++ interface, but supporting copy semantics and a `schema'
     object instead.

   The header file `netcdf.hh' must be included in source code files
using this interface.

   This early release provides the functionality of netCDF version 2.02,
but does not yet include member functions corresponding to the netCDF
2.3 generalized hyperslab access interfaces (`ncvarputg', `ncvargetg')
or the record I/O interfaces (`ncrecinq', `ncrecput', `ncrecget') in
netCDF version 2.3.

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

Class Hierarchy
===============

     `NcFile'                   abstract base class for files
             `NcNewFile'        new netCDF files
             `NcOldFile'        existing netCDF files

     `NcDim'                    dimension

     `NcTypedComponent'         abstract base class
             `NcVar'            variable
             `NcAtt'            attribute

     `NcValues'                 abstract base class for arrays
             `NcValues_ncbyte'  array of bytes
             `NcValues_char'    array of characters
             `NcValues_short'   array of shorts
             `NcValues_int'     array of ints
             `NcValues_long'    array of longs
             `NcValues_float'   array of floats
             `NcValues_double'  array of doubles

     `NcError'                    for error handling

Auxiliary Types and Constants
=============================

   The netCDF classes use several auxiliary types for arguments and
return types from member functions: `NcToken', `NcType', `ncbyte', and
`NcBool'.

`NcToken'
     Used for names for netCDF objects, in particular variable names,
     dimension names, and attribute names.  Currently this is just a
     typedef for `const char*'.

`NcType'
     Used for specifying netCDF value types.  Currently this is an
     enumerated type with the following legitimate values:  `ncByte',
     `ncChar', `ncShort', `ncLong', `ncFloat', `ncDouble', and `ncInt'.
      The latter is a synonym for `ncLong'.

`ncbyte'
     Used to declare values of type `ncByte', analogously to using the
     built-in type `float' to declare values of type `ncFloat'. This is
     currently just a typedef for `unsigned char'.

`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 `unsigned int'.

File Classes
************

   There are three netCDF file classes: `NcFile', `NcOldFile', and
`NcNewFile'.  The latter two are derived from the `NcFile' abstract
base class, which defines all the member functions except the
constructors.

Class NcFile
============

   `NcFile' is the abstract base class for netCDF file objects.  It
provides all common methods for file operations.  There are no
constructors for `NcFile'.  `NcOldFile' or `NcNewFile' classes must be
used to create `NcFile' objects.

   Some member functions return pointers to dimensions (`NcDim') or
variables (`NcVar').  These objects are owned by the `NcFile' they are
associated with, and will be deleted automatically by the `NcFile'
destructor (or by the `close' member function, if this is called
earlier than the destructor), so users should not delete these.  Member
functions that return pointers to attributes (`NcAtt') currently pass
ownership to the calling function; users should delete attributes when
they are finished with them.  Note: it appears that it will be
desirable to change the ownership of `NcAtt' objects in the future so
that they are owned by their variables, at which time their destructor
will be called when the associated variable destructor is invoked.

   All member functions that return a value of type `NcBool' return
`TRUE' on success and `FALSE' on failure.  All member functions that
return a pointer value return the `NULL' pointer on failure.

   This class interface hides the distinction in the C and Fortran
interfaces between "define mode" (when dimensions, variables, or
attributes are being defined or renamed), and "data mode" (when data
values are being accessed), by automatically switching between the modes
when necessary.  Users should 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.

Public Member Functions
-----------------------

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

`NcBool close( void )'
     Close netCDF file.

`NcBool is_valid( void ) const'
     Returns `TRUE' if valid netCDF file, `FALSE' otherwise (e.g. if
     constructor could not open file).

`int num_dims( void ) const'
     Returns the number of dimensions in the netCDF file.

`int num_vars( void ) const'
     Returns the number of variables in the netCDF file.

`int num_atts( void ) const'
     Returns the number of global attributes in the netCDF file.

`NcDim* get_dim(NcToken name) const'
     Get a dimension by name.

`NcVar* get_var(NcToken name) const'
     Get a variable by name.

`NcAtt* get_att(NcToken name) const'
     Get a global attribute by name.

`NcDim* get_dim(int i) const'
     Get the ith dimension (beginning with the 0th).

`NcVar* get_var(int i) const'
     Get the ith variable (beginning with the 0th).

`NcAtt* get_att(int i) const'
     Get the ith global attribute (beginning with the 0th).

`NcDim* rec_dim( void ) const'
     Get the unlimited dimension, if any.

`NcDim* add_dim(NcToken dimname)'
     Add an unlimited dimension named `dimname' to the netCDF file.

`NcDim* add_dim(NcToken dimname, long dimsize)'
     Add a dimension named `dimname' of size `dimsize'.

`NcVar* add_var(NcToken varname, NcType type, const NcDim* dim0, ... , const NcDim* dim4=0)'
     Add a variable named `varname' of between 1 and 5 dimensions of the
     specified type.  Dimension arguments default to 0.  Supply as many
     dimensions as needed.  If more than 5 dimensions are required, use
     the n-dimensional version of this member function.

`NcVar* add_var(NcToken varname, NcType type, int ndims, const NcDim* dims)'
     Add a variable named `varname' of `ndims' dimensions and of the
     specified type.  Use this method when dealing with variables of
     more than 5 dimensions.

`NcBool add_att(NcToken name, char val)'
`NcBool add_att(NcToken name, short val)'
`NcBool add_att(NcToken name, int val)'
`NcBool add_att(NcToken name, long val)'
`NcBool add_att(NcToken name, float val)'
`NcBool add_att(NcToken name, double val)'
`NcBool add_att(NcToken name, const char* val)'
     Add global scalar attributes of the specified name and with the
     supplied value.

`NcBool add_att(NcToken name, int n, const char* val)'
`NcBool add_att(NcToken name, int n, const short* val)'
`NcBool add_att(NcToken name, int n, const int* val)'
`NcBool add_att(NcToken name, int n, const long* val)'
`NcBool add_att(NcToken name, int n, const float* val)'
`NcBool add_att(NcToken name, int n, const double* val)'
     Add global vector attributes with the specified name and vector
     value.

`NcBool set_fill( FillMode mode = Fill)'
     Sets fill-mode to either `NcFile::Fill' or `NcFile::NoFill'.
     Default is `Fill', in which case unwritten values are prewritten
     with appropriate type-specific or variable-specific fill values.

`enum NcFile::FillMode get_fill( void ) const'
     Returns fill mode of the file.

`NcBool sync( void )'
     Synchronizes file to disk.

`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).

Class NcNewFile
===============

   This class is derived from the abstract base class `NcFile', and it
is used to create new netCDF files.

Public Member Functions
-----------------------

`NcNewFile( const char * path, CreateMode = NoClobber )'
     The constructor creates a new netCDF file.  If called with a
     single path name argument or `NcNewFile::NoClobber' for its second
     argument, it creates the file only if it does not already exist.
     The constructor will not fail in case of a bad path name or if the
     file already exists, but no netCDF file will be created, and the
     fact that the creation failed may be checked with the `is_valid()'
     member function.

     If called with `NcNewFile::Clobber' for its second argument, a new
     netCDF file will be created even if the file already exists,
     clobbering the old netCDF file.

`~NcNewFile( void )'
     The destructor will close the file, if it has not already been
     closed with an explicit call to the `close()' member function.

Class NcOldFile
===============

   This class is derived from the abstract base class `NcFile', and it
is used to open existing netCDF files, either for read-only access (the
default), or for read-write access.

Public Member Functions
-----------------------

`NcOldFile( const char * path, OpenMode = ReadOnly )'
     The constructor opens an existing netCDF file.  The constructor
     will not fail in case of a bad path name or the proper permissions
     on the file but no netCDF file will be opened, and the fact that
     the open failed may be checked with the `is_valid()' member
     function.

     If called with a single path name argument or `NcOldFile::ReadOnly'
     for its second argument, the file is opened for read-only access.
     If called with `NcOldFile::Write' for its second argument, the file
     will be opened with read-write access.

`~NcNewFile( void )'
     The destructor will close the file, if it has not already been
     closed with an explicit call to the `close()' member function.

Dimensions, Variables, and Attributes
*************************************

   The components of a netCDF file are dimensions, variables, and
attributes.  There is a class for each of these kinds of objects;
`NcDim', `NcVar', and `NcAtt'.  Variables and attributes share some
common characteristics that are factored out in the abstract base class
`NcTypedComponent'.  Users will never declare `NcTypedComponent'
instances, but must know about the public member functions of this
class for use with variables and attributes.

Class NcDim
===========

   A netCDF dimension has a name and a size.  These 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.

Public Member Functions
-----------------------

`NcToken name( void ) const'
     Returns the name of the dimension if it exists, 0 otherwise.

`long size( void ) const'
     Returns the dimension size.

`NcBool is_valid( void ) const'
     Returns `TRUE' if file and dimension are both valid, `FALSE'
     otherwise.

`NcBool is_unlimited( void ) const'
     Returns `TRUE' if the dimension is the unlimited dimension,
     `FALSE' if either not a valid netCDF file, or if the dimension is
     not the unlimited dimension.

`NcBool rename( NcToken newname )'
     Renames the dimension to `newname'.

`int id( void ) const'
     Returns the id number of the dimension.  This should almost never
     be needed in the C++ interface.

Class NcTypedComponent
======================

   `NcTypedComponent' is an abstract base class for `NcVar' and `NcAtt'
that captures the similarities between netCDF variables and attributes.

Public Member Functions
-----------------------

`NcToken name( void ) const'
     Returns the name of the variable or attribute.

`NcType type( void ) const'
     Returns the type of the variable or attribute.  The type will be
     one of `ncByte', `ncChar', `ncShort', `ncLong', `ncFloat', or
     `ncDouble'.

`NcBool is_valid( void ) const'
     Returns `TRUE' if the component is valid, `FALSE' otherwise.

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

`NcBool rename( NcToken newname )'
     Renames the variable or attribute.

`NcValues* values( void )'
     Returns a pointer to the block of all values for the variable or
     attribute.  This will be deleted when the variable or attribute is
     destroyed.  Note that this is not a good way to read selected
     values of a variable; use the `get' member function instead, to
     get single values or selected cross-sections of values.

`ncbyte as_ncbyte( int n ) const'
`char as_char( int n ) const'
`short as_short( int n ) const'
`long as_long( int n ) const'
`float as_float( int n ) const'
`double as_double( int n ) const'
`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 default fill-value of the appropriate type should be returned
     (not yet implemented).

Class NcVar
===========

   `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 `NcFile' to get
netCDF variables.

Public Member Functions
-----------------------

`~NcVar( void )'
     Destructor.

`int num_dims( void ) const'
     Returns number of dimensions for this variable.

`NcDim* get_dim( int ) const'
     Returns a pointer to the n-th dimension (starting at 0).  Returns a
     NULL-pointer if an invalid dimension is requested.

`const 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.

`int num_atts( void ) const'
     Returns the number of attributes attached to the variable.

`NcAtt* get_att( NcToken ) const'
     Returns an attribute by name of the variable.  If no such
     attribute has been attached to the variable, zero is returned.
     Currently, attributes returned in this way must be deleted by the
     caller.

`NcAtt* get_att( int ) const'
     Returns the n-th (starting at 0) attribute of the variable.  If no
     such attribute has been attached to the variable, zero is returned.
     Currently, attributes returned in this way must be deleted by the
     caller.

`NcBool put( const char* vals, long c0, long c1, long c2, long c3, long c4 )'
`NcBool put( const short* vals, long c0, long c1, long c2, long c3, long c4 )'
`NcBool put( const long* vals, long c0, long c1, long c2, long c3, long c4 )'
`NcBool put( const int* vals, long c0, long c1, long c2, long c3, long c4 )'
`NcBool put( const float* vals, long c0, long c1, long c2, long c3, long c4 )'
`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. Arguments are edge lengths, and their number must not
     exceed variable's dimensionality.  Start corner is `[0,0,..., 0]'
     by default, but may be reset using the `set_cur()' member
     function.  `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 `put' member function.

`NcBool put( const char* vals, const long* counts )'
`NcBool put( const short* vals, const long* counts )'
`NcBool put( const long* vals, const long* counts )'
`NcBool put( const int* vals, const long* counts )'
`NcBool put( const float* vals, const long* counts )'
`NcBool put( const double* vals, const long* counts )'
     Write n-dimensional arrays, starting at `[0, 0, ..., 0]' by
     default, may be reset with `set_cur()'.  `FALSE' is returned if
     type of values does not match type for variable.

`NcBool get( char* vals, long c0, long c1, long c2, long c3, long c4 ) const'
`NcBool get( short* vals, long c0, long c1, long c2, long c3, long c4 ) const'
`NcBool get( long* vals, long c0, long c1, long c2, long c3, long c4 ) const'
`NcBool get( int* vals, long c0, long c1, long c2, long c3, long c4 ) const'
`NcBool get( float* vals, long c0, long c1, long c2, long c3, long c4 ) const'
`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.  Arguments are edge lengths, and their number must not
     exceed variable's dimensionality.  Start corner is `[0,0,..., 0]'
     by default, but may be reset using the `set_cur()' member function.

`NcBool get( char* vals, const long* counts ) const'
`NcBool get( short* vals, const long* counts ) const'
`NcBool get( long* vals, const long* counts ) const'
`NcBool get( int* vals, const long* counts ) const'
`NcBool get( float* vals, const long* counts ) const'
`NcBool get( double* vals, const long* counts ) const'
     Get n-dimensional arrays, starting at `[0, 0, ..., 0]' by default,
     may be reset with `set_cur()' member function.

`NcBool set_cur(long c0=-1, long c1=-1, long c2=-1, long c3=-1, long c4=-1)'
`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.
     The method returns FALSE if any argument is greater than the size
     of the corresponding dimension.

`NcBool add_att( NcToken, char )'
`NcBool add_att( NcToken, short )'
`NcBool add_att( NcToken, int )'
`NcBool add_att( NcToken, long )'
`NcBool add_att( NcToken, float )'
`NcBool add_att( NcToken, double )'
`NcBool add_att( NcToken, const char* )'
`NcBool add_att( NcToken, int, const char* )'
`NcBool add_att( NcToken, int, const short* )'
`NcBool add_att( NcToken, int, const int* )'
`NcBool add_att( NcToken, int, const long* )'
`NcBool add_att( NcToken, int, const float* )'
`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.

`NcBool rename( NcToken newname )'
     Rename a variable.

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

Class NcAtt
===========

   `NcAtt' is derived from `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 `NcFile' and `NcVar' to get netCDF attributes.
Most of the useful member functions for `NcAtt' are inherited from
class `NcTypedComponent'.

Public Member Functions
-----------------------

`~NcAtt( void )'
     Destructor.

`NcBool remove( void )'
     Deletes the attribute from the file and detaches it from the
     variable. Does not call the destructor.  Subsequent calls to
     `is_valid()' will return `FALSE'.

Auxiliary Classes
*****************

   Auxiliary classes include the abstract base class `NcValues', its
type-specific derived subclasses, and the error-handling class
`NcError'.

Class NcValues
==============

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

Public Member Functions
-----------------------

`NcValues( void )'
     Default constructor.

`NcValues(NcType, long)'
     Constructor for a value block of the specified type and length.

`~NcValues( void )'
     Destructor.

`long num( void )'
     Returns the number of values in the value block.

`ostream& print(ostream&) const'
     Used to print the comma-delimited sequence of values of the value
     block.

`void* base( void ) const'
     Returns a bland pointer to the beginning of the value block.

`int bytes_for_one( void ) const'
     Returns the number of bytes required for one value.

`ncbyte as_ncbyte( int n ) const'
`char as_char( int n ) const'
`short as_short( int n ) const'
`long as_long( int n ) const'
`float as_float( int n ) const'
`double as_double( int n ) const'
`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.

Class NcError
=============

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

Public Member Functions
-----------------------

`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 `NcError::silent_nonfatal',
     `NcError::verbose_nonfatal', `NcError::silent_fatal', or
     `NcError::verbose_fatal', to control whether error messages are
     output from the underlying library and whether such messages are
     fatal or nonfatal.

`~NcError( void )'
     Destructor, restores previous error state.

`int get_err( void )'
     Returns most recent error, as enumerated in `netcdf.h'.