Module org.hdfgroup.object
Package hdf.object.nc2

# Class NC2Datatype

Object
hdf.object.HObject
hdf.object.Datatype
hdf.object.nc2.NC2Datatype

All Implemented Interfaces:
  `MetaDataContainer`, `Serializable`

public class NC2Datatype extends Datatype
Datatype encapsulates information of a datatype. Information includes the class, size, endian of a datatype.

Version:
  1.1 9/4/2007
Author:
  Peter X. Cao
See Also:
  - Serialized Form

- ## Field Summary

  ### Fields inherited from class hdf.object.Datatype

  `arrayDims, baseType, CLASS_ARRAY, CLASS_BITFIELD, CLASS_CHAR, CLASS_COMPOUND, CLASS_ENUM, CLASS_FLOAT, CLASS_INTEGER, CLASS_NO_CLASS, CLASS_OPAQUE, CLASS_REFERENCE, CLASS_STRING, CLASS_TIME, CLASS_VLEN, compoundMemberNames, compoundMemberOffsets, compoundMemberTypes, datatypeClass, datatypeDescription, datatypeNATIVE, datatypeOrder, datatypeSign, datatypeSize, enumMembers, isNamed, isVariableStr, isVLEN, NATIVE, NSGN, ORDER_BE, ORDER_LE, ORDER_NONE, ORDER_VAX, SIGN_2, SIGN_NONE`

  ### Fields inherited from class hdf.object.HObject

  `fileFormat, linkTargetObjName, oid, SEPARATOR`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `NC2Datatype(int tclass, int tsize, int torder, int tsign)`
  Create an Datatype with specified class, size, byte order and sign.
  `NC2Datatype(ucar.ma2.DataType theType)`
  Constructs a NC2Datatype with a given NetCDF3 native datatype object.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static final Object`
  `allocateArray(ucar.ma2.DataType dtype, int datasize)`
  Allocate an one-dimensional array of byte, short, int, long, float, double, or String to store data retrieved from an NetCDF3 file based on the given NetCDF3 datatype and dimension sizes.
  `void`
  `close(long id)`
  Closes a datatype identifier.
  `long`
  `createNative()`
  Converts the datatype object to a native datatype.
  `void`
  `fromNative(long tid)`
  Translate NetCDF3 datatype object into NC2Datatype.
  `String`
  `getDescription()`
  Returns a short text description of this datatype.
  `List`
  `getMetadata(int... attrPropList)`
  Retrieves the object's metadata, such as attributes, from the file.
  `boolean`
  `hasAttribute()`
  Check if the object has any attributes attached.
  `boolean`
  `isText()`
  Checks if this datatype is a boolean type.
  `boolean`
  `isUnsigned()`
  Checks if this datatype is unsigned.

  ### Methods inherited from class hdf.object.Datatype

  `clear, getArrayDims, getCompoundMemberNames, getCompoundMemberOffsets, getCompoundMemberTypes, getDatatypeBase, getDatatypeClass, getDatatypeOrder, getDatatypeSign, getDatatypeSize, getEnumMembers, getEnumMembersAsString, getMetadata, getReferenceType, isArray, isBitField, isChar, isCompound, isEnum, isFloat, isInteger, isNamed, isOpaque, isRef, isString, isVarStr, isVLEN, open, removeMetadata, setEnumMembers, toString, updateMetadata, writeMetadata`

  ### Methods inherited from class hdf.object.HObject

  `createFullname, debug, equals, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, hashCode, setFullname, setLinkTargetObjName, setName, setPath`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### NC2Datatype

    public NC2Datatype(int tclass, int tsize, int torder, int tsign) throws Exception
    Create an Datatype with specified class, size, byte order and sign. The following list a few example of how to create a Datatype.
    1. to create unsigned native integer
       NC2Datatype type = new NC2Datatype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE);
    2. to create 16-bit signed integer with big endian
       NC2Datatype type = new NC2Datatype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE);
    3. to create native float
       NC2Datatype type = new NC2Datatype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE);
    4. to create 64-bit double
       NC2Datatype type = new NC2Datatype(Datatype.CLASS_FLOAT, 8, Datatype.NATIVE, Datatype.NATIVE);
    Parameters:
      `tclass` - the class of the datatype, e.g. CLASS_INTEGER, CLASS_FLOAT and etc.
      `tsize` - the size of the datatype in bytes, e.g. for a 32-bit integer, the size is 4. Valid values are NATIVE or a positive value.
      `torder` - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX, ORDER_NONE and NATIVE.
      `tsign` - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and NATIVE.
    Throws:
      `Exception` - if there is an error

  - ### NC2Datatype

    public NC2Datatype(ucar.ma2.DataType theType) throws Exception
    Constructs a NC2Datatype with a given NetCDF3 native datatype object.
    Parameters:
      `theType` - the netcdf native datatype.
    Throws:
      `Exception` - if there is an error

- ## Method Details

  - ### fromNative

    public void fromNative(long tid)
    Translate NetCDF3 datatype object into NC2Datatype.
    Specified by:
      `fromNative` in class `Datatype`
    Parameters:
      `tid` - the native ID UNUSED.

  - ### allocateArray

    public static final Object allocateArray(ucar.ma2.DataType dtype, int datasize) throws OutOfMemoryError
    Allocate an one-dimensional array of byte, short, int, long, float, double, or String to store data retrieved from an NetCDF3 file based on the given NetCDF3 datatype and dimension sizes.
    Parameters:
      `dtype` - the NetCDF3 datatype object.
      `datasize` - the size of the data array
    Returns:
      an array of 'datasize' numbers of datatype.
    Throws:
      `OutOfMemoryError` - if the array cannot be allocated

  - ### getDescription

    public String getDescription()
    Description copied from class: `Datatype`
    Returns a short text description of this datatype.
    Overrides:
      `getDescription` in class `Datatype`
    Returns:
      a short text description of this datatype

  - ### isUnsigned

    public boolean isUnsigned()
    Description copied from class: `Datatype`
    Checks if this datatype is unsigned.
    Overrides:
      `isUnsigned` in class `Datatype`
    Returns:
      true if the datatype is unsigned; otherwise, returns false.

  - ### isText

    public boolean isText()
    Description copied from class: `Datatype`
    Checks if this datatype is a boolean type.
    Specified by:
      `isText` in class `Datatype`
    Returns:
      true if the datatype is boolean; false otherwise

  - ### createNative

    public long createNative()
    Description copied from class: `Datatype`
    Converts the datatype object to a native datatype. Subclasses must implement it so that this datatype will be converted accordingly. Use close() to close the native identifier; otherwise, the datatype will be left open. For example, a HDF5 datatype created from

         H5Dataype dtype = new H5Datatype(CLASS_INTEGER, 4, NATIVE, SIGN_NONE);
         int tid = dtype.createNative();

    The "tid" will be the HDF5 datatype id of a 64-bit unsigned integer, which is equivalent to

         int tid = H5.H5Tcopy(HDF5Constants.H5T_NATIVE_UNINT32);

    Specified by:
      `createNative` in class `Datatype`
    Returns:
      the identifier of the native datatype.

  - ### close

    public void close(long id)
    Description copied from class: `Datatype`
    Closes a datatype identifier. Sub-classes must replace this default implementation.
    Specified by:
      `close` in class `Datatype`
    Parameters:
      `id` - the datatype identifier to close.

  - ### getMetadata

    public List getMetadata(int... attrPropList) throws Exception
    Retrieves the object's metadata, such as attributes, from the file. Metadata, such as attributes, is stored in a List.
    Parameters:
      `attrPropList` - the list of properties to get
    Returns:
      the list of metadata objects.
    Throws:
      `Exception` - if the metadata can not be retrieved

  - ### hasAttribute

    public boolean hasAttribute()
    Check if the object has any attributes attached.
    Returns:
      true if it has any attributes, false otherwise.