Package ucar.nc2

Class Structure

java.lang.Object
ucar.nc2.CDMNode
ucar.nc2.Variable
ucar.nc2.Structure
All Implemented Interfaces:
Comparable<VariableSimpleIF>, Iterable<Attribute>, AttributeContainer, ProxyReader, VariableSimpleIF
Direct Known Subclasses:
Sequence, StructureDS
public class Structure extends Variable
A Structure is a type of Variable that contains other Variables, like a struct in C. A Structure can be scalar or multidimensional.

A call to structure.read() will read all of the data in a Structure, including nested structures, and returns an Array of StructureData, with all of the data in memory. If there is a nested sequence, the sequence data may be read into memory all at once, or it may be read in increments as the iteration proceeds.

Generally, the programmer can assume that the data in one Structure are stored together, so that it is efficient to read an entire Structure, and then access the Variable data through the Arrays in the StructureData.

  • Method Details

    • select

      public Structure select(List<String> memberNames)
      Create a subset of the Structure consisting only of the given member variables
      Parameters:
      memberNames - list of Variable names, already a member
      Returns:
      Structure containing just those members

    • select

      public Structure select(String varName)
      Create a subset of the Structure consisting only of the one member variable
      Parameters:
      varName - name of member Variable
      Returns:
      containing just that member

    • isSubset

      public boolean isSubset()
      Find if this was created from a subset() method.
      Returns:
      true if this is a subset

    • isCaching

      public boolean isCaching()
      Caching is not allowed
      Overrides:
      isCaching in class Variable
      Returns:
      true is caching

    • setCaching

      public void setCaching(boolean caching)
      Caching is not allowed

    • getVariables

      public com.google.common.collect.ImmutableList<Variable> getVariables()
      Get the variables contained directly in this Structure.

    • getNumberOfMemberVariables

      public int getNumberOfMemberVariables()
      Get the number of variables contained directly in this Structure.

    • getVariableNames

      public com.google.common.collect.ImmutableList<String> getVariableNames()
      Get the (short) names of the variables contained directly in this Structure.

    • findVariable

      public Variable findVariable(String shortName)
      Find the Variable member with the specified (short) name.
      Parameters:
      shortName - name of the member variable.
      Returns:
      the Variable member with the specified (short) name, or null if not found.

    • makeStructureMembers

      public StructureMembers makeStructureMembers()
      Create a StructureMembers object that describes this Structure. CAUTION: Do not use for iterating over a StructureData or ArrayStructure - get the StructureMembers object directly from the StructureData or ArrayStructure.
      Returns:
      a StructureMembers object that describes this Structure.

    • getElementSize

      public int getElementSize()
      Get the size of one element of the Structure.
      Overrides:
      getElementSize in class Variable
      Returns:
      size (in bytes)

    • readStructure

      public StructureData readStructure(int index) throws IOException, InvalidRangeException
      Use this when this is a one dimensional array of Structures, or you are doing the index calculation yourself for a multidimension array. This will read only the ith structure, and return the data as a StructureData object.
      Parameters:
      index - index into 1D array
      Returns:
      ith StructureData
      Throws:
      IOException - on read error
      InvalidRangeException - if index out of range

    • readStructure

      public ArrayStructure readStructure(int start, int count) throws IOException, InvalidRangeException
      For rank 1 array of Structures, read count Structures and return the data as an ArrayStructure. Use only when this is a one dimensional array of Structures.
      Parameters:
      start - start at this index
      count - return this many StructureData
      Returns:
      the StructureData recordsfrom start to start+count-1
      Throws:
      IOException - on read error
      InvalidRangeException - if start, count out of range

    • getStructureIterator

      public StructureDataIterator getStructureIterator() throws IOException
      Iterator over all the data in a Structure. 
       StructureDataIterator ii = structVariable.getStructureIterator();
 while (ii.hasNext()) {
   StructureData sdata = ii.next();
 }
      Returns:
      StructureDataIterator over type StructureData
      Throws:
      IOException - on read error
      See Also:

    • getStructureIterator

      public StructureDataIterator getStructureIterator(int bufferSize) throws IOException
      Get an efficient iterator over all the data in the Structure. This is the efficient way to get all the data, it can be much faster than reading one record at a time, and is optimized for large datasets. This is accomplished by buffering bufferSize amount of data at once. 
       Example:

  StructureDataIterator ii = structVariable.getStructureIterator(100 * 1000);
  while (ii.hasNext()) {
    StructureData sdata = ii.next();
  }
      Parameters:
      bufferSize - size in bytes to buffer, set < 0 to use default size
      Returns:
      StructureDataIterator over type StructureData
      Throws:
      IOException - on read error

    • getNameAndAttributes

      public String getNameAndAttributes()
      Get String with name and attributes. Used in short descriptions like tooltips.
      Returns:
      name and attributes String

    • toBuilder

      public Structure.Builder<?> toBuilder()
      Turn into a mutable Builder. Can use toBuilder().build() to copy.
      Overrides:
      toBuilder in class Variable

    • builder

      public static Structure.Builder<?> builder()
      Get Builder for this class that allows subclassing.
      See Also:
      • "https://community.oracle.com/blogs/emcmanus/2010/10/24/using-builder-pattern-subclasses"