Class Dimensions


  • public class Dimensions
    extends java.lang.Object
    A dimensions specification is a record of the measurement dimensions of a quantity.

    The dimensions here match those in the ‘International System of Quantities’ (ISQ), ISO 80000-1:2009.

    They also match the dimensions in the QUDT framework of quantities, units and dimensions, although it is not necessary to be familiar with that framework in order to use the Dimensions class. The methods here are primarily intended to be used to query the dimensions of an existing object.

    There is a parser, parse(java.lang.String), which can create new dimension quantities, should that be necessary. That parser is rather ad-hoc, however, and the syntax it handles is not really specified here, but it is made visible in case there is some use for it, without at present any commitments that the syntax or the interface is stable. The constructor is not public: the parse method is the only public way of constructing Dimension objects.

    The QUDT dimension string is a sequence of letters [ULMTΘINJ] and powers. These match the ‘quantities’ in ISO 80000-1, with the addition of ‘U’, which the QUDT authors use when describing the Lumen as Candela-steradian, with string U J, and the Lux, with string U L^-2 J. Here, we ignore the U specifiers, and insist that they are never followed by any power. These ‘U’ specifiers do not appear in any output.

    The dimensions in the ISQ are

    SI base units
    SymbolNameSI base unit
    LLengthMetre
    MMassKilogramme
    TTimeSecond
    IElectric currentAmpère
    ΘThermodynamic temperatureKelvin
    NAmount of substanceMole
    JLuminous intensityCandela
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Dimensions.BaseQuantity
      The base quantities in the International System of Quantites.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      float exponent​(Dimensions.BaseQuantity q)
      Return the exponent of the given base quantity.
      float[] exponents()
      Deprecated.
      java.lang.String getURI()
      Return a URI naming one of the dimensions in the QUDT dimensions ontology.
      static Dimensions multiply​(java.lang.Iterable<Dimensions> dimlist)
      Multiplies several dimensions together, and returns a (new) object representing the dimensions of the result.
      Dimensions multiply​(Dimensions d)
      Respond with a Dimensions object which is the result of multiplying the dimensions of this object by the dimensions of another.
      Dimensions multiply​(Dimensions d, float pow)
      Respond with a Dimensions object which is the result of multiplying the dimensions of this object by the dimensions of another raised to the given power.
      static Dimensions parse​(java.lang.String dimensionString)
      Parse a dimension string to produce a new dimension object.
      java.lang.String toString()
      Return a string representation of the dimension.
      static Dimensions unity()
      Returns a new Dimensions object representing 1.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Method Detail

      • unity

        public static final Dimensions unity()
        Returns a new Dimensions object representing 1.
        Returns:
        a new Dimensions object
      • multiply

        public Dimensions multiply​(Dimensions d)
        Respond with a Dimensions object which is the result of multiplying the dimensions of this object by the dimensions of another. This will be a new object, if the resulting dimensions are different.
        Parameters:
        d - the dimensions object we want to multiply by
        Returns:
        a new Dimensions object
      • multiply

        public Dimensions multiply​(Dimensions d,
                                   float pow)
        Respond with a Dimensions object which is the result of multiplying the dimensions of this object by the dimensions of another raised to the given power. This will be a new object, if the resulting dimensions are different.
        Parameters:
        d - a Dimensions object which is to multiply this one
        pow - the power to which the dimensions argument is raised
        Returns:
        a new Dimensions object
      • multiply

        public static Dimensions multiply​(java.lang.Iterable<Dimensions> dimlist)
        Multiplies several dimensions together, and returns a (new) object representing the dimensions of the result. If any of the Dimensions in the list are null, the result is null (and not an error)
        Parameters:
        dimlist - a collection of dimensions to be multiplied together
        Returns:
        a new Dimensions object
      • getURI

        public java.lang.String getURI()
        Return a URI naming one of the dimensions in the QUDT dimensions ontology. We construct this based on the dimensions of the current quantity, using the QUDT system, rather than looking it up; it's therefore possible to construct a dimension which isn't included in that set.
        Returns:
        a String naming a dimension
      • toString

        public java.lang.String toString()
        Return a string representation of the dimension. The format of this string is not specified here, but it is intended to be (roughly) human-readable. A dimensionless quantity is reported as having units "1".
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of the dimension
      • exponents

        @Deprecated
        public float[] exponents()
        Deprecated.
        Return the numerical dimensions of the quantities in the expression. The result is an array of the exponents of the base dimensions, in the order 'L', 'M', 'T', 'I', 'Θ', 'N', 'J'.
        Returns:
        a list of floats, representing powers of base quantities
      • exponent

        public float exponent​(Dimensions.BaseQuantity q)
        Return the exponent of the given base quantity. For example, a unit "m.s^-1" would produce a Dimensions object for which exponent(BaseQuantity.LENGTH) would be 1, exponent(BaseQuantity.TIME) would be -1, and the others zero.
        Parameters:
        q - the quantity to inspect
        Returns:
        the exponent of the given quantity in the set of dimensions
      • parse

        public static Dimensions parse​(java.lang.String dimensionString)
                                throws UnitParserException
        Parse a dimension string to produce a new dimension object. If the string is not parseable, throw an exception.

        A dimensions string consists of a sequence of capital letter dimensions, and powers, for example "M L2T-2" for the dimensions of "kg m2 s-2". The dimensions are as discussed in the class overview above. The syntax here is slightly more general than is required to handle the existing QUDT dimension strings.

        Since the domain is so restricted, the parsing can be very liberal, and everything which isn't a letter, or part of a number, is ignored (for example '^'). That means, by the way, that a string like 'ML2/T2' wouldn't have the same dimensions as the example above. If any letters appear which are not one of the known dimension letters, we throw an exception.

        Parameters:
        dimensionString - a string composed of a sequence of dimension letters and numbers
        Returns:
        a new Dimensions object
        Throws:
        UnitParserException - if the string is malformed