* A two-dimensional size attribute's value consists of two items, the X * dimension and the Y dimension. A two-dimensional 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 two-dimensional 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 {@link #INCH INCH} and {@link #MM * MM} are provided for indicating those units. *
* Once constructed, a two-dimensional size attribute's value is immutable. *
* Design *
* A two-dimensional 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 {@link #INCH INCH} is actually the
* conversion factor by which to multiply a value in inches to get the value in
* µm. Likewise, the exported constant {@link #MM 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.
*
* @author Alan Kaminsky
*/
public abstract class Size2DSyntax implements Serializable, Cloneable {
private static final long serialVersionUID = 5584439964938660530L;
/**
* X dimension in units of micrometers (µm).
* @serial
*/
private int x;
/**
* Y dimension in units of micrometers (µm).
* @serial
*/
private int y;
/**
* Value to indicate units of inches (in). It is actually the conversion
* factor by which to multiply inches to yield µm (25400).
*/
public static final int INCH = 25400;
/**
* Value to indicate units of millimeters (mm). It is actually the
* conversion factor by which to multiply mm to yield µm (1000).
*/
public static final int MM = 1000;
/**
* Construct a new two-dimensional size attribute from the given
* floating-point values.
*
* @param x X dimension.
* @param y Y dimension.
* @param units
* Unit conversion factor, e.g. {@link #INCH INCH} or
* {@link #MM MM}.
*
* @exception IllegalArgumentException
* (Unchecked exception) Thrown if {@code x < 0} or {@code y < 0} or
* {@code units < 1}.
*/
protected Size2DSyntax(float x, float y, int units) {
if (x < 0.0f) {
throw new IllegalArgumentException("x < 0");
}
if (y < 0.0f) {
throw new IllegalArgumentException("y < 0");
}
if (units < 1) {
throw new IllegalArgumentException("units < 1");
}
this.x = (int) (x * units + 0.5f);
this.y = (int) (y * units + 0.5f);
}
/**
* Construct a new two-dimensional size attribute from the given integer
* values.
*
* @param x X dimension.
* @param y Y dimension.
* @param units
* Unit conversion factor, e.g. {@link #INCH INCH} or
* {@link #MM MM}.
*
* @exception IllegalArgumentException
* (Unchecked exception) Thrown if {@code x < 0} or {@code y < 0}
* or {@code units < 1}.
*/
protected Size2DSyntax(int x, int y, int units) {
if (x < 0) {
throw new IllegalArgumentException("x < 0");
}
if (y < 0) {
throw new IllegalArgumentException("y < 0");
}
if (units < 1) {
throw new IllegalArgumentException("units < 1");
}
this.x = x * units;
this.y = y * units;
}
/**
* Convert a value from micrometers to some other units. The result is
* returned as a floating-point number.
*
* @param x
* Value (micrometers) to convert.
* @param units
* Unit conversion factor, e.g. {@link #INCH INCH} or
* {@link #MM MM}.
*
* @return The value of x converted to the desired units.
*
* @exception IllegalArgumentException
* (unchecked exception) Thrown if units < 1.
*/
private static float convertFromMicrometers(int x, int units) {
if (units < 1) {
throw new IllegalArgumentException("units is < 1");
}
return ((float)x) / ((float)units);
}
/**
* Get this two-dimensional size attribute's dimensions in the given units
* as floating-point values.
*
* @param units
* Unit conversion factor, e.g. {@link #INCH INCH} or {@link #MM MM}.
*
* @return A two-element array with the X dimension at index 0 and the Y
* dimension at index 1.
*
* @exception IllegalArgumentException
* (unchecked exception) Thrown if {@code units < 1}.
*/
public float[] getSize(int units) {
return new float[] {getX(units), getY(units)};
}
/**
* Returns this two-dimensional size attribute's X dimension in the given
* units as a floating-point value.
*
* @param units
* Unit conversion factor, e.g. {@link #INCH INCH} or {@link #MM MM}.
*
* @return X dimension.
*
* @exception IllegalArgumentException
* (unchecked exception) Thrown if {@code units < 1}.
*/
public float getX(int units) {
return convertFromMicrometers(x, units);
}
/**
* Returns this two-dimensional size attribute's Y dimension in the given
* units as a floating-point value.
*
* @param units
* Unit conversion factor, e.g. {@link #INCH INCH} or {@link #MM MM}.
*
* @return Y dimension.
*
* @exception IllegalArgumentException
* (unchecked exception) Thrown if {@code units < 1}.
*/
public float getY(int units) {
return convertFromMicrometers(y, units);
}
/**
* Returns a string version of this two-dimensional size attribute in the
* given units. The string takes the form "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.
*
* @param units
* Unit conversion factor, e.g. {@link #INCH INCH} or {@link #MM MM}.
*
* @param unitsName
* Units name string, e.g. {@code in} or {@code mm}. If
* null, no units name is appended to the result.
*
* @return String version of this two-dimensional size attribute.
*
* @exception IllegalArgumentException
* (unchecked exception) Thrown if {@code units < 1}.
*/
public String toString(int units, String unitsName) {
StringBuffer result = new StringBuffer();
result.append(getX (units));
result.append('x');
result.append(getY (units));
if (unitsName != null) {
result.append(' ');
result.append(unitsName);
}
return result.toString();
}
/**
* Returns whether this two-dimensional size attribute is equivalent to the
* passed in object. To be equivalent, all of the following conditions must
* be true:
*
object is not null.
* object is an instance of class Size2DSyntax.
* object's X
* dimension.
* object's Y
* dimension.
* object is equivalent to this
* two-dimensional size attribute, false otherwise.
*/
public boolean equals(Object object) {
return(object != null &&
object instanceof Size2DSyntax &&
this.x == ((Size2DSyntax) object).x &&
this.y == ((Size2DSyntax) object).y);
}
/**
* Returns a hash code value for this two-dimensional size attribute.
*/
public int hashCode() {
return (((x & 0x0000FFFF) ) |
((y & 0x0000FFFF) << 16));
}
/**
* Returns a string version of this two-dimensional size attribute. The
* string takes the form "XxY um", where
* X is the X dimension and Y is the Y dimension.
* The values are reported in the internal units of micrometers.
*/
public String toString() {
StringBuffer result = new StringBuffer();
result.append(x);
result.append('x');
result.append(y);
result.append(" um");
return result.toString();
}
/**
* Returns this two-dimensional size attribute's X dimension in units of
* micrometers (µm). (For use in a subclass.)
*
* @return X dimension (µm).
*/
protected int getXMicrometers(){
return x;
}
/**
* Returns this two-dimensional size attribute's Y dimension in units of
* micrometers (µm). (For use in a subclass.)
*
* @return Y dimension (µm).
*/
protected int getYMicrometers() {
return y;
}
}