public abstract class Size2DSyntax extends Object implements Serializable, Cloneable
A twodimensional size attribute's value consists of two items, the X
dimension and the Y dimension. A twodimensional size attribute may be
constructed by supplying the two values and indicating the units in which the
values are measured. Methods are provided to return a twodimensional size
attribute's values, indicating the units in which the values are to be
returned. The two most common size units are inches (in) and millimeters
(mm), and exported constants INCH
and MM
are provided for indicating those units.
Once constructed, a twodimensional size attribute's value is immutable.
Design
A twodimensional size attribute's X and Y dimension values are stored internally as integers in units of micrometers (µm), where 1 micrometer = 10^{6} meter = 1/1000 millimeter = 1/25400 inch. This permits dimensions to be represented exactly to a precision of 1/1000 mm (= 1 µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in negative powers of two, this permits dimensions to be represented exactly to a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch does not equal an integral number of µm).
Storing the dimensions internally in common units of µm lets two size attributes be compared without regard to the units in which they were created; for example, 8.5 in will compare equal to 215.9 mm, as they both are stored as 215900 µm. For example, a lookup service can match resolution attributes based on equality of their serialized representations regardless of the units in which they were created. Using integers for internal storage allows precise equality comparisons to be done, which would not be guaranteed if an internal floating point representation were used. Note that if you're looking for U.S. letter sized media in metric units, you have to search for a media size of 215.9 x 279.4 mm; rounding off to an integral 216 x 279 mm will not match.
The exported constant INCH
is actually the
conversion factor by which to multiply a value in inches to get the value in
µm. Likewise, the exported constant MM
is the
conversion factor by which to multiply a value in mm to get the value in
µm. A client can specify a resolution value in units other than inches
or mm by supplying its own conversion factor. However, since the internal
units of µm was chosen with supporting only the external units of inch
and mm in mind, there is no guarantee that the conversion factor for the
client's units will be an exact integer. If the conversion factor isn't an
exact integer, resolution values in the client's units won't be stored
precisely.
Modifier and Type  Field and Description 

static int 
INCH
Value to indicate units of inches (in).

static int 
MM
Value to indicate units of millimeters (mm).

Modifier  Constructor and Description 

protected 
Size2DSyntax(float x,
float y,
int units)
Construct a new twodimensional size attribute from the given
floatingpoint values.

protected 
Size2DSyntax(int x,
int y,
int units)
Construct a new twodimensional size attribute from the given integer
values.

Modifier and Type  Method and Description 

boolean 
equals(Object object)
Returns whether this twodimensional size attribute is equivalent to the
passed in object.

float[] 
getSize(int units)
Get this twodimensional size attribute's dimensions in the given units
as floatingpoint values.

float 
getX(int units)
Returns this twodimensional size attribute's X dimension in the given
units as a floatingpoint value.

protected int 
getXMicrometers()
Returns this twodimensional size attribute's X dimension in units of
micrometers (µm).

float 
getY(int units)
Returns this twodimensional size attribute's Y dimension in the given
units as a floatingpoint value.

protected int 
getYMicrometers()
Returns this twodimensional size attribute's Y dimension in units of
micrometers (µm).

int 
hashCode()
Returns a hash code value for this twodimensional size attribute.

String 
toString()
Returns a string version of this twodimensional size attribute.

String 
toString(int units,
String unitsName)
Returns a string version of this twodimensional size attribute in the
given units.

public static final int INCH
public static final int MM
protected Size2DSyntax(float x, float y, int units)
x
 X dimension.y
 Y dimension.units
 Unit conversion factor, e.g. INCH
or
MM
.IllegalArgumentException
 (Unchecked exception) Thrown if x < 0
or y < 0
or
units < 1
.protected Size2DSyntax(int x, int y, int units)
x
 X dimension.y
 Y dimension.units
 Unit conversion factor, e.g. INCH
or
MM
.IllegalArgumentException
 (Unchecked exception) Thrown if x < 0
or y < 0
or units < 1
.public float[] getSize(int units)
units
 Unit conversion factor, e.g. INCH
or MM
.IllegalArgumentException
 (unchecked exception) Thrown if units < 1
.public float getX(int units)
units
 Unit conversion factor, e.g. INCH
or MM
.IllegalArgumentException
 (unchecked exception) Thrown if units < 1
.public float getY(int units)
units
 Unit conversion factor, e.g. INCH
or MM
.IllegalArgumentException
 (unchecked exception) Thrown if units < 1
.public String toString(int units, String unitsName)
"XxY
U"
, where X is the X dimension, Y is the Y
dimension, and U is the units name. The values are displayed in
floating point.units
 Unit conversion factor, e.g. INCH
or MM
.unitsName
 Units name string, e.g. in
or mm
. If
null, no units name is appended to the result.IllegalArgumentException
 (unchecked exception) Thrown if units < 1
.public boolean equals(Object object)
object
is not null.
object
is an instance of class Size2DSyntax.
object
's X
dimension.
object
's Y
dimension.
equals
in class Object
object
 Object to compare to.object
is equivalent to this
twodimensional size attribute, false otherwise.Object.hashCode()
,
HashMap
public int hashCode()
hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public String toString()
"XxY um"
, where
X is the X dimension and Y is the Y dimension.
The values are reported in the internal units of micrometers.protected int getXMicrometers()
protected int getYMicrometers()
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developertargeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2023, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.