AngleFormat (Geotools modules 20-SNAPSHOT API)

Object
- Format
- - AngleFormat

All Implemented Interfaces:: Serializable, Cloneable

public class AngleFormat
extends Format

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

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

.   The decimal separator

Upper-case letters D, M and S are for the integer parts of degrees, minutes and seconds respectively. They must appear in this order (e.g. "M'D" is illegal because "M" and "S" are inverted; "D°S" is illegal too because there is no "M" between "D" and "S"). Lower-case letters d, m and s are for fractional parts of degrees, minutes and seconds respectively. Only one of those may appears in a pattern, and it must be the last special symbol (e.g. "D.dd°MM'" is illegal because "d" is followed by "M"; "D.mm" is illegal because "m" is not the fractional part of "D").

The number of occurrence of D, M, S and their lower-case counterpart is the number of digits to format. For example, "DD.ddd" will format angle 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 " and 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; AngleFormat will still differentiate degrees, minutes and seconds fields according the pattern. For example, "0480439" with the pattern "DDDMMmm" will be parsed as 48°04.39'.

The following table gives some examples of legal patterns.

Pattern Example

DD°MM'SS" 48°30'00"

DD°MM' 48°30'

DD.ddd 48.500

DDMM 4830

DDMMSS 483000

Pattern	Example
`DD°MM'SS"`	48°30'00"
`DD°MM'`	48°30'
`DD.ddd`	48.500
`DDMM`	4830
`DDMMSS`	483000

Since:: 2.0
Author:: Martin Desruisseaux (PMO, IRD)
See Also:: Angle, Latitude, Longitude, Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class AngleFormat.RoundingMethod
Set the rounding method to use when the last significant digit in a value is 5.
- Nested classes/interfaces inherited from class Format
  Format.Field

Nested Classes
Modifier and Type	Class and Description
`static class`	`AngleFormat.RoundingMethod` Set the rounding method to use when the last significant digit in a value is 5.

Field Summary

Fields
Modifier and Type	Field and Description
`static AngleFormat.RoundingMethod`	`DEFAULT_ROUNDING_METHOD` The default rounding method (AngleFormat.RoundingMethod.ROUND_HALF_EVEN).
`static int`	`DEGREES_FIELD` Constant for degrees field.
`static int`	`HEMISPHERE_FIELD` Constant for hemisphere field.
`static int`	`MINUTES_FIELD` Constant for minutes field.
`static int`	`SECONDS_FIELD` Constant for seconds field.

Constructor Summary

Constructors
Constructor and Description
`AngleFormat()` Constructs a new `AngleFormat` using the current default locale and a default pattern.
`AngleFormat(String pattern)` Constructs a new `AngleFormat` using the current default locale and the specified pattern.
`AngleFormat(String pattern, DecimalFormatSymbols symbols)` Constructs a new `AngleFormat` using the specified pattern and decimal symbols.
`AngleFormat(String pattern, Locale locale)` Constructs a new `AngleFormat` using the specified pattern and locale.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`applyPattern(String pattern)` Sets the pattern to use for parsing and formatting angle.
`boolean`	`equals(Object obj)` Compares this format with the specified object for equality.
`String`	`format(double angle)` Format an angle.
`StringBuffer`	`format(double angle, StringBuffer toAppendTo, FieldPosition pos)` Formats an angle and appends the resulting text to a given string buffer.
`StringBuffer`	`format(Object obj, StringBuffer toAppendTo, FieldPosition pos)` Formats an angle, a latitude or a longitude and appends the resulting text to a given string buffer.
`static AngleFormat.RoundingMethod`	`getDefaultRoundingMethod()` Get the default rounding method.
`static AngleFormat`	`getInstance(Locale locale)` Constructs a new `AngleFormat` for the specified locale.
`static AngleFormat.RoundingMethod`	`getRoundingMethod()` Get the rounding method being used by this instance.
`int`	`hashCode()` Returns a "hash value" for this object.
`Angle`	`parse(String source)` Parses a string as an angle.
`Angle`	`parse(String source, ParsePosition pos)` Parses a string as an angle.
`Angle`	`parseObject(String source)` Parses a string as an object.
`Angle`	`parseObject(String source, ParsePosition pos)` Parses a substring as an angle.
`static void`	`setDefaultRoundingMethod(AngleFormat.RoundingMethod method)` Set the default rounding method for all instances of this class to use when the last significant digit of a value is 5.
`void`	`setRoundingMethod(AngleFormat.RoundingMethod method)` Set the rounding method for this instance to use when the last significant digit of a value is 5.
`String`	`toPattern()` Returns the pattern used for parsing and formatting angles.
`String`	`toString()` Returns a string representation of this object.

Methods inherited from class Format
clone, format, formatToCharacterIterator

Methods inherited from class Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEGREES_FIELD
```
public static final int DEGREES_FIELD
```
    Constant for degrees field. When formatting a string, this value may be specified to the FieldPosition constructor in order to get the bounding index where degrees have been written.
    
    See Also:
    
    Constant Field Values
  - MINUTES_FIELD
