de.caff.util.measure

Class PhysicalLength

java.lang.Object

de.caff.util.measure.PhysicalLength

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<PhysicalLength>

public final class PhysicalLength
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<PhysicalLength>

A physical length.

This is an immutable class.

Author:

Rammi

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static PhysicalLength	NULL Null length.
static java.lang.String	UNIT_FORMAT The format for printing units.

Constructor Summary

Constructors

Constructor and Description
PhysicalLength(double value, LengthUnit unit) Create a new physical length.

Method Summary

Modifier and Type	Method and Description
int	compareTo(PhysicalLength o) Compares this object with the specified object for order.
PhysicalLength	dividedBy(double divider) Get a divided part of this physical length.
double	dividedBy(PhysicalLength physicalLength) Get the scaling between two physical lengths.
boolean	equals(java.lang.Object o) Is this length equal to another one?
boolean	equals(PhysicalLength other, PhysicalLength epsilon) Is this length nearly equal to another one?
static PhysicalLength	fromString(java.lang.String descr) Decodes a physical length description in text form,using the default locale.
static PhysicalLength	fromString(java.lang.String descr, java.util.Locale locale) Decodes a physical length description in text form.
static PhysicalLength	ft(double feet) Factory method for lengths in foot.
double	getLength() Get the length.
double	getLength(LengthUnit targetUnit) Get the length in an arbitrary unit.
double	getLengthInMeter() Get the length in meter.
LengthUnit	getUnit() Get the length unit.
int	hashCode() Getr a useful hashcode.
static PhysicalLength	in(double inches) Factory method for lengths in inches.
PhysicalLength	in(LengthUnit targetUnit) Get this length in another unit.
static PhysicalLength	m(double meter) Factory method for lengths in meter.
static void	main(java.lang.String[] args)
PhysicalLength	minus(PhysicalLength another) Get the difference of this physical length and another.
static PhysicalLength	mm(double millimeter) Factory method for lengths in millimeter.
PhysicalLength	plus(PhysicalLength another) Get the sum of this physical length and another.
PhysicalLength	times(double scale) Get a scaled physical length.
java.lang.String	toString() Return a string representation of this length.
java.lang.String	toString(LengthUnit targetUnit) Return a string representation of this length using the given unit.
java.lang.String	toString(LengthUnit targetUnit, java.util.Locale locale) Return a string representation of this length using the given unit.
java.lang.String	toString(java.util.Locale locale) Return a string representation of this length.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UNIT_FORMAT

@NotNull
public static final java.lang.String UNIT_FORMAT

The format for printing units.

See Also:

Constant Field Values

NULL

@NotNull
public static final PhysicalLength NULL

Null length.

Constructor Detail

PhysicalLength

public PhysicalLength(double value,
                      @NotNull
                      LengthUnit unit)

Create a new physical length.

Parameters:

value - length value

unit - length unit

Method Detail

getUnit

public LengthUnit getUnit()

Get the length unit.

Returns:

length unit

getLengthInMeter

public double getLengthInMeter()

Get the length in meter.

Returns:

length im meter

getLength

public double getLength()

Get the length.

Returns:

length in unit

getLength

public double getLength(@NotNull
                        LengthUnit targetUnit)

Get the length in an arbitrary unit.

Parameters:

targetUnit - length unit for return value

Returns:

the length in the given value

toString

public java.lang.String toString()

Return a string representation of this length. This uses the default locale.

Overrides:

toString in class java.lang.Object

Returns:

length in internal unit as string

toString

public java.lang.String toString(@NotNull
                                 LengthUnit targetUnit)

Return a string representation of this length using the given unit.

Parameters:

targetUnit - length unit

Returns:

length in unit as string

toString

public java.lang.String toString(@NotNull
                                 java.util.Locale locale)

Return a string representation of this length.

Parameters:

locale - locale to use for number output

Returns:

length in internal unit as string

toString

public java.lang.String toString(@NotNull
                                 LengthUnit targetUnit,
                                 @NotNull
                                 java.util.Locale locale)

Return a string representation of this length using the given unit.

Parameters:

targetUnit - length unit

locale - locale to use for number output

Returns:

length in unit as string

equals

public boolean equals(@NotNull
                      PhysicalLength other,
                      @NotNull
                      PhysicalLength epsilon)

Is this length nearly equal to another one?

Parameters:

other - length unit to compare to

epsilon - the maximal error allowed

Returns:

true if the lengths are nearly equal, otherwise false

equals

public boolean equals(java.lang.Object o)

