Class NcFile

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.

Public Member Functions

NcFile( const char * path, FileMode = ReadOnly )

The constructor creates a new netCDF file or opens an existing netCDF file. The 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 )

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 earlier than it would be closed by the NcFile destructor.

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 n) const

Get the nth dimension (beginning with the 0th).

NcVar* get_var(int n) const

Get the nth variable (beginning with the 0th).

NcAtt* get_att(int n) const

Get the nth global attribute (beginning with the 0th).

NcDim* rec_dim( void ) const

Get the unlimited dimension, if any.

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)

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*, ...)

Add a variable named 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)

Add a variable named 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)

Add global scalar attributes of the specified name and with the supplied value.

NcBool add_att(NcToken name, const char* val)

Add global string-valued attribute with the specified name and C string value (terminated with a \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)

Add global vector attributes with the specified name, length, and values.

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, either NcFile::Fill or NcFile::NoFill.

enum NcFile::FileFormat get_format( void ) const

Returns format version of the file, either NcFile::Classic, NcFile:Offset64Bits, NcFile:Netcdf4, or NcFile::Netcdf4Classic.

NcBool sync( void )

Synchronizes file to disk. This flushes buffers so that readers of the file will see recent changes.

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