```
public static final int MINUTES_FIELD
```
    Constant for minutes field. When formatting a string, this value may be specified to the FieldPosition constructor in order to get the bounding index where minutes have been written.
    
    See Also:
    
    Constant Field Values
  - SECONDS_FIELD
```
public static final int SECONDS_FIELD
```
    Constant for seconds field. When formatting a string, this value may be specified to the FieldPosition constructor in order to get the bounding index where seconds have been written.
    
    See Also:
    
    Constant Field Values
  - HEMISPHERE_FIELD
```
public static final int HEMISPHERE_FIELD
```
    Constant for hemisphere field. When formatting a string, this value may be specified to the FieldPosition constructor in order to get the bounding index where the hemisphere synbol has been written.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_ROUNDING_METHOD
```
public static final AngleFormat.RoundingMethod DEFAULT_ROUNDING_METHOD
```
    The default rounding method (AngleFormat.RoundingMethod.ROUND_HALF_EVEN).
- Constructor Detail
  - AngleFormat
```
public AngleFormat()
```
    Constructs a new AngleFormat using the current default locale and a default pattern.
  - AngleFormat
```
public AngleFormat(String pattern)
            throws IllegalArgumentException
```
    Constructs a new AngleFormat using the current default locale and the specified pattern.
    
    Parameters:
    
    pattern - Pattern to use for parsing and formatting angle. See class description for an explanation of how this pattern work.
    
    Throws:
    
    IllegalArgumentException - If the specified pattern is not legal.
  - AngleFormat
```
public AngleFormat(String pattern,
                   Locale locale)
            throws IllegalArgumentException
```
    Constructs a new AngleFormat using the specified pattern and locale.
    
    Parameters:
    
    pattern - Pattern to use for parsing and formatting angle. See class description for an explanation of how this pattern work.
    
    locale - Locale to use.
    
    Throws:
    
    IllegalArgumentException - If the specified pattern is not legal.
  - AngleFormat
```
public AngleFormat(String pattern,
                   DecimalFormatSymbols symbols)
```
    Constructs a new AngleFormat using the specified pattern and decimal symbols.
    
    Parameters:
    
    pattern - Pattern to use for parsing and formatting angle. See class description for an explanation of how this pattern work.
    
    symbols - The symbols to use for parsing and formatting numbers.
    
    Throws:
    
    IllegalArgumentException - If the specified pattern is not legal.
- Method Detail
  - getInstance
```
public static AngleFormat getInstance(Locale locale)
```
    Constructs a new AngleFormat for the specified locale.
    
    Parameters:
    
    locale - The locale.
    
    Returns:
    
    An angle format in the given locale.
  - setDefaultRoundingMethod
```
public static void setDefaultRoundingMethod(AngleFormat.RoundingMethod method)
```
    Set the default rounding method for all instances of this class to use when the last significant digit of a value is 5.
    Note: this will not affect the rounding method being used by instances of this class created previously.
    
    Parameters:
    
    method - one of AngleFormat.RoundingMethod constants
    
    See Also:
    
    setRoundingMethod(org.geotools.measure.AngleFormat.RoundingMethod), DEFAULT_ROUNDING_METHOD
  - getDefaultRoundingMethod
```
public static AngleFormat.RoundingMethod getDefaultRoundingMethod()
```
    Get the default rounding method.
    
    Returns:
    
    the default rounding method.
  - setRoundingMethod
```
public void setRoundingMethod(AngleFormat.RoundingMethod method)
```
    Set the rounding method for this instance to use when the last significant digit of a value is 5. If the rounding method has previously been set globally with the static setDefaultRoundingMethod(org.geotools.measure.AngleFormat.RoundingMethod) method, setting a different method here will take precedence for this instance.
    
    Parameters:
    
    method - one of AngleFormat.RoundingMethod constants
    
    See Also:
    
    setDefaultRoundingMethod(org.geotools.measure.AngleFormat.RoundingMethod), DEFAULT_ROUNDING_METHOD
  - getRoundingMethod
```
public static AngleFormat.RoundingMethod getRoundingMethod()
```
    Get the rounding method being used by this instance.
    
    Returns:
    
    the rounding method for this instance
  - applyPattern
```
public void applyPattern(String pattern)
                  throws IllegalArgumentException
```
    Sets the pattern to use for parsing and formatting angle. See class description for an explanation of how patterns work.
    
    Parameters:
    
    pattern - Pattern to use for parsing and formatting angle.
    
    Throws:
    
    IllegalArgumentException - If the specified pattern is not legal.
  - 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.
  - format
```
public final String format(double angle)
```
    Format an angle. The string will be formatted according the pattern set in the last call to applyPattern(java.lang.String).
    
    Parameters:
    
    angle - Angle to format, in degrees.
    
    Returns:
    
    The formatted string.
  - format