Is this length equal to another one?

Overrides:

equals in class java.lang.Object

Parameters:

o - object to compare to

Returns:

true if the lengths are equals, otherwise false

hashCode

public int hashCode()

Getr a useful hashcode.

Overrides:

hashCode in class java.lang.Object

Returns:

hash code

times

@NotNull
public PhysicalLength times(double scale)

Get a scaled physical length.

Parameters:

scale - scaling factor

Returns:

a physical length which is scale times this physical length

dividedBy

@NotNull
public PhysicalLength dividedBy(double divider)

Get a divided part of this physical length. Because a physical length is internally just a double all rules which apply for doubles apply here (like division by zero etc).

Parameters:

divider - divider

Returns:

this physical length divided by divider

dividedBy

public double dividedBy(@NotNull
                        PhysicalLength physicalLength)

Get the scaling between two physical lengths. Because a physical length is internally just a double all rules which apply for doubles apply here (like division by zero etc).

Parameters:

physicalLength - other length

Returns:

scale: this/physicalLength

plus

@NotNull
public PhysicalLength plus(@NotNull
                                    PhysicalLength another)

Get the sum of this physical length and another.

Parameters:

another - another physical length

Returns:

this + another

minus

@NotNull
public PhysicalLength minus(@NotNull
                                     PhysicalLength another)

Get the difference of this physical length and another.

Parameters:

another - another physical length

Returns:

this - another

in

@NotNull
public PhysicalLength in(@NotNull
                                  LengthUnit targetUnit)

Get this length in another unit.

Parameters:

targetUnit - other unit

Returns:

physical length in the given unit

compareTo

public int compareTo(@NotNull
                     PhysicalLength o)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

The implementor must ensure sgn(x.compareTo(y)) == -sgn(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception iff y.compareTo(x) throws an exception.)

The implementor must also ensure that the relation is transitive: (x.compareTo(y)>0 && y.compareTo(z)>0) implies x.compareTo(z)>0.

Finally, the implementor must ensure that x.compareTo(y)==0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for all z.

It is strongly recommended, but not strictly required that (x.compareTo(y)==0) == (x.equals(y)). Generally speaking, any class that implements the Comparable interface and violates this condition should clearly indicate this fact. The recommended language is "Note: this class has a natural ordering that is inconsistent with equals."

In the foregoing description, the notation sgn(expression) designates the mathematical signum function, which is defined to return one of -1, 0, or 1 according to whether the value of expression is negative, zero or positive.

Specified by:

compareTo in interface java.lang.Comparable<PhysicalLength>

Parameters:

o - the object to be compared.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

java.lang.NullPointerException - if the specified object is null

java.lang.ClassCastException - if the specified object's type prevents it from being compared to this object.

fromString

@NotNull
public static PhysicalLength fromString(@NotNull
                                                 java.lang.String descr,
                                                 @Nullable
                                                 java.util.Locale locale)
                                          throws IllegalPhysicalLengthFormatException

Decodes a physical length description in text form. E.g. "12 km", "-7.3in" and similar.

Parameters:

descr - text description containing a physical length

locale - locale to use for number decoding

Returns:

a physical length

Throws:

IllegalPhysicalLengthFormatException - if the string does not contain a valid physical length

java.lang.NullPointerException - if descr is null

fromString

@NotNull
public static PhysicalLength fromString(@NotNull
                                                 java.lang.String descr)
                                          throws IllegalPhysicalLengthFormatException

Decodes a physical length description in text form,using the default locale. E.g. "12 km", "-7.3in" and similar.

Parameters:

descr - text description containing a physical length

Returns:

a physical length

Throws:

IllegalPhysicalLengthFormatException - if the string does not contain a valid physical length

java.lang.NullPointerException - if descr is null

in

@NotNull
public static PhysicalLength in(double inches)

Factory method for lengths in inches.

Parameters:

inches - number of inches

Returns:

length with the given number of inches

ft

@NotNull
public static PhysicalLength ft(double feet)

Factory method for lengths in foot.

Parameters:

feet - number of feet

Returns:

length with the given number of feet

m

@NotNull
public static PhysicalLength m(double meter)

Factory method for lengths in meter.

Parameters:

meter - number of meters

Returns:

length with the given number of meters

mm

@NotNull
public static PhysicalLength mm(double millimeter)

Factory method for lengths in millimeter.

Parameters:

millimeter - number of millimeters

Returns:

length with the given number of millimeters

main

public static void main(java.lang.String[] args)