org.apache.sis.measure

Class AngleFormat

Object

Format

AngleFormat

All Implemented Interfaces:

Serializable, Cloneable, Localized

public class AngleFormat
extends Format
implements Localized

Parses and formats angles according a specified pattern. The pattern is a string containing any characters, with a special meaning for the following characters:

Reserved characters

Symbol	Meaning
D	The integer part of degrees
d	The fractional part of degrees
M	The integer part of minutes
m	The fractional part of minutes
S	The integer part of seconds
s	The fractional part of seconds
#	Fraction digits shown only if non-zero
.	The decimal separator
?	Omit the preceding field if zero

Upper-case letters D, M and S stand for the integer parts of degrees, minutes and seconds respectively. If present, they shall appear in that order.

Example: "M′D" is illegal because "M" and "S" are in reverse order. "D°S" is also illegal because "M" is missing between "D" and "S".

Lower-case letters d, m and s stand for fractional parts of degrees, minutes and seconds respectively. Only one of those can appear in a pattern. If present, they must be in the last field.

Example: "D.dd°MM′" is illegal because "d" is followed by "M". "D.mm" is also illegal because "m" is not the fractional part of "D".

The number of occurrences of D, M, S and their lower-case counterpart is the number of digits to format.

Example: "DD.ddd" will format angles with two digits for the integer part and three digits for the fractional part (e.g. 4.4578 will be formatted as "04.458").

Separator characters like °, ′ and ″ are inserted "as-is" in the formatted string, except the decimal separator dot (.) which is replaced by the local-dependent decimal separator. Separator characters may be completely omitted; Angle­Format will still differentiate degrees, minutes and seconds fields according the pattern.

Example: "0480439" with the "DDDMMmm" pattern will be parsed as 48°04.39′.

The ? modifier specifies that the preceding field can be omitted if its value is zero. Any field can be omitted for Angle object, but only trailing fields are omitted for Longitude and Latitude.

Example: "DD°MM′?SS″?" will format an angle of 12.01° as 12°36″, but a longitude of 12.01°N as 12°00′36″N (not 12°36″N).

The above special case exists because some kind of angles are expected to be very small (e.g. rotation angles in Bursa-Wolf parameters are given in arc-seconds), while longitude and latitude values are usually distributed over their full ±180° or ±90° range. Since longitude or latitude values without the degrees field are unusual, omitting that field is likely to increase the risk of confusion in those cases.

Examples:

Pattern examples

Pattern	48.5	-12.53125
DD°MM′SS.#″	48°30′00″	-12°31′52.5″
DD°MM′	48°30′	-12°32′
DD.ddd	48.500	-12.531
DD.###	48.5	-12.531
DDMM	4830	-1232
DDMMSSs	4830000	-1231525
DD°MM′?SS.s″?	48°30′	-12°31′52.5″

Since:

0.3

See Also:

Angle, Latitude, Longitude, Coordinate­Format, Serialized Form

Defined in the sis-utility module

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AngleFormat.Field Constants that are used as attribute keys in the iterator returned from format­To­Character­Iterator(Object).

Constructor Summary

Constructors

Constructor and Description
AngleFormat() Constructs a new Angle­Format for the default pattern and the current default locale.
AngleFormat(Locale locale) Constructs a new Angle­Format for the default pattern and the specified locale.
AngleFormat(String pattern) Constructs a new Angle­Format for the specified pattern and the current default locale.
AngleFormat(String pattern, Locale locale) Constructs a new Angle­Format using the specified pattern and locale.

Method Summary

