## ucar.netcdf
Class Variable

    java.lang.Object
      ucar.netcdf.Variable

All Implemented Interfaces:
  Accessor, MultiArray, MultiArrayInfo, Named

public class Variable
extends Object
implements MultiArray, Named

Variable is a (potentially large) multi-dimensional array of primitives. The dimensions are named, allowing relationships between Variables to be expressed. Variables have names and may have descriptive attributes.

Objects which implement this interface exist in the context of a particular Netcdf data set. If you factor out the data access methods of this interface, leaving the descriptive "meta" information, what remains is a ProtoVariable.

Although there is no explicit relationship between this interface and class ProtoVariable, they share common method signatures and semantics where appropriate.

See Also:
  `ProtoVariable`, `MultiArray`

Field Summary
`(package private) Accessor` `io`
`(package private) ProtoVariable` `meta`

Constructor Summary
`Variable(ProtoVariable proto, Accessor io)` The usual constructor.

Method Summary
`(package private) void` `connectDims(DimensionDictionary dimensions)` Ensure that the dimensions referenced by this are members of the specified Dictionary.
`void` `copyin(int[] origin, MultiArray data)` Aggregate write access.
`MultiArray` `copyout(int[] origin, int[] shape)` Aggregate read access.
`Object` `get(int[] index)` Get (read) the array element at index.
`Attribute` `getAttribute(String name)` Convenience function; look up Attribute by name.
`AttributeSet` `getAttributes()` Returns the set of attributes associated with this.
`boolean` `getBoolean(int[] index)` Get the array element at index, as a boolean.
`byte` `getByte(int[] index)` Get the array element at index, as a byte.
`char` `getChar(int[] index)` Get the array element at index, as a char.
`Class` `getComponentType()` Returns the Class object representing the component type of the array.
`DimensionIterator` `getDimensionIterator()` Returns a DimensionIterator of the dimensions used by this variable.
`double` `getDouble(int[] index)` Get the array element at index, as a double.
`float` `getFloat(int[] index)` Get the array element at index, as a float.
`int` `getInt(int[] index)` Get the array element at index, as an int.
`int[]` `getLengths()` Discover the dimensions of this MultiArray.
`long` `getLong(int[] index)` Get the array element at index, as a long.
`String` `getName()` Returns the name of this Variable.
`int` `getRank()` Returns the number of dimensions.
`short` `getShort(int[] index)` Get the array element at index, as a short.
`Object` `getStorage()`
`boolean` `isScalar()` Convenience interface; return `true` if and only if the rank is zero.
`boolean` `isUnlimited()` Returns `true` if and only if the this variable can grow.
`void` `set(int[] index, Object value)` Set (modify, write) the array element at index to the specified value.
`void` `setBoolean(int[] index, boolean value)` Set the array element at index to the specified boolean value.
`void` `setByte(int[] index, byte value)` Set the array element at index to the specified byte value.
`void` `setChar(int[] index, char value)` Set the array element at index to the specified char value.
`void` `setDouble(int[] index, double value)` Set the array element at index to the specified double value.
`void` `setFloat(int[] index, float value)` Set the array element at index to the specified float value.
`void` `setInt(int[] index, int value)` Set the array element at index to the specified int value.
`void` `setLong(int[] index, long value)` Set the array element at index to the specified long value.
`void` `setShort(int[] index, short value)` Set the array element at index to the specified short value.
`Object` `toArray()` Returns a new array containing all of the elements in this MultiArray.
`Object` `toArray(Object dst, int[] origin, int[] shape)` Returns an array containing elements of this MultiArray specified by origin and shape, possibly converting the component type.
`void` `toCdl(StringBuffer buf)` Format as CDL.
`String` `toString()`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### meta

    final ProtoVariable meta

### io

    final Accessor io

Constructor Detail

### Variable

    public Variable(ProtoVariable proto,
                    Accessor io)

  The usual constructor. Think of it as package private or protected, let AbstactNetcdf call it for you.

Parameters:
  `proto` - the ProtoVariable used as metadata storage. Shouldn't be null. It should be immutable over the lifetime of this object. (If in doubt, hand this its own private copy.)

Method Detail

### getComponentType

    public Class getComponentType()

  Returns the Class object representing the component type of the array.

  Specified by:
    `getComponentType` in interface `MultiArrayInfo`
  Returns:
    Class of the component type
  See Also:
    `MultiArrayInfo.getComponentType()`

### getRank

    public int getRank()

  Returns the number of dimensions.

  Specified by:
    `getRank` in interface `MultiArrayInfo`
  Returns:
    int number of dimensions
  See Also:
    `MultiArrayInfo.getRank()`

### getLengths

    public int[] getLengths()

  Description copied from interface: `MultiArrayInfo`
  Discover the dimensions of this MultiArray.

  Specified by:
    `getLengths` in interface `MultiArrayInfo`
  Returns:
    int array whose length is the rank of this and whose elements represent the length of each of its dimensions
  See Also:
    `MultiArrayInfo.getLengths()`