```
public StringBuffer format(double angle,
                           StringBuffer toAppendTo,
                           FieldPosition pos)
```
    Formats an angle and appends the resulting text to a given string buffer. The string will be formatted according the pattern set in the last call to applyPattern(java.lang.String).
    
    Parameters:
    
    angle - Angle to format, in degrees.
    
    toAppendTo - Where the text is to be appended.
    
    pos - An optional FieldPosition identifying a field in the formatted text, or null if this information is not wanted. This field position shall be constructed with one of the following constants: DEGREES_FIELD, MINUTES_FIELD, SECONDS_FIELD or HEMISPHERE_FIELD.
    
    Returns:
    
    The string buffer passed in as toAppendTo, with formatted text appended.
  - format
```
public StringBuffer format(Object obj,
                           StringBuffer toAppendTo,
                           FieldPosition pos)
                    throws IllegalArgumentException
```
    Formats an angle, a latitude or a longitude and appends the resulting text to a given string buffer. The string will be formatted according the pattern set in the last call to applyPattern(java.lang.String). The argument obj shall be an Angle object or one of its derived class (Latitude, Longitude). If obj is a Latitude object, then a symbol "N" or "S" will be appended to the end of the string (the symbol will be choosen according the angle's sign). Otherwise, if obj is a Longitude object, then a symbol "E" or "W" will be appended to the end of the string. Otherwise, no hemisphere symbol will be appended.
    
    Strictly speaking, formatting ordinary numbers is not the AngleFormat's job. Nevertheless, this method accept Number objects. This capability is provided only as a convenient way to format altitude numbers together with longitude and latitude angles.
    
    Specified by:
    
    format in class Format
    
    Parameters:
    
    obj - Angle or Number object to format.
    
    toAppendTo - Where the text is to be appended.
    
    pos - An optional FieldPosition identifying a field in the formatted text, or null if this information is not wanted. This field position shall be constructed with one of the following constants: DEGREES_FIELD, MINUTES_FIELD, SECONDS_FIELD or HEMISPHERE_FIELD.
    
    Returns:
    
    The string buffer passed in as toAppendTo, with formatted text appended.
    
    Throws:
    
    IllegalArgumentException - if obj if not an object of class Angle or Number.
  - parse
```
public Angle parse(String source,
                   ParsePosition pos)
```
    Parses a string as an angle. This method can parse an angle even if it doesn't comply exactly to the expected pattern. For example, this method will parse correctly string "48°12.34'" even if the expected pattern was "DDMM.mm" (i.e. the string should have been "4812.34"). Spaces between degrees, minutes and secondes are ignored. If the string ends with an hemisphere symbol "N" or "S", then this method returns an object of class Latitude. Otherwise, if the string ends with an hemisphere symbol "E" or "W", then this method returns an object of class Longitude. Otherwise, this method returns an object of class Angle.
    
    Parameters:
    
    source - A String whose beginning should be parsed.
    
    pos - Position where to start parsing.
    
    Returns:
    
    The parsed string as an Angle, Latitude or Longitude object.
  - parse
```
public Angle parse(String source)
            throws ParseException
```
    Parses a string as an angle.
    
    Parameters:
    
    source - The string to parse.
    
    Returns:
    
    The parsed string as an Angle, Latitude or Longitude object.
    
    Throws:
    
    ParseException - if the string has not been fully parsed.
  - parseObject
```
public Angle parseObject(String source,
                         ParsePosition pos)
```
    Parses a substring as an angle. Default implementation invokes parse(String, ParsePosition).
    
    Specified by:
    
    parseObject in class Format
    
    Parameters:
    
    source - A String whose beginning should be parsed.
    
    pos - Position where to start parsing.
    
    Returns:
    
    The parsed string as an Angle, Latitude or Longitude object.
  - parseObject
```
public Angle parseObject(String source)
                  throws ParseException
```
    Parses a string as an object. Default implementation invokes parse(String).
    
    Overrides:
    
    parseObject in class Format
    
    Parameters:
    
    source - The string to parse.
    
    Returns:
    
    The parsed string as an Angle, Latitude or Longitude object.
    
    Throws:
    
    ParseException - if the string has not been fully parsed.
  - hashCode
```
public int hashCode()
```
    Returns a "hash value" for this object.
    
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object obj)
```
    Compares this format with the specified object for equality.
    
    Overrides:
    
    equals in class Object
  - toString
```
public String toString()
```
    Returns a string representation of this object.
    
    Overrides:
    
    toString in class Object

`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
`.`	The decimal separator

Class AngleFormat

Nested Class Summary

Nested classes/interfaces inherited from class Format

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Format

Methods inherited from class Object

Field Detail

DEGREES_FIELD

MINUTES_FIELD

SECONDS_FIELD

HEMISPHERE_FIELD

DEFAULT_ROUNDING_METHOD

Constructor Detail

AngleFormat

AngleFormat

AngleFormat

AngleFormat

Method Detail

getInstance

setDefaultRoundingMethod

getDefaultRoundingMethod

setRoundingMethod

getRoundingMethod

applyPattern

toPattern

format

format

format

parse

parse

parseObject

parseObject

hashCode

equals

toString