Package ucar.nc2

Class Dimension

java.lang.Object
ucar.nc2.CDMNode
ucar.nc2.Dimension
All Implemented Interfaces:
Comparable<Dimension>
public class Dimension extends CDMNode implements Comparable<Dimension>
A Dimension is used to define the array shape of a Variable. A Variable can be thought of as a sampled function with Domain its Dimensions. A Dimension may be shared among Variables, which provides a simple yet powerful way of associating Variables. When a Dimension is shared, it has a unique name within its Group. It may have a coordinate Variable, which gives each index a coordinate value. A private Dimension cannot have a coordinate Variable, so use shared dimensions with coordinates when possible. The Dimension length must be > 0, except for an unlimited dimension which may have length = 0, and a vlen Dimension which has a length known only when the variable is read.

Immutable if setImmutable() was called, except for an Unlimited Dimension, whose size can change.

Note: this class has a natural ordering that is inconsistent with equals. TODO Dimension will be immutable in 6. TODO Dimension will not extend CDMNode in 6. TODO Dimension will not have a reference to its owning Group in 6. TODO Dimension.getFullName() will not exist in 6.

  • Field Details

    • VLEN

      public static final Dimension VLEN
      A variable-length dimension: the length is not known until the data is read.

  • Constructor Details

    • Dimension

      public Dimension(String name, int length)
      Constructor
      Parameters:
      name - name must be unique within group
      length - length of Dimension

    • Dimension

      @Deprecated public Dimension(String name, int length, boolean isShared)
      Deprecated.
      Use Dimension.builder()
      Constructor
      Parameters:
      name - name must be unique within group
      length - length, or UNLIMITED.length or UNKNOWN.length
      isShared - whether its shared or local to Variable.

    • Dimension

      public Dimension(String name, int length, boolean isShared, boolean isUnlimited, boolean isVariableLength)
      Constructor
      Parameters:
      name - name must be unique within group. Can be null only if not shared.
      length - length, or UNLIMITED.length or UNKNOWN.length
      isShared - whether its shared or local to Variable.
      isUnlimited - whether the length can grow.
      isVariableLength - whether the length is unknown until the data is read.

    • Dimension

      @Deprecated public Dimension(String name, Dimension from)
      Deprecated.
      Use Dimension.builder()
      Copy Constructor. used to make global dimensions
      Parameters:
      name - name must be unique within group. Can be null only if not shared.
      from - copy all other fields from here.

  • Method Details

    • makeDimensionsString

      @Deprecated public static String makeDimensionsString(List<Dimension> dimensions)
      Deprecated.
      use Dimensions.makeDimensionsString()
      Make a space-delineated String from a list of Dimension names. Inverse of makeDimensionsList().
      Returns:
      space-delineated String of Dimension names.

    • makeDimensionsList

      @Deprecated public static List<Dimension> makeDimensionsList(Group parentGroup, String dimString) throws IllegalArgumentException
      Deprecated.
      use Group.makeDimensionsList()
      Create a dimension list using the dimensions names. The dimension is searched for recursively in the parent groups, so it must already have been added. Inverse of makeDimensionsString().
      Parameters:
      parentGroup - containing group, may not be null
      dimString - : whitespace separated list of dimension names, or '*' for Dimension.UNKNOWN, or number for anon dimension. null or empty String is a scalar.
      Returns:
      list of dimensions
      Throws:
      IllegalArgumentException - if cant find dimension or parse error.

    • makeDimensionsList

      @Deprecated public static List<Dimension> makeDimensionsList(List<Dimension> dimensions, String dimString)
      Deprecated.
      use Dimensions.makeDimensionsList()
      Create a dimension list using the dimensions names. Inverse of makeDimensionsString().
      Parameters:
      dimensions - list of possible dimensions, may not be null
      dimString - : whitespace separated list of dimension names, or '*' for Dimension.UNKNOWN, or number for anon dimension. null or empty String is a scalar.
      Returns:
      list of dimensions
      Throws:
      IllegalArgumentException - if cant find dimension or parse error.

    • makeDimensionsAnon

      @Deprecated public static List<Dimension> makeDimensionsAnon(int[] shape)
      Deprecated.
      use Dimensions.makeDimensionsAnon()

    • toBuilder

      public Dimension.Builder toBuilder()
      Turn into a mutable Builder, use toBuilder().build() to make a copy.

    • getLength

      public int getLength()
      Get the length of the Dimension.

    • getName

      public String getName()
      Get the name of the Dimension. Same as getShortName. Not deprecated.
      Overrides:
      getName in class CDMNode

    • getShortName

      public String getShortName()
      Get the name of the Dimension.
      Overrides:
      getShortName in class CDMNode

    • isUnlimited

      public boolean isUnlimited()
      If this is a NetCDF unlimited dimension. The length might increase between invocations, but it remains fixed for the lifetime of the NetcdfFile. If you modify the file in a separate process, you must close and reopen the file.
      Returns:
      if its an "unlimited" Dimension

    • isVariableLength

      public boolean isVariableLength()
      If variable length, then the length is unknown until the data is read.
      Returns:
      if its a "variable length" Dimension.

    • isShared

      public boolean isShared()
      If this Dimension is shared, or is private to a Variable. All Dimensions in NetcdfFile.getDimensions() or Group.getDimensions() are shared. Dimensions in the Variable.getDimensions() may be shared or private.
      Returns:
      if its a "shared" Dimension.

    • getGroup

      @Deprecated public Group getGroup()
      Deprecated.
      Do not use.
      Get the Group that owns this Dimension.
      Overrides:
      getGroup in class CDMNode
      Returns:
      owning group or null if !isShared

    • makeFullName

      @Deprecated public String makeFullName()
      Deprecated.
      Do not use.

    • equals

      public boolean equals(Object oo)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Override Object.hashCode() to implement equals.
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • compareTo

      public int compareTo(Dimension odim)
      Dimensions with the same name are equal. This method is inconsistent with equals()!
      Specified by:
      compareTo in interface Comparable<Dimension>
      Parameters:
      odim - compare to this Dimension
      Returns:
      0, 1, or -1

    • writeCDL

      @Deprecated public String writeCDL(boolean strict)
      Deprecated.
      use CDLWriter
      CDL representation.
      Parameters:
      strict - if true, write in strict adherence to CDL definition.
      Returns:
      CDL representation.

    • setUnlimited

      @Deprecated public void setUnlimited(boolean b)
      Deprecated.
      Use Dimension.builder()
      Set whether this is unlimited, meaning length can increase.
      Parameters:
      b - true if unlimited

    • setVariableLength

      @Deprecated public void setVariableLength(boolean b)
      Deprecated.
      Use Dimension.builder()
      Set whether the length is variable.
      Parameters:
      b - true if variable length

    • setShared

      @Deprecated public void setShared(boolean b)
      Deprecated.
      Use Dimension.builder()
      Set whether this is shared.
      Parameters:
      b - true if shared

    • setLength

      @Deprecated public void setLength(int n)
      Deprecated.
      Use Dimension.builder()
      Set the Dimension length.
      Parameters:
      n - length of Dimension

    • setName

      @Deprecated public String setName(String name)
      Deprecated.
      Use Dimension.builder()
      Set the name, converting to valid CDM object name if needed.
      Parameters:
      name - set to this value
      Returns:
      valid CDM object name

    • setGroup

      @Deprecated public void setGroup(Group g)
      Deprecated.
      Use Dimension.builder()
      Set the group
      Parameters:
      g - parent group

    • setImmutable

      @Deprecated public Dimension setImmutable()
      Deprecated.
      Use Dimension.builder()
      Make this immutable.
      Overrides:
      setImmutable in class CDMNode
      Returns:
      this

    • builder

      public static Dimension.Builder builder()

    • builder

      public static Dimension.Builder builder(String name, int length)
      A builder with the Dimension name and length set