### isUnlimited

    public boolean isUnlimited()

  Returns `true` if and only if the this variable can grow. This is equivalent to saying at least one of its dimensions is unlimited. In the current implementation, exactly one dimension, the most slowly varying (leftmost), can be unlimited.

  Specified by:
    `isUnlimited` in interface `MultiArrayInfo`
  Returns:
    boolean `true` iff this can grow

### isScalar

    public boolean isScalar()

  Convenience interface; return `true` if and only if the rank is zero.

  Specified by:
    `isScalar` in interface `MultiArrayInfo`
  Returns:
    boolean `true` iff rank == 0

### getName

    public String getName()

  Returns the name of this Variable.

  Specified by:
    `getName` in interface `Named`
  Returns:
    String which identifies this Variable.

### getDimensionIterator

    public DimensionIterator getDimensionIterator()

  Returns a DimensionIterator of the dimensions used by this variable. The most slowly varying (leftmost for java and C programmers) dimension is first. For scalar variables, the set has no elements and the iteration is empty.

  Returns:
    DimensionIterator of the elements.
  See Also:
    `DimensionIterator`

### getAttributes

    public AttributeSet getAttributes()

  Returns the set of attributes associated with this.

  Returns:
    AttributeSet. May be empty. Won't be null.

### getAttribute

    public Attribute getAttribute(String name)

  Convenience function; look up Attribute by name.

  Parameters:
    `name` - the name of the attribute
  Returns:
    the attribute, or null if not found

### get

    public Object get(int[] index)
               throws IOException

  Description copied from interface: `Accessor`
  Get (read) the array element at index. The returned value is wrapped in an object if it has a primitive type. Length of index must be greater than or equal to the rank of this. Values of index components must be less than corresponding values from getLengths().

  Specified by:
    `get` in interface `Accessor`
  Parameters:
    `index` - MultiArray index
  Returns:
    Object value at `index`
  Throws:
    `IOException`

### getBoolean

    public boolean getBoolean(int[] index)
                       throws IOException

  Description copied from interface: `Accessor`
  Get the array element at index, as a boolean.

  Specified by:
    `getBoolean` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.get(int[])`

### getChar

    public char getChar(int[] index)
                 throws IOException

  Description copied from interface: `Accessor`
  Get the array element at index, as a char.

  Specified by:
    `getChar` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.get(int[])`

### getByte

    public byte getByte(int[] index)
                 throws IOException

  Description copied from interface: `Accessor`
  Get the array element at index, as a byte.

  Specified by:
    `getByte` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.get(int[])`

### getShort

    public short getShort(int[] index)
                   throws IOException

  Description copied from interface: `Accessor`
  Get the array element at index, as a short.

  Specified by:
    `getShort` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.get(int[])`

### getInt

    public int getInt(int[] index)
               throws IOException

  Description copied from interface: `Accessor`
  Get the array element at index, as an int.

  Specified by:
    `getInt` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.get(int[])`

### getLong

    public long getLong(int[] index)
                 throws IOException

  Description copied from interface: `Accessor`
  Get the array element at index, as a long.

  Specified by:
    `getLong` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.get(int[])`

### getFloat

    public float getFloat(int[] index)
                   throws IOException

  Description copied from interface: `Accessor`
  Get the array element at index, as a float.

  Specified by:
    `getFloat` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.get(int[])`

### getDouble

    public double getDouble(int[] index)
                     throws IOException

  Description copied from interface: `Accessor`
  Get the array element at index, as a double.

  Specified by:
    `getDouble` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.get(int[])`

### set

    public void set(int[] index,
                    Object value)
             throws IOException

  Description copied from interface: `Accessor`
  Set (modify, write) the array element at index to the specified value. If the array has a primitive component type, the value may be unwrapped. Values of index components must be less than corresponding values from getLengths().

  Specified by:
    `set` in interface `Accessor`
  Parameters:
    `index` - MultiArray index
    `value` - the new value.
  Throws:
    `IOException`

### setBoolean

    public void setBoolean(int[] index,
                           boolean value)
                    throws IOException

  Description copied from interface: `Accessor`
  Set the array element at index to the specified boolean value.

  Specified by:
    `setBoolean` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.set(int[], java.lang.Object)`

### setChar

    public void setChar(int[] index,
                        char value)
                 throws IOException

  Description copied from interface: `Accessor`
  Set the array element at index to the specified char value.

  Specified by:
    `setChar` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.set(int[], java.lang.Object)`

### setByte

    public void setByte(int[] index,
                        byte value)
                 throws IOException

  Description copied from interface: `Accessor`
  Set the array element at index to the specified byte value.

  Specified by:
    `setByte` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.set(int[], java.lang.Object)`

### setShort

    public void setShort(int[] index,
                         short value)
                  throws IOException

  Description copied from interface: `Accessor`
  Set the array element at index to the specified short value.

  Specified by:
    `setShort` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.set(int[], java.lang.Object)`

