Package com.adobe.xfa.ut

Class UnitSpan

java.lang.Object
com.adobe.xfa.ut.UnitSpan
All Implemented Interfaces:
Comparable<UnitSpan>
public final class UnitSpan extends Object implements 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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    CM_250K
    Unit code for 250,000 units per cm.
    static final int
    INCHES_1M
    Unit code for 1,000,000 units per inch.
    static final int
    INCHES_72K
    Unit code for 72,000 units per inch.
    static final int
    MILLIPOINT
    Unit code for 1,000 units per point (72,000 units per inch).
    static final int
    MM_25K
    Unit code for 25,000 units per mm.
    static final int
    PICA_PT_10K
    Deprecated.
    Unit deprecated.
    static final int
    PICA_PT_1K
    Deprecated.
    Unit deprecated in favour of POINTS_1K.
    static final int
    PICAS_12K
    Unit code for 12,000 units per pica (72,000 units per inch).
    static final int
    POINTS_1K
    Unit code for 1,000 units per point (72,000 units per inch).
    static final int
    UNIT_MASK
     
    static final int
    UNIT_UNKNOWN
    Unit code for units unknown.
    static final int
    UNITS_CM_250K
     
    static final int
    UNITS_INCHES_1M
     
    static final int
    UNITS_INCHES_72K
     
    static final int
    UNITS_MILLIPOINT
     
    static final int
    UNITS_MM_25K
     
    static final int
    UNITS_PICAS_12K
     
    static final int
    UNITS_POINTS_1K
     
    static final UnitSpan
    ZERO
     

  • 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(String sText)
    Instantiates a UnitSpan with a value and unit code parsed from the given text.
    UnitSpan(String sText, int eDefaultUnits, boolean bDefaultValuePerUnit)
    Instantiates a UnitSpan with a value and unit code parsed from the given text.

  • Method Summary

    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(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 String
    measurementValidate(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(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.
    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.
    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 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(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 Details

    • INCHES_1M

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

    • CM_250K

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

    • INCHES_72K

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

    • MM_25K

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

    • POINTS_1K

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

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

    • MILLIPOINT

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

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

    • PICAS_12K

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

    • UNIT_MASK

      public static final int UNIT_MASK
      See Also:

    • UNIT_UNKNOWN

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

    • UNITS_CM_250K

      public static final int UNITS_CM_250K
      See Also:

    • UNITS_INCHES_1M

      public static final int UNITS_INCHES_1M
      See Also:

    • UNITS_INCHES_72K

      public static final int UNITS_INCHES_72K
      See Also:

    • UNITS_MILLIPOINT

      public static final int UNITS_MILLIPOINT
      See Also:

    • UNITS_MM_25K

      public static final int UNITS_MM_25K
      See Also:

    • UNITS_POINTS_1K

      public static final int UNITS_POINTS_1K
      See Also:

    • UNITS_PICAS_12K

      public static final int UNITS_PICAS_12K
      See Also:

    • ZERO

      public static final UnitSpan ZERO

  • Constructor Details

    • UnitSpan

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

    • 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(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(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 Details

    • 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 String measurementValidate(String sText, boolean negValid)

    • stringToUnit

      public static int stringToUnit(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 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(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 Object
      Parameters:
      object - the Object to compare.
      Returns:
      true if equal, false otherwise.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class 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 (invalid input: '<'7/5> * 5) = 1 * 5 = 5 (moved to left)
 grid = 5, pt = -7 and (invalid input: '<'-7/5> * * 5) = -2 * 5 = -10 (moved to left)
 
 grid = -5, pt = 7 and (invalid input: '<'7/-5> * -5) = -2 * -5 = 10 (moved to right)
 grid = -5, pt = * -7 and (invalid input: '<'-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 invalid input: '<' 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 invalid input: '<' 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 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 String toString()
      Returns a String containing this object's value followed by its units.
      Overrides:
      toString in class 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(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 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.