Modifier and Type	Method and Description
void	applyPattern(String pattern) Sets the pattern to use for parsing and formatting angles.
AngleFormat	clone() Returns a clone of this Angle­Format.
boolean	equals(Object object) Compares this format with the specified object for equality.
String	format(double angle) Formats an angle.
StringBuffer	format(double angle, StringBuffer toAppendTo, FieldPosition pos) Formats an angle in the given buffer.
StringBuffer	format(Object value, StringBuffer toAppendTo, FieldPosition pos) Formats an angle, latitude or longitude value in the given buffer.
AttributedCharacterIterator	formatToCharacterIterator(Object value) Formats an angle, latitude or longitude value as an attributed character iterator.
static AngleFormat	getInstance() Constructs a new Angle­Format for the default pattern and the current default locale.
static AngleFormat	getInstance(Locale locale) Constructs a new Angle­Format for the default pattern and the specified locale.
Locale	getLocale() Returns this formatter locale.
int	getMaximumFractionDigits() Returns the maximum number of digits allowed in the fraction portion of the last field.
int	getMinimumFractionDigits() Returns the minimum number of digits allowed in the fraction portion of the last field.
RoundingMode	getRoundingMode() Returns the rounding mode.
int	hashCode() Returns a "hash value" for this object.
boolean	isFallbackAllowed() Returns true if the parse methods are allowed to fallback on the build-in default symbols if the string to parse doesn't match the applied pattern.
Angle	parse(String source) Parses the given string as an angle.
Angle	parse(String source, ParsePosition pos) Parses the given string as an angle.
Object	parseObject(String source) Parses the given string as an object.
Object	parseObject(String source, ParsePosition pos) Parses a substring as an object.
void	setFallbackAllowed(boolean allowed) Sets whether the parse methods are allowed to fallback on the build-in default symbols if the string to parse doesn't match the applied pattern.
void	setMaximumFractionDigits(int count) Sets the maximum number of digits allowed in the fraction portion of the last field.
void	setMaximumWidth(int width) Modifies, if needed, the pattern in order to fit formatted angles in the given maximum total width.
void	setMinimumFractionDigits(int count) Sets the minimum number of digits allowed in the fraction portion of the last field.
void	setRoundingMode(RoundingMode mode) Sets the rounding mode to the specified value.
String	toPattern() Returns the pattern used for parsing and formatting angles.
String	toString() Returns a string representation of this object for debugging purpose.

Methods inherited from class Format

format

Methods inherited from class Object

finalize, get­Class, notify, notify­All, wait, wait, wait

Constructor Detail

AngleFormat

public AngleFormat()

Constructs a new Angle­Format for the default pattern and the current default locale.

AngleFormat

public AngleFormat(Locale locale)

Constructs a new Angle­Format for the default pattern and the specified locale.

Parameters:

locale - the locale to use.

AngleFormat

public AngleFormat(String pattern)
            throws IllegalArgumentException

Constructs a new Angle­Format for the specified pattern and the current default locale.

Parameters:

pattern - the pattern to use for parsing and formatting angles. See class description for an explanation of pattern syntax.

Throws:

Illegal­Argument­Exception - if the specified pattern is illegal.

AngleFormat

public AngleFormat(String pattern,
                   Locale locale)
            throws IllegalArgumentException

Constructs a new Angle­Format using the specified pattern and locale.

Parameters:

pattern - the pattern to use for parsing and formatting angles. See class description for an explanation of pattern syntax.

locale - the locale to use.

Throws:

Illegal­Argument­Exception - if the specified pattern is illegal.

Method Detail

getInstance

public static AngleFormat getInstance()

Constructs a new Angle­Format for the default pattern and the current default locale.

Returns:

an angle format for the current default locale.

getInstance

public static AngleFormat getInstance(Locale locale)

Constructs a new Angle­Format for the default pattern and the specified locale.

Parameters:

locale - the locale to use.

Returns:

an angle format for the given locale.

applyPattern

public void applyPattern(String pattern)
                  throws IllegalArgumentException

Sets the pattern to use for parsing and formatting angles. See class description for a description of pattern syntax.

Parameters:

pattern - the pattern to use for parsing and formatting angle.

Throws:

Illegal­Argument­Exception - if the specified pattern is not legal.

See Also:

set­Minimum­Fraction­Digits(int), set­Maximum­Fraction­Digits(int)

toPattern

public String toPattern()

Returns the pattern used for parsing and formatting angles. See class description for an explanation of how patterns work.

Returns:

the formatting pattern.

See Also:

get­Minimum­Fraction­Digits(), get­Maximum­Fraction­Digits()

getRoundingMode

public RoundingMode getRoundingMode()

Returns the rounding mode. Default value is Rounding­Mode.HALF_EVEN.

Returns:

the rounding mode.

Since:

0.8

See Also:

Number­Format.get­Rounding­Mode()

setRoundingMode

public void setRoundingMode(RoundingMode mode)

Sets the rounding mode to the specified value. The given mode can be one of the following:

Supported rounding modes

Rounding mode	Result
UP	Round away from zero.
DOWN	Round towards zero.
CEILING	Round towards positive infinity.
FLOOR	Round towards negative infinity.
HALF_EVEN	Round towards nearest neighbor.

The Rounding­Mode.HALF_UP and HALF_DOWN values are not supported by the current Angle­Format implementation.

Parameters:

mode - the new rounding mode.

Since:

0.8

See Also:

Number­Format.set­Rounding­Mode(Rounding­Mode)

getMinimumFractionDigits

public int getMinimumFractionDigits()

Returns the minimum number of digits allowed in the fraction portion of the last field. This value can be set by the repetition of 'd', 'm' or 's' symbol in the pattern.

Returns:

the minimum number of digits allowed in the fraction portion.

See Also:

Decimal­Format.get­Minimum­Fraction­Digits()

setMinimumFractionDigits

