Class UnitSpan
- java.lang.Object
-
- com.adobe.xfa.ut.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.
-
Field Summary
Fields Modifier and Type Field Description static int
CM_250K
Unit code for 250,000 units per cm.static int
INCHES_1M
Unit code for 1,000,000 units per inch.static int
INCHES_72K
Unit code for 72,000 units per inch.static int
MILLIPOINT
Unit code for 1,000 units per point (72,000 units per inch).static int
MM_25K
Unit code for 25,000 units per mm.static int
PICA_PT_10K
Deprecated.Unit deprecated.static int
PICA_PT_1K
Deprecated.Unit deprecated in favour ofPOINTS_1K
.static int
PICAS_12K
Unit code for 12,000 units per pica (72,000 units per inch).static int
POINTS_1K
Unit code for 1,000 units per point (72,000 units per inch).static int
UNIT_MASK
static int
UNIT_UNKNOWN
Unit code for units unknown.static int
UNITS_CM_250K
static int
UNITS_INCHES_1M
static int
UNITS_INCHES_72K
static int
UNITS_MILLIPOINT
static int
UNITS_MM_25K
static int
UNITS_PICAS_12K
static int
UNITS_POINTS_1K
static UnitSpan
ZERO
-
Constructor Summary
Constructors Constructor Description UnitSpan()
Instantiates aUnitSpan
with the value 0 and default unitsINCHES_72K
.UnitSpan(double dValue, int eUnits)
Instantiates aUnitSpan
with the given double value and units.UnitSpan(int nValue)
Instantiates aUnitSpan
with the given int value and unknown units.UnitSpan(int eUnits, int nValue)
Instantiates aUnitSpan
with the given units and optional value.UnitSpan(int eNewUnits, int eOldUnits, int nOldValue)
Instantiates aUnitSpan
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 aUnitSpan
with a value and unit code parsed from the given text.UnitSpan(java.lang.String sText, int eDefaultUnits, boolean bDefaultValuePerUnit)
Instantiates aUnitSpan
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 aUnitSpan
representing the absolute value of thisUnitSpan
.UnitSpan
add(UnitSpan add)
Returns aUnitSpan
representing the addition of this object and the givenUnitSpan
.UnitSpan
changeUnits(int eUnits)
Returns aUnitSpan
representing the change of units of this object to the given unit code.int
compareTo(UnitSpan compare)
Compares this object to the givenUnitSpan
.static int
convertUnit(int eNewUnits, int eOldUnits, int nValue)
static int
defaultUnits()
Gets the default unit code for allUnitSpans
.UnitSpan
divide(int nDivisor)
Returns aUnitSpan
representing the division of this object's value by the given int value.double
divide(UnitSpan divisor)
Returns aUnitSpan
representing the division of this object's value by the givenUnitSpan
.boolean
equals(java.lang.Object object)
Determines if this object is equal to the givenObject
.UnitSpan
grid(UnitSpan grid)
Returns aUnitSpan
representing thisUnitSpan
's value snaped to the nearest grid coordinate of the givenUnitSpan
.boolean
gt(UnitSpan compare)
Determines if this object is greater than the givenUnitSpan
.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 givenUnitSpan
.boolean
lte(UnitSpan compare)
Determines if this object is less than or equal to the givenUnitSpan
.static boolean
match(UnitSpan u1, UnitSpan u2)
Compares twoUnitSpan
(s) for equality, allowing for null arguments.static java.lang.String
measurementValidate(java.lang.String sText, boolean negValid)
UnitSpan
multiply(double dScale)
Returns aUnitSpan
representing the multiplication of this object's value by the given double value.UnitSpan
multiply(int nScale)
Returns aUnitSpan
representing the multiplication of this object's value by the given int value.UnitSpan
round(UnitSpan round)
Returns aUnitSpan
representing the rounding of this object's value to the givenUnitSpan
.static int
stringToUnit(java.lang.String sUnit, int eDefaultUnits)
Converts the given unit string to a unit code.UnitSpan
subtract(UnitSpan subtract)
Returns aUnitSpan
representing the subtraction of this object's value from the givenUnitSpan
.java.lang.String
text(int nPrecision, boolean bTruncate, boolean bValuePerUnits)
Returns aString
containing this object's value converted followed by its units, formatted according to the given arguments.java.lang.String
toString()
Returns aString
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.
-
-
-
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 ofPOINTS_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_MASK
public static final int UNIT_MASK
- See Also:
- Constant Field Values
-
UNIT_UNKNOWN
public static final int UNIT_UNKNOWN
Unit code for units unknown.- See Also:
- Constant Field Values
-
UNITS_CM_250K
public static final int UNITS_CM_250K
- See Also:
- Constant Field Values
-
UNITS_INCHES_1M
public static final int UNITS_INCHES_1M
- See Also:
- Constant Field Values
-
UNITS_INCHES_72K
public static final int UNITS_INCHES_72K
- See Also:
- Constant Field Values
-
UNITS_MILLIPOINT
public static final int UNITS_MILLIPOINT
- See Also:
- Constant Field Values
-
UNITS_MM_25K
public static final int UNITS_MM_25K
- See Also:
- Constant Field Values
-
UNITS_POINTS_1K
public static final int UNITS_POINTS_1K
- See Also:
- Constant Field Values
-
UNITS_PICAS_12K
public static final int UNITS_PICAS_12K
- See Also:
- Constant Field Values
-
ZERO
public static final UnitSpan ZERO
-
-
Constructor Detail
-
UnitSpan
public UnitSpan()
Instantiates aUnitSpan
with the value 0 and default unitsINCHES_72K
.- See Also:
zero()
-
UnitSpan
public UnitSpan(double dValue, int eUnits)
Instantiates aUnitSpan
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 aUnitSpan
with the given int value and unknown units. The unit code will beUNIT_UNKNOWN
.- Parameters:
nValue
- the value of the unit span.
-
UnitSpan
public UnitSpan(int eUnits, int nValue)
Instantiates aUnitSpan
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 aUnitSpan
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 aUnitSpan
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 toUNIT_UNKNOWN
.
-
UnitSpan
public UnitSpan(java.lang.String sText, int eDefaultUnits, boolean bDefaultValuePerUnit)
Instantiates aUnitSpan
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 aUnitSpan
from the givenUnitSpan
.- Parameters:
source
- theUnitSpan
to copy to this object.
-
-
Method Detail
-
changeUnits
public UnitSpan changeUnits(int eUnits)
Returns aUnitSpan
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 allUnitSpans
.- 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 aUnitSpan
representing the absolute value of thisUnitSpan
.- Returns:
- a unit span of the absolute value.
-
add
public UnitSpan add(UnitSpan add)
Returns aUnitSpan
representing the addition of this object and the givenUnitSpan
. The givenUnitSpan
's value is converted to this object's units for the operation.- Parameters:
add
- theUnitSpan
to add.- Returns:
- a unit span of the addition.
-
divide
public UnitSpan divide(int nDivisor)
Returns aUnitSpan
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 aUnitSpan
representing the division of this object's value by the givenUnitSpan
. The givenUnitSpan
'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 givenObject
. Comparisons with instances of non-UnitSpan
objects are never equal.- Overrides:
equals
in classjava.lang.Object
- Parameters:
object
- theObject
to compare.- Returns:
- true if equal, false otherwise.
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
grid
public UnitSpan grid(UnitSpan grid)
Returns aUnitSpan
representing thisUnitSpan
's value snaped to the nearest grid coordinate of the givenUnitSpan
. The givenUnitSpan
'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 givenUnitSpan
. The givenUnitSpan
's value is converted to this object's units for the comparison.- Parameters:
compare
- theUnitSpan
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 givenUnitSpan
's value is converted to this object's units for the comparison.- Parameters:
compare
- theUnitSpan
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 givenUnitSpan
. The givenUnitSpan
's value is converted to this object's units for the comparison.- Parameters:
compare
- theUnitSpan
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 givenUnitSpan
. The givenUnitSpan
's value is converted to this object's units for the comparison.- Parameters:
compare
- theUnitSpan
to compare.- Returns:
- true if less than or equal to, false otherwise.
-
multiply
public UnitSpan multiply(double dScale)
Returns aUnitSpan
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 aUnitSpan
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 aUnitSpan
representing the rounding of this object's value to the givenUnitSpan
. 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 aUnitSpan
representing the subtraction of this object's value from the givenUnitSpan
. The givenUnitSpan
's value is converted to this object's units for the operation.- Parameters:
subtract
- theUnitSpan
to subtract.- Returns:
- a unit span of the subtraction.
-
text
public java.lang.String text(int nPrecision, boolean bTruncate, boolean bValuePerUnits)
Returns aString
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 bynPrecision
. 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 aString
containing this object's value followed by its units.- Overrides:
toString
in classjava.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.
- 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.
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.
- 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 twoUnitSpan
(s) for equality, allowing for null arguments.- Parameters:
u1
- the firstUnitSpan
to compare.u2
- the secondUnitSpan
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 givenUnitSpan
. The givenUnitSpan
's value is converted to this object's units for the comparison.- Specified by:
compareTo
in interfacejava.lang.Comparable<UnitSpan>
- Parameters:
compare
- theUnitSpan
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.
-
-