NcFile
is the class for netCDF files,
providing methods for netCDF file operations.
(A previous prototype release included derived classes NcOldFile
,
and NcNewFile
, but these are no longer needed. Old code that
uses NcOldFile and NcNewFile classes should still work, but new code
should not use the deprecated NcOldFile and NcNewFile classes.)
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
) pass ownership to the calling function; users
should delete attributes when they are finished with them.
Member functions that return NcBool
yield TRUE
on success
and FALSE
on failure. Member functions that return a pointer
value return a 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. 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.
NcFile( const char * path, FileMode = ReadOnly )
FileMode
argument can be any of ReadOnly
(the
default) to open an existing file for reading, Write
to open an
existing file for reading or writing, Replace
to create a new
empty file even if the named file already exists, or
New
to create a new file only if the named file does not already
exist.
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 FileMode
as 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 is_valid()
member function will return
False
.
~NcFile( void )
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 )
NcFile
destructor.
NcBool is_valid( void ) const
TRUE
if valid netCDF file, FALSE
otherwise (e.g.
if constructor could not open file).
int num_dims( void ) const
int num_vars( void ) const
int num_atts( void ) const
NcDim* get_dim(NcToken name) const
NcVar* get_var(NcToken name) const
NcAtt* get_att(NcToken name) const
NcDim* get_dim(int n) const
NcVar* get_var(int n) const
NcAtt* get_att(int n) const
NcDim* rec_dim( void ) const
The following add_
member functions put the file in define
mode, so could be expensive. To avoid copying of data, invoke
these before writing data to variables.
NcDim* add_dim(NcToken dimname)
dimname
to the netCDF file.
NcDim* add_dim(NcToken dimname, long dimsize)
dimname
of size dimsize
.
NcVar* add_var(NcToken varname, NcType type, const NcDim*, ...)
varname
of the specified type
(ncByte
, ncChar
, ncShort
, ncInt
,
ncFloat
, 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.
NcVar* add_var(NcToken varname, NcType type, int ndims, const NcDim** dims)
varname
of ndims
dimensions and of
the specified type. This method must be used when dealing with
variables of more than 5 dimensions.
NcBool add_att(NcToken name, ncbyte val)
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, float val)
NcBool add_att(NcToken name, double val)
NcBool add_att(NcToken name, const char* val)
\0
character).
NcBool add_att(NcToken name, int n, const ncbyte* val)
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 float* val)
NcBool add_att(NcToken name, int n, const double* val)
NcBool set_fill(FillMode mode = Fill)
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
NcFile::Fill
or
NcFile::NoFill
.
enum NcFile::FileFormat get_format( void ) const
NcFile::Classic
,
NcFile:Offset64Bits
, NcFile:Netcdf4
, or
NcFile::Netcdf4Classic
.
NcBool sync( void )
NcBool abort( void )