### setInt

    public void setInt(int[] index,
                       int value)
                throws IOException

  Description copied from interface: `Accessor`
  Set the array element at index to the specified int value.

  Specified by:
    `setInt` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.set(int[], java.lang.Object)`

### setLong

    public void setLong(int[] index,
                        long value)
                 throws IOException

  Description copied from interface: `Accessor`
  Set the array element at index to the specified long value.

  Specified by:
    `setLong` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.set(int[], java.lang.Object)`

### setFloat

    public void setFloat(int[] index,
                         float value)
                  throws IOException

  Description copied from interface: `Accessor`
  Set the array element at index to the specified float value.

  Specified by:
    `setFloat` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.set(int[], java.lang.Object)`

### setDouble

    public void setDouble(int[] index,
                          double value)
                   throws IOException

  Description copied from interface: `Accessor`
  Set the array element at index to the specified double value.

  Specified by:
    `setDouble` in interface `Accessor`
  Throws:
    `IOException`
  See Also:
    `Accessor.set(int[], java.lang.Object)`

### copyout

    public MultiArray copyout(int[] origin,
                              int[] shape)
                       throws IOException

  Description copied from interface: `Accessor`
  Aggregate read access. Return a new MultiArray of the same componentType as this, and with shape as specified, which is initialized to the values of this, as clipped to (origin, origin + shape).

  It is easier to implement than to specify :-).

  The main reason to implement this instead of using the equivalent proxy is for remote or file access.

  `assert(origin[ii] + shape[ii] <= lengths[ii]);`

  Specified by:
    `copyout` in interface `Accessor`
  Parameters:
    `origin` - int array specifying the starting index.
    `shape` - int array specifying the extents in each dimension. This becomes the shape of the return.
  Returns:
    the MultiArray with the specified shape
  Throws:
    `IOException`

### copyin

    public void copyin(int[] origin,
                       MultiArray data)
                throws IOException

  Description copied from interface: `Accessor`
  Aggregate write access. Given a MultiArray, copy it into this at the specified starting index. TODO: clearer specification.

  Hopefully this member can be optimized in various situations.

  `assert(origin[ii] + (source.getLengths())[ii] <= (getLengths())[ii]);`

  Specified by:
    `copyin` in interface `Accessor`
  Parameters:
    `origin` - int array specifying the starting index.
    `data` - MultiArray with the same componentType as this and shape smaller than `this.getLengths() - origin`
  Throws:
    `IOException`

### toArray

    public Object toArray()
                   throws IOException

  Description copied from interface: `Accessor`
  Returns a new array containing all of the elements in this MultiArray. The returned array is one dimensional. The order of the elements in the result is natural, as if we used an IndexIterator to step through the elements of this MultiArray. The component type of the result is the same as this.

  This method acts as bridge between array-based and MultiArray-based APIs.

  This method is functionally equivalent to

                      Object anArray = Array.newInstance(getComponentType(), 1);
                      int [] origin = new int[getRank()]
                      int [] shape = getDimensions();
                      return toArray(anArray, origin, shape);

  Specified by:
    `toArray` in interface `Accessor`
  Returns:
    a one dimensional Array containing all the elements in this MultiArray
  Throws:
    `IOException`

### getStorage

    public Object getStorage()

  Specified by:
    `getStorage` in interface `MultiArray`
  Returns:
    a the original one dimensional Array containing all the elements in this MultiArray

### toArray

    public Object toArray(Object dst,
                          int[] origin,
                          int[] shape)
                   throws IOException

  Description copied from interface: `Accessor`
  Returns an array containing elements of this MultiArray specified by origin and shape, possibly converting the component type. The returned array is one dimensional. The order of the elements in the result is natural, as if we used an IndexIterator to step through the elements of this MultiArray.

  The anArray argument should be an array. If it is large enough to contain the output, it is used and no new storage is allocated. Otherwise, new storage is allocated with the same component type as the argument, and the data is copied into it.

  This method acts as bridge between array-based and MultiArray-based APIs.

  This method is similar to copyout(origin, shape).toArray(), but avoids a copy operation and (potentially) an allocation.

  NOTE: Implementation of type conversion is deferred until JDK 1.2. Currently, the componentType of `anArray` must be the same as `this`

  Specified by:
    `toArray` in interface `Accessor`
  Returns:
    a one dimensional Array containing the specified elements
  Throws:
    `IOException`

### toCdl

    public void toCdl(StringBuffer buf)

  Format as CDL.

  Parameters:
    `buf` - StringBuffer into which to write

### toString

    public String toString()

  Returns:
    a CDL string of this.

### connectDims

    void connectDims(DimensionDictionary dimensions)

  Ensure that the dimensions referenced by this are members of the specified Dictionary. This may modify dimArray elements to reference different (equivalent) dimension instances. package private