public void setMinimumFractionDigits(int count)

Sets the minimum number of digits allowed in the fraction portion of the last field. If the given value is greater than the maximum number of fraction digits, then that maximum number will be set to the given value too.

Parameters:

count - the minimum number of digits allowed in the fraction portion.

See Also:

Decimal­Format.set­Minimum­Fraction­Digits(int)

getMaximumFractionDigits

public int getMaximumFractionDigits()

Returns the maximum number of digits allowed in the fraction portion of the last field. This value can be set by the repetition of '#' symbol in the pattern.

Returns:

the maximum number of digits allowed in the fraction portion.

See Also:

Decimal­Format.get­Maximum­Fraction­Digits()

setMaximumFractionDigits

public void setMaximumFractionDigits(int count)

Sets the maximum number of digits allowed in the fraction portion of the last field. If the given value is smaller than the minimum number of fraction digits, then that minimum number will be set to the given value too.

Parameters:

count - the maximum number of digits allowed in the fraction portion.

See Also:

Decimal­Format.set­Maximum­Fraction­Digits(int)

setMaximumWidth

public void setMaximumWidth(int width)

Modifies, if needed, the pattern in order to fit formatted angles in the given maximum total width. This method applies zero, one or more of the following changes, in that order:

1. If needed, reduce the maximum number of fraction digits.
2. If omitting all fraction digits would not be sufficient for fitting a formatted angle in the given width, remove the seconds field (if any) from the pattern.
3. If the above changes are not sufficient, remove the minutes field (if any) from the pattern.
4. If the above changes are not sufficient, set the minimal width of degrees field to 1.

Note that despite the above changes, formatted angles may still be larger than the given width if that width is small, or if the formatted angles are too large in magnitude.

This method does not take into account the space needed for the hemisphere symbol when formatting Latitude or Longitude objects.

Parameters:

width - the maximum total width of formatted angle.

format

public final String format(double angle)

Formats an angle. The angle will be formatted according the pattern given to the last call of apply­Pattern(String).

Parameters:

angle - angle to format, in decimal degrees.

Returns:

the formatted string.

format

public StringBuffer format(double angle,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Formats an angle in the given buffer. The angle will be formatted according the pattern given to the last call of apply­Pattern(String).

Parameters:

angle - angle to format, in decimal degrees.

to­Append­To - the buffer where to append the formatted angle.

pos - an optional object where to store the position of the field in the formatted text, or null if this information is not wanted. This field position shall be created with one of the Angle­Format.Field constants.

Returns:

the to­Append­To buffer, returned for method calls chaining.

format

public StringBuffer format(Object value,
                           StringBuffer toAppendTo,
                           FieldPosition pos)
                    throws IllegalArgumentException

Formats an angle, latitude or longitude value in the given buffer. The angular values will be formatted according the pattern given to the last call of apply­Pattern(String), with some variations that depend on the value class:

• If value is a Latitude instance, then the value is formatted as a positive angle followed by the "N" (positive value) or "S" (negative value) symbol.
• If value is a Longitude instance, then the value is formatted as a positive angle followed by the "E" (positive value) or "W" (negative value) symbol.
• If value is any Angle other than a Latitude or Longitude, then it is formatted as by the format(double, String­Buffer, Field­Position) method.

Specified by:

format in class Format

Parameters:

value - Angle object to format.

to­Append­To - the buffer where to append the formatted angle.

pos - an optional object where to store the position of the field in the formatted text, or null if this information is not wanted. This field position shall be created with one of the Angle­Format.Field constants.

Returns:

the to­Append­To buffer, returned for method calls chaining.

Throws:

Illegal­Argument­Exception - if value if not an instance of Angle.

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object value)

Formats an angle, latitude or longitude value as an attributed character iterator. Callers can iterate and queries the attribute values as in the following example:

AttributedCharacterIterator it = angleFormat.formatToCharacterIterator(myAngle);
for (char c=it.first(); c!=AttributedCharacterIterator.DONE; c=c.next()) {
    // 'c' is a character from the formatted string.
    if (it.getAttribute(AngleFormat.Field.MINUTES) != null) {
        // If we enter this block, then the character 'c' is part of the minutes field,
        // This field extends from it.getRunStart(MINUTES) to it.getRunLimit(MINUTES).
    }
}

Alternatively, if the current iterator index is before the start of the minutes field, then the starting position of that field can be obtained directly by it.get­Run­Limit(MINUTES). If the current iterator index is inside the minutes field, then the above method call will rather returns the end of that field. The same strategy works for other all fields too.

The returned character iterator contains all Number­Format.Field attributes in addition to the Angle­Format.Field ones. Consequently the same character may have more than one attribute. For example when formatting 45°30′15.0″N, then:

