Package com.adobe.xfa.ut

Class UnitSpan

  • All Implemented Interfaces:
    java.lang.Comparable<UnitSpan>
    public final class UnitSpan
extends java.lang.Object
implements java.lang.Comparable<UnitSpan>
    A class to describe a unit span. It consists of a value with a units specification. Unit spans of unknown units are valid.

    Instances of this class are immutable. All change operations return a new instance of this UnitSpan class.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  UnitSpan.ParseData
      A class returned by the validatingParse() method.

    • Constructor Summary

      Constructors 
      Constructor Description
      UnitSpan()
      Instantiates a UnitSpan with the value 0 and default units INCHES_72K.
      UnitSpan​(double dValue, int eUnits)
      Instantiates a UnitSpan with the given double value and units.
      UnitSpan​(int nValue)
      Instantiates a UnitSpan with the given int value and unknown units.
      UnitSpan​(int eUnits, int nValue)
      Instantiates a UnitSpan with the given units and optional value.
      UnitSpan​(int eNewUnits, int eOldUnits, int nOldValue)
      Instantiates a UnitSpan with the given units and a value equal to the given value after it has been converted from it's old units to the new units.
      UnitSpan​(UnitSpan source)
      Deprecated.
      UnitSpan is immutable, so there is no need to copy an instance.
      UnitSpan​(java.lang.String sText)
      Instantiates a UnitSpan with a value and unit code parsed from the given text.
      UnitSpan​(java.lang.String sText, int eDefaultUnits, boolean bDefaultValuePerUnit)
      Instantiates a UnitSpan with a value and unit code parsed from the given text.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      UnitSpan abs()
      Returns a UnitSpan representing the absolute value of this UnitSpan.
      UnitSpan add​(UnitSpan add)
      Returns a UnitSpan representing the addition of this object and the given UnitSpan.
      UnitSpan changeUnits​(int eUnits)
      Returns a UnitSpan representing the change of units of this object to the given unit code.
      int compareTo​(UnitSpan compare)
      Compares this object to the given UnitSpan.
      static int convertUnit​(int eNewUnits, int eOldUnits, int nValue)  
      static int defaultUnits()
      Gets the default unit code for all UnitSpans.
      UnitSpan divide​(int nDivisor)
      Returns a UnitSpan representing the division of this object's value by the given int value.
      double divide​(UnitSpan divisor)
      Returns a UnitSpan representing the division of this object's value by the given UnitSpan.
      boolean equals​(java.lang.Object object)
      Determines if this object is equal to the given Object.
      UnitSpan grid​(UnitSpan grid)
      Returns a UnitSpan representing this UnitSpan's value snaped to the nearest grid coordinate of the given UnitSpan.
      boolean gt​(UnitSpan compare)
      Determines if this object is greater than the given UnitSpan.
      boolean gte​(UnitSpan compare)
      Determines if this object is greater than or equal to the given.
      int hashCode()  
      boolean lt​(UnitSpan compare)
      Determines if this object is less than the given UnitSpan.
      boolean lte​(UnitSpan compare)
      Determines if this object is less than or equal to the given UnitSpan.
      static boolean match​(UnitSpan u1, UnitSpan u2)
      Compares two UnitSpan(s) for equality, allowing for null arguments.
      static java.lang.String measurementValidate​(java.lang.String sText, boolean negValid)  
      UnitSpan multiply​(double dScale)
      Returns a UnitSpan representing the multiplication of this object's value by the given double value.
      UnitSpan multiply​(int nScale)
      Returns a UnitSpan representing the multiplication of this object's value by the given int value.
      UnitSpan round​(UnitSpan round)
      Returns a UnitSpan representing the rounding of this object's value to the given UnitSpan.
      static int stringToUnit​(java.lang.String sUnit, int eDefaultUnits)
      Converts the given unit string to a unit code.
      UnitSpan subtract​(UnitSpan subtract)
      Returns a UnitSpan representing the subtraction of this object's value from the given UnitSpan.
      java.lang.String text​(int nPrecision, boolean bTruncate, boolean bValuePerUnits)
      Returns a String containing this object's value converted followed by its units, formatted according to the given arguments.
      java.lang.String toString()
      Returns a String containing this object's value followed by its units.
      int units()
      Gets this object's units.
      int unitsPerInch()
      Gets the units per inch for this object's unit code.
      static int unitsPerInch​(int eUnit)
      Gets the units per inch for the given unit code.
      static java.lang.String unitToString​(int eUnit)
      Converts the given unit code to a string.
      static int unitToValue​(double dValue, int eUnit)
      Converts a unit measure to a unit value; e.g.
      static UnitSpan.ParseData validatingParse​(java.lang.String sText, int eDefaultUnits, boolean bAllowNegative, boolean bForceValuePerUnit, boolean bAllowPercent)
      Parses a value with strict validation.
      int value()
      Gets this object's value.
      int valueAsUnit​(int eUnits)
      Gets this object's value converted to the given unit code.
      static double valueToUnit​(int nValue, int eUnit)
      Converts the given value to the given unit code.
      static UnitSpan zero()
      The zero unit span.

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • INCHES_1M

        public static final int INCHES_1M
        Unit code for 1,000,000 units per inch.
        See Also:
        Constant Field Values

      • CM_250K

        public static final int CM_250K
        Unit code for 250,000 units per cm.
        See Also:
        Constant Field Values

      • INCHES_72K

        public static final int INCHES_72K
        Unit code for 72,000 units per inch.
        See Also:
        Constant Field Values

      • MM_25K

        public static final int MM_25K
        Unit code for 25,000 units per mm.
        See Also:
        Constant Field Values

      • POINTS_1K

        public static final int POINTS_1K
        Unit code for 1,000 units per point (72,000 units per inch).
        See Also:
        Constant Field Values

      • PICA_PT_1K

        public static final int PICA_PT_1K
        Deprecated.
        Unit deprecated in favour of POINTS_1K.
        Unit code for 1,000 units per point (72,000 units per inch).
        See Also:
        Constant Field Values

      • MILLIPOINT

        public static final int MILLIPOINT
        Unit code for 1,000 units per point (72,000 units per inch).
        See Also:
        Constant Field Values

      • PICA_PT_10K

        public static final int PICA_PT_10K
        Deprecated.
        Unit deprecated. The unit is not accurate and does not actually handle picas.
        Unit code for 10,000 units per point.
        See Also:
        Constant Field Values

      • PICAS_12K

        public static final int PICAS_12K
        Unit code for 12,000 units per pica (72,000 units per inch).
        See Also:
        Constant Field Values

      • UNIT_UNKNOWN

        public static final int UNIT_UNKNOWN
        Unit code for units unknown.
        See Also:
        Constant Field Values

      • ZERO

        public static final UnitSpan ZERO

    • Constructor Detail

      • UnitSpan

        public UnitSpan()
        Instantiates a UnitSpan with the value 0 and default units INCHES_72K.
        See Also:
        zero()

      • UnitSpan

        public UnitSpan​(double dValue,
                int eUnits)
        Instantiates a UnitSpan with the given double value and units.
        Parameters:
        dValue - the value of the unit span.
        eUnits - the unit code of the unit span.

      • UnitSpan

        public UnitSpan​(int nValue)
        Instantiates a UnitSpan with the given int value and unknown units. The unit code will be UNIT_UNKNOWN.
        Parameters:
        nValue - the value of the unit span.

      • UnitSpan

        public UnitSpan​(int eUnits,
                int nValue)
        Instantiates a UnitSpan with the given units and optional value.
        Parameters:
        eUnits - the unit code of the unit span.
        nValue - the value of the unit span.

      • UnitSpan

        public UnitSpan​(int eNewUnits,
                int eOldUnits,
                int nOldValue)
        Instantiates a UnitSpan with the given units and a value equal to the given value after it has been converted from it's old units to the new units.
        Parameters:
        eNewUnits - the unit code of the unit span to which the value will be converted.
        eOldUnits - the unit code from which the value will be converted.
        nOldValue - the value to be converted and set as this object's value.

      • UnitSpan

        public UnitSpan​(java.lang.String sText)
        Instantiates a UnitSpan with a value and unit code parsed from the given text.
        Parameters:
        sText - text containing a numeric value possibly followed by a unit string of "in", "inches", "cm", "centimeters", "pt", "points", "picas", "mm", "millimeters", "mp", or "millipoints". If no unit is specified, this object's unit will default to UNIT_UNKNOWN.

      • UnitSpan

        public UnitSpan​(java.lang.String sText,
                int eDefaultUnits,
                boolean bDefaultValuePerUnit)
        Instantiates a UnitSpan with a value and unit code parsed from the given text.
        Parameters:
        sText - text containing a numeric value possibly followed by a unit string of "in", "inches", "cm", "centimeters", "pt", "points", "picas", "mm", "millimeters", "mp" or "millipoints".
        eDefaultUnits - unit to use if the string contains no unit specification.
        bDefaultValuePerUnit - a default interpretation of the value if no unit string is found.

      • UnitSpan

        public UnitSpan​(UnitSpan source)
        Deprecated.
        UnitSpan is immutable, so there is no need to copy an instance.
        Instantiates a UnitSpan from the given UnitSpan.
        Parameters:
        source - the UnitSpan to copy to this object.

    • Method Detail

      • changeUnits

        public UnitSpan changeUnits​(int eUnits)
        Returns a UnitSpan representing the change of units of this object to the given unit code.
        Parameters:
        eUnits - the new unit code.
        Returns:
        the unit span of the changed units

      • convertUnit

        public static int convertUnit​(int eNewUnits,
                              int eOldUnits,
                              int nValue)

      • defaultUnits

        public static int defaultUnits()
        Gets the default unit code for all UnitSpans.
        Returns:
        the default unit code, which is INCHES_72K.

      • measurementValidate

        public static java.lang.String measurementValidate​(java.lang.String sText,
                                                   boolean negValid)

      • stringToUnit

        public static int stringToUnit​(java.lang.String sUnit,
                               int eDefaultUnits)
        Converts the given unit string to a unit code. If the string is not recognized as a unit string, a default may be specified.
        Parameters:
        sUnit - the string to be converted.
        eDefaultUnits - the default unit code.
        Returns:
        the converted unit code.

      • unitsPerInch

        public static int unitsPerInch​(int eUnit)
        Gets the units per inch for the given unit code.
        Returns:
        the units per inch for the unit code.

      • unitToString

        public static java.lang.String unitToString​(int eUnit)
        Converts the given unit code to a string.
        Parameters:
        eUnit - the unit code to be converted.
        Returns:
        the string version of the unit code.

      • unitToValue

        public static int unitToValue​(double dValue,
                              int eUnit)
        Converts a unit measure to a unit value; e.g. 3in ⇒ 3,000,000.

      • valueToUnit

        public static double valueToUnit​(int nValue,
                                 int eUnit)
        Converts the given value to the given unit code.
        Parameters:
        nValue - the unit value to be converted.
        eUnit - the unit code to be converted to.
        Returns:
        the converted value.

      • zero

        public static UnitSpan zero()
        The zero unit span.
        Returns:
        the unit span equal to zero.

      • abs

        public UnitSpan abs()
        Returns a UnitSpan representing the absolute value of this UnitSpan.
        Returns:
        a unit span of the absolute value.

      • add

        public UnitSpan add​(UnitSpan add)
        Returns a UnitSpan representing the addition of this object and the given UnitSpan. The given UnitSpan's value is converted to this object's units for the operation.
        Parameters:
        add - the UnitSpan to add.
        Returns:
        a unit span of the addition.

      • divide

        public UnitSpan divide​(int nDivisor)
        Returns a UnitSpan representing the division of this object's value by the given int value. The resulting value is rounded to 0 decimal places.
        Parameters:
        nDivisor - the divisor.
        Returns:
        a unit span of the division.

      • divide

        public double divide​(UnitSpan divisor)
        Returns a UnitSpan representing the division of this object's value by the given UnitSpan. The given UnitSpan's value is converted to this object's units for the operation.
        Parameters:
        divisor - the divisor.
        Returns:
        a unit span of the division.

      • equals

        public boolean equals​(java.lang.Object object)
        Determines if this object is equal to the given Object. Comparisons with instances of non-UnitSpan objects are never equal.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        object - the Object to compare.
        Returns:
        true if equal, false otherwise.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • grid

        public UnitSpan grid​(UnitSpan grid)
        Returns a UnitSpan representing this UnitSpan's value snaped to the nearest grid coordinate of the given UnitSpan. The given UnitSpan's value is converted to this object's units for the calculation.

        Positive grid values will "move" this object's value to the left (or down), and negative grid values will "move" this object's value to the right (or up).

        The algorithm used to "snap" this object's value is (<y/x> ∗ x) where y is this value, x is the grid size, and <> is the floor function; this is best explained with examples: 

         grid = 5, pt = 7 and (<7/5> * 5) = 1 * 5 = 5 (moved to left)
 grid = 5, pt = -7 and (<-7/5> * * 5) = -2 * 5 = -10 (moved to left)
 
 grid = -5, pt = 7 and (<7/-5> * -5) = -2 * -5 = 10 (moved to right)
 grid = -5, pt = * -7 and (<-7/-5> * -5) = 1 * -5 = -5 (moved to right)
        Parameters:
        grid - the grid coordinate
        Returns:
        a unit span aligned to the grid.

      • gt

        public boolean gt​(UnitSpan compare)
        Determines if this object is greater than the given UnitSpan. The given UnitSpan's value is converted to this object's units for the comparison.
        Parameters:
        compare - the UnitSpan to compare.
        Returns:
        true if greater than, false otherwise.

      • gte

        public boolean gte​(UnitSpan compare)
        Determines if this object is greater than or equal to the given. UnitSpan. The given UnitSpan's value is converted to this object's units for the comparison.
        Parameters:
        compare - the UnitSpan to compare.
        Returns:
        true if greater than or equal to, false otherwise.

      • lt

        public boolean lt​(UnitSpan compare)
        Determines if this object is less than the given UnitSpan. The given UnitSpan's value is converted to this object's units for the comparison.
        Parameters:
        compare - the UnitSpan to compare.
        Returns:
        true if less than, false otherwise.

      • lte

        public boolean lte​(UnitSpan compare)
        Determines if this object is less than or equal to the given UnitSpan. The given UnitSpan's value is converted to this object's units for the comparison.
        Parameters:
        compare - the UnitSpan to compare.
        Returns:
        true if less than or equal to, false otherwise.

      • multiply

        public UnitSpan multiply​(double dScale)
        Returns a UnitSpan representing the multiplication of this object's value by the given double value. The resulting value is rounded to 0 decimal places.
        Parameters:
        dScale - the multiplier.
        Returns:
        a unit span of the multiplication.

      • multiply

        public UnitSpan multiply​(int nScale)
        Returns a UnitSpan representing the multiplication of this object's value by the given int value.
        Parameters:
        nScale - the multiplier.
        Returns:
        a unit span of the multiplication.

      • round

        public UnitSpan round​(UnitSpan round)
        Returns a UnitSpan representing the rounding of this object's value to the given UnitSpan. Positive and negative round values have the same effect.

        This value is rounded by adding one to the quotient (subtracting one for negative quotients) of [y / |x|] if the remainder of [y / |x|] is >= [x/2] or <= [-x/2] where y is this object's value, and x is the round value. Again this is best explained with examples: 

         rnd = 5, pt = 7, quo = 1, rem = 2, rem / rnd < 0.5 and pt = quo * rnd = 5
 rnd = 5, pt = 8, quo = 1, rem = 3, rem / rnd > 0.5 and pt = (quo + 1) * rnd = 10
 rnd = 5, pt = -7, quo = -1, rem = 2, rem / rnd < 0.5 and pt = quo * rnd = -5
 rnd = 5, pt = -8, quo = -1, rem = 2, rem / rnd > 0.5 and pt = (quo - 1) * rnd = -10
        Parameters:
        round - the rounding coordinate.
        Returns:
        a unit span of the rounding.

      • subtract

        public UnitSpan subtract​(UnitSpan subtract)
        Returns a UnitSpan representing the subtraction of this object's value from the given UnitSpan. The given UnitSpan's value is converted to this object's units for the operation.
        Parameters:
        subtract - the UnitSpan to subtract.
        Returns:
        a unit span of the subtraction.

      • text

        public java.lang.String text​(int nPrecision,
                             boolean bTruncate,
                             boolean bValuePerUnits)
        Returns a String containing this object's value converted followed by its units, formatted according to the given arguments.
        Parameters:
        nPrecision - the number of decimal places to which the value will be calculated.
        bTruncate - If false, the decimal portion will be padded out with 0's up to the number specified by nPrecision. If true, '0' placeholders will be suppressed.
        bValuePerUnits - indicates the number should be expressed in quantity per unit, i.e., lines per inch.
        Returns:
        The output string, which will be the value converted to units followed by the (abbreviated) unit.

      • toString

        public java.lang.String toString()
        Returns a String containing this object's value followed by its units.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string of this UnitSpan's value followed by its (abbreviated) unit.

      • units

        public int units()
        Gets this object's units.
        Returns:
        the unit as an int.

      • unitsPerInch

        public int unitsPerInch()
        Gets the units per inch for this object's unit code.
        Returns:
        the units per inch for this unit.

      • validatingParse

        public static UnitSpan.ParseData validatingParse​(java.lang.String sText,
                                                 int eDefaultUnits,
                                                 boolean bAllowNegative,
                                                 boolean bForceValuePerUnit,
                                                 boolean bAllowPercent)
        Parses a value with strict validation.

        Given a string representing a value with optional unit specification, this method parses the string content and returns results.

        The caller can invoke this method to parse specifically for supported UnitSpan types, or it can call it as a more general-purpose value and unit parser for caller-recognized types. It can also use a single call for both purposes.

        The method returns flag indicating whether the parse succeeded or failed. The parse will fail if the string is not in the general format of a value with optional units. If the string does fit the format, but the unit type is not recognized, the call succeeds, and the structure indicates that the caller may choose to validate the units. Alternatively, the caller may treat this situation as an error if it is expecting only UnitSpan units.

        Values in the structure are populated as described below. These values are relevant only if the parse succeeds. If the string contains recognized UnitSpan units, only two fields in the structure are relevant:

        • mnValue: The ultimate value for a resulting UnitSpan object. This will already have been scaled to match the unit type.
        • meUnits: The unit code to use for a resulting UnitSpan object.

          • If the units are not recognized or are expressed as a percentage (and the parse otherwise succeeds), the caller may need to look at all fields in the structure.

          • mnValue: The whole number part of the value (i.e., the part before the decimal point).
          • mnFraction: The fractional part of the number (i.e., the part after the decimal point), expressed as an integer value. For example, .1234 would result in a value of 1,234 here.
          • mnFractionScale: The amount to divide the fraction part by to convert it back to its true fractional amount. For example, a fractional part of .1234 would yield a value of 10,000 in this field.
          • meUnits: UNIT_UNKNOWN to indicate that the parse didn't recognize the unit type as a valid UnitSpan type.
          • mcUnit0, mcUnit1, mcUnit2: First three characters of the unit text.
          • mbValuePerUnit: True if the string expressed the measurement as a value per unit (e.g., 6/in). False otherwise.
          • mbPercent: True if the string expressed the measurement as a percentage, instead of including unit text. False otherwise.
        Parameters:
        sText - Text to parse.
        eDefaultUnits - (optional) Default units to use if the string does not contain a unit specification. The default is UNIT_UNKNOWN, which cause the result of DefaultUnit() to be used.
        bAllowNegative - (optional) True if negative values are allowed. If false, a negative value will be considered an error. The default is false.
        bForceValuePerUnit - (optional) True if the result is to be treated as value per unit even if the slash character is not present. The default is false.
        bAllowPercent - (optional) True if the percent character is to be allowed as a unit type. The default is false.
        Returns:
        Result of the parse if it succeeded; null if it failed. Please see above for an explanation of the fields. If the unit text is not recognized as a valid UnitSpan unit type but the parse otherwise succeeds, true will be returned and the value of meUnits in the structure will be UNIT_UNKNOWN.

      • value

        public int value()
        Gets this object's value.
        Returns:
        the value.

      • valueAsUnit

        public int valueAsUnit​(int eUnits)
        Gets this object's value converted to the given unit code.
        Parameters:
        eUnits - the unit code.
        Returns:
        the converted value.

      • match

        public static boolean match​(UnitSpan u1,
                            UnitSpan u2)
        Compares two UnitSpan(s) for equality, allowing for null arguments.
        Parameters:
        u1 - the first UnitSpan to compare.
        u2 - the second UnitSpan to compare.
        Returns:
        true if equal, false othewise. Note that two null arguments will be considered equal, but comparing a null argument to a non-null one will not be considered equal.

      • compareTo

        public int compareTo​(UnitSpan compare)
        Compares this object to the given UnitSpan. The given UnitSpan's value is converted to this object's units for the comparison.
        Specified by:
        compareTo in interface java.lang.Comparable<UnitSpan>
        Parameters:
        compare - the UnitSpan to compare.
        Returns:
        the value 0 if equal; a value less than zero if this object is less that the given argument; and a value greater than zero if this object is greater that the given argument.