Next: , Previous: Class NcTypedComponent, Up: NetCDF Classes


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 variables or add new variables.

Public Member Functions

NcToken name( void ) const
Returns the name of the variable.


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


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


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.


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.


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


NcAtt* get_att( NcToken attname ) const
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.


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


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.


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 get member function instead, to get single values or selected cross-sections of values.


NcBool put(const ncbyte* vals, long c0, long c1, long c2, long c3, long c4)
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 int* 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 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. The 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 [0,0,..., 0] by default, but may be reset using the set_cur() member function for this variable. 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 ncbyte* vals, const long* counts)
NcBool put(const char* vals, const long* counts)
NcBool put(const short* vals, const long* counts)
NcBool put(const int* vals, const long* counts)
NcBool put(const long* 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. The 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.


NcBool get(ncbyte* vals, long c0, long c1, long c2, long c3, long c4) const
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(int* 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(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. The 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 [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.


NcBool get(ncbyte* vals, const long* counts) const
NcBool get(char* vals, const long* counts) const
NcBool get(short* vals, const long* counts) const
NcBool get(int* vals, const long* counts) const
NcBool get(long* 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. 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 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.


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


NcBool add_att( NcToken, char )
NcBool add_att( NcToken, ncbyte )
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 ncbyte* )
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. These put file in define mode, so could be expensive. To avoid the expense of copying data, add attributes to variables before writing data.


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.


ncbyte as_ncbyte( int n ) const
char as_char( int n ) const
short as_short( int n ) const
int as_int( int n ) const
nclong as_nclong( int n ) const // deprecated
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 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.


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.


NcBool sync( void )
If the variable may have been renamed, make sure its name is updated.


~NcVar( void )
Destructor.

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.

long rec_size( void )
long rec_size( NcDim* )
Return the number of values per record or the number of values per dimension slice for the specified dimension.


NcValues* get_rec( void )
NcValues* get_rec( long n )
Get the data for this variable for the current record or for the nth record.
NcValues* get_rec( NcDim* )
NcValues* get_rec( NcDim*, long n )
Get the data for this variable for the current dimension slice or for the nth dimension slice.


NcBool put_rec( const ncbyte* vals )
NcBool put_rec( const char* vals )
NcBool put_rec( const short* vals )
NcBool put_rec( const int* vals )
NcBool put_rec( const long* vals )
NcBool put_rec( const float* vals )
NcBool put_rec( const double* vals )
Put a record's worth of data for this variable in the current record.
NcBool put_rec( NcDim*, const ncbyte* vals )
NcBool put_rec( NcDim*, const char* vals )
NcBool put_rec( NcDim*, const short* vals )
NcBool put_rec( NcDim*, const int* vals )
NcBool put_rec( NcDim*, const long* vals )
NcBool put_rec( NcDim*, const float* vals )
NcBool put_rec( NcDim*, const double* vals )
Put a dimension slice worth of data for this variable in the current dimension slice.


NcBool put_rec( const ncbyte* vals, long rec )
NcBool put_rec( const char* vals, long rec )
NcBool put_rec( const short* vals, long rec )
NcBool put_rec( const int* vals, long rec )
NcBool put_rec( const long* vals, long rec )
NcBool put_rec( const float* vals, long rec )
NcBool put_rec( const double* vals, long rec )
Put a record's worth of data for this variable in the specified record.
NcBool put_rec( NcDim*, const ncbyte* vals, long slice )
NcBool put_rec( NcDim*, const char* vals, long slice )
NcBool put_rec( NcDim*, const short* vals, long slice )
NcBool put_rec( NcDim*, const int* vals, long slice )
NcBool put_rec( NcDim*, const long* vals, long slice )
NcBool put_rec( NcDim*, const float* vals, long slice )
NcBool put_rec( NcDim*, const double* vals, long slice )
Put a dimension slice worth of data for this variable in the specified dimension slice.


long get_index( const ncbyte* vals )
long get_index( const char* vals )
long get_index( const short* vals )
long get_index( const int* vals )
long get_index( const long* vals )
long get_index( const float* vals )
long get_index( const double* vals )
Get first record index for this variable corresponding to the specified key value(s).
long get_index( NcDim*, const ncbyte* vals )
long get_index( NcDim*, const char* vals )
long get_index( NcDim*, const short* vals )
long get_index( NcDim*, const int* vals )
long get_index( NcDim*, const long* vals )
long get_index( NcDim*, const float* vals )
long get_index( NcDim*, const double* vals )
Get first index of specified dimension for this variable corresponding to the specified key value(s).


void set_rec ( long rec )
Set the current record for this variable.
void set_rec ( NcDim*, long rec )
Set the current dimension slice for the specified dimension for this variable.