• The 45° part has the Angle­Format.Field.DEGREES attribute.
• The 30′ part has the Angle­Format.Field.MINUTES attribute.
• The 15.0″ part has the Angle­Format.Field.SECONDS attribute.
• The N part has the Angle­Format.Field.HEMISPHERE attribute.
• The 45, 30 and 15 parts have the Number­Format.Field.INTEGER attribute.
• The . part has the Number­Format.Field.DECIMAL_SEPARATOR attribute.
• The last 0 part has the Number­Format.Field.FRACTION attribute.

In Apache SIS implementation, the returned character iterator also implements the Char­Sequence interface for convenience.

Overrides:

format­To­Character­Iterator in class Format

Parameters:

value - the Angle object to format.

Returns:

a character iterator together with the attributes describing the formatted value.

Throws:

Illegal­Argument­Exception - if value if not an instance of Angle.

parse

public Angle parse(String source,
                   ParsePosition pos)

Parses the given string as an angle. This method can parse the string even if it is not strictly compliant to the expected pattern. For example if is­Fallback­Allowed() is true, then this method will parse "48°12.34'" correctly even if the expected pattern was "DDMM.mm" (i.e. the string should have been "4812.34").

If the given string ends with a "N" or "S" hemisphere symbol, then this method returns an instance of Latitude. Otherwise if the string ends with a "E" or "W" symbol, then this method returns an instance of Longitude. Otherwise this method returns an instance of Angle.

This method is stricter than the parse(String) method regarding whitespaces between the degrees, minutes and seconds fields. This is because whitespaces could be used as a separator for other kinds of values. If the string is known to contain only an angle value, use parse(String) instead.

Parameters:

source - the string to parse.

pos - on input, index of the first source character to read. On output, index after the last parsed character.

Returns:

the parsed string as an Angle, Latitude or Longitude object.

See Also:

is­Fallback­Allowed()

parse

public Angle parse(String source)
            throws ParseException

Parses the given string as an angle. This full string is expected to represents an angle value. This assumption allows parse(String) to be more tolerant than parse(String, Parse­Position) regarding white spaces between degrees, minutes and seconds fields.

Parameters:

source - the string to parse.

Returns:

the parsed string as an Angle, Latitude or Longitude object.

Throws:

Parse­Exception - if the string can not be fully parsed.

See Also:

is­Fallback­Allowed()

parseObject

public Object parseObject(String source,
                          ParsePosition pos)

Parses a substring as an object. The default implementation delegates to parse(String, Parse­Position).

Specified by:

parse­Object in class Format

Parameters:

source - the string to parse.

pos - the position where to start parsing.

Returns:

the parsed string as an Angle, Latitude or Longitude object.

parseObject

public Object parseObject(String source)
                   throws ParseException

Parses the given string as an object. The default implementation delegates to parse(String).

Overrides:

parse­Object in class Format

Parameters:

source - the string to parse.

Returns:

the parsed string as an Angle, Latitude or Longitude object.

Throws:

Parse­Exception - if the string can not been fully parsed.

isFallbackAllowed

public boolean isFallbackAllowed()

Returns true if the parse methods are allowed to fallback on the build-in default symbols if the string to parse doesn't match the applied pattern.

Returns:

true if the ASCII quote characters are allowed at parsing time.

setFallbackAllowed

public void setFallbackAllowed(boolean allowed)

Sets whether the parse methods are allowed to fallback on the build-in default symbols if the string to parse doesn't match the applied pattern. The build-in fallback is:

• ° (an extended-ASCII character) or space (in parse(String) method only) for degrees.
• ' (an ASCII character) or ′ (the default Unicode character) for minutes.
• " (an ASCII character) or ″ (the default Unicode character) for seconds.

The default value is true, because many end-users will not enter the Unicode ′ and ″ symbols. However developers may need to set this flag to false if those ASCII symbols are used in a wider context (for example the " character for quoting strings).

Parameters:

allowed - true if the ASCII quote characters are allowed at parsing time.

getLocale

public Locale getLocale()

Returns this formatter locale. This is the locale specified at construction time if any, or the default locale at construction time otherwise.

Specified by:

get­Locale in interface Localized

Returns:

this formatter locale (never null).

clone

public AngleFormat clone()

Returns a clone of this Angle­Format.

Overrides:

clone in class Format

Returns:

a clone of this format.

hashCode

public int hashCode()

Returns a "hash value" for this object.

Overrides:

hash­Code in class Object

equals

public boolean equals(Object object)

Compares this format with the specified object for equality.

Overrides:

equals in class Object

Parameters:

object - the object to compare with this angle format for equality.

toString

@Debug
public String toString()

Returns a string representation of this object for debugging purpose.

Overrides:

to­String in class Object