Package ucar.nc2

Class 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 Detail

      • VLEN

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

    • Constructor Detail

      • 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 Detail

      • 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

      • 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

      • hashCode

        public int hashCode()
        Override Object.hashCode() to implement equals.
        Overrides:
        hashCode 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

      • builder

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