Atomic Data Types

CDL netCDF-C netCDF-Java Description Availability
char NC_CHAR CHAR 8-bit character Classic, CDF-5, Enhanced
byte NC_BYTE BYTE 8-bit signed integer Classic, CDF-5, Enhanced
short NC_SHORT SHORT 16-bit signed integer Classic, CDF-5, Enhanced
int NC_INT INT 32-bit signed integer Classic, CDF-5, Enhanced
long NC_LONG Deprecated: synonymous with int
float NC_FLOAT FLOAT IEEE single-precision floating point (32 bits) Classic, CDF-5, Enhanced
real Deprecated: Synonymous with float
double NC_DOUBLE DOUBLE IEEE double-precision floating point (64 bits) Classic, CDF-5, Enhanced
ubyte NC_UBYTE UBYTE Unsigned 8-bit integer CDF-5, Enhanced
ushort NC_USHORT USHORT Unsigned 16-bit integer CDF-5, Enhanced
uint NC_UINT UINT Unsigned 32-bit integer CDF-5, Enhanced
int64 NC_INT64 LONG 64-bit signed integer CDF-5, Enhanced
uint64 NC_UINT64 ULONG Unsigned 64-bit signed integer CDF-5, Enhanced
string NC_STRING STRING Variable-length string of characters Enhanced

The netCDF atomic data types provide a variety of integer, floating point, and character data types. The data types in different programming languages and on different computing platforms will not necessarily align with the netCDF atomic data types. In those cases conversions will be necessary and are generally handled by the different language libraries.

Conversion Advice ???

Converting from one numeric type to another may result in an error if the target type is not capable of representing the converted value.

Note that mere loss of precision in type conversion does not return an error. Thus, if you read double precision values into a single-precision floating-point variable, for example, no error results unless the magnitude of the double precision value exceeds the representable range of single-precision floating point numbers on your platform. Similarly, if you read a large integer into a float incapable of representing all the bits of the integer in its mantissa, this loss of precision will not result in an error. If you want to avoid such precision loss, check the external types of the variables you access to make sure you use an internal type that has adequate precision.

Byte data in netCDF

Because the netCDF classic data model only has the byte type (byte), byte data in the classic data model can be interpreted as either signed (-128 to 127) or unsigned (0 to 255). Several conventions have developed over the years for dealing with this situation (see Best Practices “Unsigned Data” section).

Both the enhanced data model and the CDF-5 file format support unsigned bytes (ubyte). So the issue can be avoided by using either of them.

String data types in netCDF

//: # (TODO: “_Encoding” variable attribute is described in nc-3 spec. Should it be included in data model?) //: # ( Info on string/char and encodings was in nc-3 file format spec, CDL page, and Best Practices.) Text strings can be stored as fixed-length char arrays or as variable-length string values. While netCDF object names must be encoded as UTF-8, variables and attributes storing text strings may use other encodings. The variable attribute “_Encoding” is reserved for this purpose in future implementations (though this is not a widely used convention). If an “_Encoding” variable attribute is not provided, the default is to assume UTF-8 encoding.

Because attributes are either scalar or vector,

User Defined Data Types

The Enhanced Data Model supports compound types (similar to C-structs), VLEN types (which can be used for ragged arrays), opaque types ( to blobs of bytes), and enumerations.

Types may be nested in complex ways. For example, a compound type containing an array of VLEN types, each containing variable length arrays of some other compound type, etc. Users are cautioned to keep types simple. Reading data of complex types can be challenging, especially perhaps for Fortran users.

Types cannot have attributes (but variables of the type may have attributes).

Scope of User Defined Types in a Group Hierarchy

Types may be defined in any group in the data file, but they are always available globally in the file.

Compound Types

The compound type can be used to define a data structure which contains an arbitrary collection of other data types, including other compound types. A compound type is defined by its name and the set of named fields in the compound type where each named field is defined by its name and data type.

VLEN Types

The VLEN type can be used to store variable length arrays of a known base type, providing support for ragged arrays. A VLEN type is defined by its name and it’s base type. A VLEN base type may be of any type, including user-defined types. Access to the values of a VLEN variable is atomic. The number of values contained by a VLEN variable is determined when that variable is written and discovered when the variable is read. If a field in a compound type is of type VLEN, the size of that field in a variable is determined/discovered when that component is written/read.

Opaque Types

The opaque type can be used to store a collection/sequence of bytes where the number of bytes is known. An opaque type is defined by its name and its size in bytes.

Enum Types

The enumerated type can be used to associate integer constant values with names/labels. An enumerated type is defined by its name, its base type (any integer type), and by its member value/name pairs. The integer member values need not be consecutive. The underlying base integer type is what is stored in the netCDF dataset.