Class AngleFormat

java.lang.Object
java.text.Format
org.apache.sis.measure.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
SymbolMeaning
DThe integer part of degrees
dThe fractional part of degrees
MThe integer part of minutes
mThe fractional part of minutes
SThe integer part of seconds
sThe 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; AngleFormat 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
Version:
1.1
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    Constants that are used as attribute keys in the iterator returned from formatToCharacterIterator(Object).
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    A temporary variable which may be set to the character iterator for which the attributes need to be set.
    (package private) static final int
    Constant for degrees field.
    private byte
    Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits.
    private String
    Characters to insert before the text to format, and after each field.
    Object to give to DecimalFormat.format methods, cached in order to avoid recreating this object too often.
    private static final char
    Hemisphere symbols.
    private static final int
    Constant for the fractional part of the degrees, minutes or seconds field.
    private byte
    Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits.
    (package private) static final int
    Constant for hemisphere field.
    private boolean
    true if the parse(String, ParsePosition) method is allowed to fallback on the build-in default symbols if the string to parse doesn't match the pattern.
    private final Locale
    The locale specified at construction time (never null).
    private byte
    Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits.
    private byte
    Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits.
    (package private) static final int
    Constant for minutes field.
    private byte
    Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits.
    private String
    Characters to insert before the text to format, and after each field.
    private static final char
    Hemisphere symbols.
    private NumberFormat
    Format to use for writing numbers (degrees, minutes or seconds) when formatting an angle.
    private static final int
    Index for the SYMBOLS character which stands for optional field.
    private byte
    A bitmask of optional fields.
    private String
    Characters to insert before the text to format, and after each field.
    private static final int
    A constant for the symbol to appears before the degrees fields.
    private RoundingMode
    The rounding mode, or null for the default mode (which is RoundingMode.HALF_EVEN).
    (package private) static final int
    Constant for seconds field.
    private byte
    Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits.
    private String
    Characters to insert before the text to format, and after each field.
    private static final long
    Serial number for inter-operability with different versions.
    private boolean
    If true, optionalFields never apply to fields to leading fields.
    private static final char
    Hemisphere symbols.
    private static final int[]
    Symbols for degrees (0), minutes (1), seconds (2) and optional fraction digits (3).
    private boolean
    Specifies whatever the decimal separator shall be inserted between the integer part and the fraction part of the last field.
    private static final char
    Hemisphere symbols.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a new AngleFormat for the default pattern and the current default locale.
    Constructs a new AngleFormat for the specified pattern and the current default locale.
    AngleFormat(String pattern, Locale locale)
    Constructs a new AngleFormat using the specified pattern and locale.
    Constructs a new AngleFormat for the default pattern and the specified locale.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Sets the pattern to use for parsing and formatting angles.
    private void
    applyPattern(String pattern, int[] symbols, int decimalSeparator)
    Actual implementation of applyPattern(String), as a private method for use by the constructor.
    Returns a clone of this AngleFormat.
    Returns the dummy field position.
    boolean
    equals(Object object)
    Compares this format with the specified object for equality.
    private static int
    fieldForSymbol(int[] symbols, int c)
    Returns the field index for the given upper case character, or -1 if none.
    final String
    format(double angle)
    Formats an angle.
    format(double angle, StringBuffer toAppendTo, FieldPosition pos)
    Formats an angle in the given buffer.
    private StringBuffer
    format(double angle, StringBuffer toAppendTo, FieldPosition pos, char positiveSuffix, char negativeSuffix)
    Formats a latitude or longitude value in the given buffer.
    format(Object value, StringBuffer toAppendTo, FieldPosition pos)
    Formats an angle, latitude or longitude value in the given buffer.
    Formats an angle, latitude or longitude value as an attributed character iterator.
    private static int
    Returns the *_FIELD constant for the given field position, or -1 if none.
    Constructs a new AngleFormat for the default pattern and the current default locale.
    Constructs a new AngleFormat for the default pattern and the specified locale.
    Returns this formatter locale.
    int
    Returns the maximum number of digits allowed in the fraction portion of the last field.
    int
    Returns the minimum number of digits allowed in the fraction portion of the last field.
    double
    Returns the precision of angles formatted by current pattern, in decimal degrees.
    Returns the rounding mode.
    int
    Returns a "hash value" for this object.
    Returns an exception for an illegal pattern.
    boolean
    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.
    private NumberFormat
    Returns the number format, created when first needed.
    parse(String source)
    Parses the given string as an angle.
    parse(String source, ParsePosition pos)
    Parses the given string as an angle.
    private Angle
    parse(String source, ParsePosition pos, boolean spaceAsSeparator)
    Parses the given string as an angle.
    Parses the given string as an object.
    Parses a substring as an object.
    private double
    round(double sign, double value)
    Rounds the given value according current roundingMode.
    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
    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
    Sets the minimum number of digits allowed in the fraction portion of the last field.
    void
    setPrecision(double resolution, boolean allowFieldChanges)
    Adjusts the number of fraction digits, and optionally the visible fields, for the given precision.
    void
    Sets the rounding mode to the specified value.
    private static int
    skipSpaces(String source, int index, int length)
    Returns the index of the first non-space character in the given string.
    private int
    skipSuffix(String source, ParsePosition pos, int expectedField)
    Ignores a field suffix, then returns the identifier of the suffix just skipped.
    private static byte
    toByte(int n)
    Returns the given value as a byte.
    Returns the pattern used for parsing and formatting angles.
    private String
    toPattern(int[] symbols, int decimalSeparator)
    Actual implementation of toPattern() and toLocalizedPattern() (the latter method may be provided in a future SIS version).
    Returns a string representation of this object for debugging purpose.

    Methods inherited from class java.text.Format

    format

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for inter-operability with different versions.
      See Also:
    • NORTH

      private static final char NORTH
      Hemisphere symbols. Must be upper-case.
      See Also:
    • SOUTH

      private static final char SOUTH
      Hemisphere symbols. Must be upper-case.
      See Also:
    • EAST

      private static final char EAST
      Hemisphere symbols. Must be upper-case.
      See Also:
    • WEST

      private static final char WEST
      Hemisphere symbols. Must be upper-case.
      See Also:
    • PREFIX_FIELD

      private static final int PREFIX_FIELD
      A constant for the symbol to appears before the degrees fields. used in switch statements. Fields PREFIX, DEGREES, MINUTES and SECONDS must have increasing values.
      See Also:
    • DEGREES_FIELD

      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:
    • MINUTES_FIELD

      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:
    • SECONDS_FIELD

      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:
    • FRACTION_FIELD

      private static final int FRACTION_FIELD
      Constant for the fractional part of the degrees, minutes or seconds field. When formatting a string, this value may be specified to the FieldPosition constructor in order to get the bounding index where fraction digits have been written.
      See Also:
    • HEMISPHERE_FIELD

      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 symbol has been written.
      See Also:
    • OPTIONAL_FIELD

      private static final int OPTIONAL_FIELD
      Index for the SYMBOLS character which stands for optional field.
      See Also:
    • SYMBOLS

      private static final int[] SYMBOLS
      Symbols for degrees (0), minutes (1), seconds (2) and optional fraction digits (3). The index of each symbol shall be equal to the corresponding *_FIELD constant.
    • locale

      private final Locale locale
      The locale specified at construction time (never null).
    • degreesFieldWidth

      private byte degreesFieldWidth
      Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits. A value of 0 means that the field is not formatted. fractionFieldWidth applies to the last non-zero field. maximumTotalWidth is 0 (the default) if there is no restriction.
    • minutesFieldWidth

      private byte minutesFieldWidth
      Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits. A value of 0 means that the field is not formatted. fractionFieldWidth applies to the last non-zero field. maximumTotalWidth is 0 (the default) if there is no restriction.
    • secondsFieldWidth

      private byte secondsFieldWidth
      Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits. A value of 0 means that the field is not formatted. fractionFieldWidth applies to the last non-zero field. maximumTotalWidth is 0 (the default) if there is no restriction.
    • fractionFieldWidth

      private byte fractionFieldWidth
      Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits. A value of 0 means that the field is not formatted. fractionFieldWidth applies to the last non-zero field. maximumTotalWidth is 0 (the default) if there is no restriction.
    • minimumFractionDigits

      private byte minimumFractionDigits
      Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits. A value of 0 means that the field is not formatted. fractionFieldWidth applies to the last non-zero field. maximumTotalWidth is 0 (the default) if there is no restriction.
    • maximumTotalWidth

      private byte maximumTotalWidth
      Minimal amount of spaces to be used by the degrees, minutes and seconds fields, and by the decimal digits. A value of 0 means that the field is not formatted. fractionFieldWidth applies to the last non-zero field. maximumTotalWidth is 0 (the default) if there is no restriction.
    • optionalFields

      private byte optionalFields
      A bitmask of optional fields. Optional fields are formatted only if their value is different than zero. The bit position is given by a *_FIELD constant, and the actual bitmask is computed by 1 << *_FIELD. A value of zero means that no field is optional.
    • prefix

      private String prefix
      Characters to insert before the text to format, and after each field. A null value means that there is nothing to insert.
    • degreesSuffix

      private String degreesSuffix
      Characters to insert before the text to format, and after each field. A null value means that there is nothing to insert.
    • minutesSuffix

      private String minutesSuffix
      Characters to insert before the text to format, and after each field. A null value means that there is nothing to insert.
    • secondsSuffix

      private String secondsSuffix
      Characters to insert before the text to format, and after each field. A null value means that there is nothing to insert.
    • roundingMode

      private RoundingMode roundingMode
      The rounding mode, or null for the default mode (which is RoundingMode.HALF_EVEN).
      See Also:
    • isFallbackAllowed

      private boolean isFallbackAllowed
      true if the parse(String, ParsePosition) method is allowed to fallback on the build-in default symbols if the string to parse doesn't match the pattern.

      This field cannot be set by the pattern string, so it needs to be initialized separately.

      See Also:
    • useDecimalSeparator

      private boolean useDecimalSeparator
      Specifies whatever the decimal separator shall be inserted between the integer part and the fraction part of the last field. A false value formats the integer and fractional part without separation, e.g. "34867" for 34.867.
    • showLeadingFields

      private transient boolean showLeadingFields
      If true, optionalFields never apply to fields to leading fields. If the minutes field is declared optional but the degrees and seconds are formatted, then minutes will be formatted too un order to reduce the risk of confusion
      Example: Value 12.01 is formatted as 12°00′36″ if this field is true, and as 12°36″ if this field is false.
    • numberFormat

      private transient NumberFormat numberFormat
      Format to use for writing numbers (degrees, minutes or seconds) when formatting an angle. The pattern given to this DecimalFormat shall NOT accept exponential notation, because "E" of "Exponent" would be confused with "E" of "East".
    • dummyFieldPosition

      private transient FieldPosition dummyFieldPosition
      Object to give to DecimalFormat.format methods, cached in order to avoid recreating this object too often.
      See Also:
    • characterIterator

      private transient FormattedCharacterIterator characterIterator
      A temporary variable which may be set to the character iterator for which the attributes need to be set.
      See Also:
  • Constructor Details

    • AngleFormat

      public AngleFormat()
      Constructs a new AngleFormat for the default pattern and the current default locale.
    • AngleFormat

      public AngleFormat(Locale locale)
      Constructs a new AngleFormat for the default pattern and the specified locale.
      Parameters:
      locale - the locale to use.
    • AngleFormat

      public AngleFormat(String pattern) throws IllegalArgumentException
      Constructs a new AngleFormat 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:
      IllegalArgumentException - if the specified pattern is illegal.
    • AngleFormat

      public AngleFormat(String pattern, Locale locale) throws IllegalArgumentException
      Constructs a new AngleFormat 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:
      IllegalArgumentException - if the specified pattern is illegal.
  • Method Details

    • numberFormat

      private NumberFormat numberFormat()
      Returns the number format, created when first needed.
    • dummyFieldPosition

      private FieldPosition dummyFieldPosition()
      Returns the dummy field position.
    • getInstance

      public static AngleFormat getInstance()
      Constructs a new AngleFormat 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 AngleFormat 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:
      IllegalArgumentException - if the specified pattern is not legal.
      See Also:
    • applyPattern

      private void applyPattern(String pattern, int[] symbols, int decimalSeparator)
      Actual implementation of applyPattern(String), as a private method for use by the constructor. All fields related to the pattern shall be set to 0 or null before this method call.
      Parameters:
      symbols - an array of code points containing the reserved symbols as upper-case letters. This is always the SYMBOLS array, unless we apply localized patterns.
      decimalSeparator - the code point which represent decimal separator in the pattern.
    • fieldForSymbol

      private static int fieldForSymbol(int[] symbols, int c)
      Returns the field index for the given upper case character, or -1 if none.
      Parameters:
      symbols - an array of code points containing the reserved symbols as upper-case letters.
      c - the symbol to search, as an upper-case character (code point actually).
      Returns:
      the index of the given character, or -1 if not found.
    • illegalPattern

      private static IllegalArgumentException illegalPattern(String pattern)
      Returns an exception for an illegal pattern.
    • 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:
    • toPattern

      private String toPattern(int[] symbols, int decimalSeparator)
      Actual implementation of toPattern() and toLocalizedPattern() (the latter method may be provided in a future SIS version).
      Parameters:
      symbols - an array of code points containing the reserved symbols as upper-case letters. this is always the SYMBOLS array, unless we apply localized patterns.
      decimalSeparator - the code point which represent decimal separator in the pattern.
    • toByte

      private static byte toByte(int n)
      Returns the given value as a byte. Values greater than the maximal supported value are clamped.
    • getRoundingMode

      public RoundingMode getRoundingMode()
      Returns the rounding mode. Default value is RoundingMode.HALF_EVEN.
      Returns:
      the rounding mode.
      Since:
      0.8
      See Also:
    • 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 RoundingMode.HALF_UP and HALF_DOWN values are not supported by the current AngleFormat implementation.
      Parameters:
      mode - the new rounding mode.
      Since:
      0.8
      See Also:
    • round

      private double round(double sign, double value)
      Rounds the given value according current roundingMode.
      Parameters:
      sign - the sign of the value to round.
      value - the positive value to round.
      Returns:
      the rounded positive value.
    • getPrecision

      public double getPrecision()
      Returns the precision of angles formatted by current pattern, in decimal degrees. For example if the angle pattern is "D°MM′", then this method returns 1/60.
      Returns:
      precision in decimal degrees of angles formatted by current pattern.
      Since:
      1.1
    • setPrecision

      public void setPrecision(double resolution, boolean allowFieldChanges)
      Adjusts the number of fraction digits, and optionally the visible fields, for the given precision. If the allowFieldChanges argument is false, then this method adjusts only the minimum and maximum fraction digits in order to show angles with at least the specified precision. But if the allowFieldChanges argument is true, then this method may change the set of fields (degrees, minutes or seconds) to show before to adjust the number of fraction digits. In that case, this method selects the first row in the following table where the precision matches the condition:
      Selected fields for given precision
      Precision Fields
      ≥ 1°
      ≥ ⅒° D.d°
      ≥ 1′ D°MM′
      ≥ ⅒′ D°MM.m′
      ≥ 1″ D°MM′SS″
      ≥ ⅒″ D°MM′SS.s″
      other D°MM′SS.ss…″
      Parameters:
      resolution - the desired angle resolution, in decimal degrees.
      allowFieldChanges - whether this method is allowed to change the set of fields (degrees, minutes or seconds).
      Throws:
      IllegalArgumentException - if the given resolution is NaN or infinite.
      Since:
      1.0
    • 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:
    • 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:
    • 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:
    • 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:
    • 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.
    • getField

      private static int getField(FieldPosition position)
      Returns the *_FIELD constant for the given field position, or -1 if none.
    • format

      public final String format(double angle)
      Formats an angle. The angle will be formatted according the pattern given to the last call of applyPattern(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 applyPattern(String).
      Parameters:
      angle - angle to format, in decimal degrees.
      toAppendTo - 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 AngleFormat.Field constants.
      Returns:
      the toAppendTo 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 applyPattern(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, StringBuffer, FieldPosition) method.
      Specified by:
      format in class Format
      Parameters:
      value - Angle object to format.
      toAppendTo - 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 AngleFormat.Field constants.
      Returns:
      the toAppendTo buffer, returned for method calls chaining.
      Throws:
      IllegalArgumentException - if value if not an instance of Angle.
    • format

      private StringBuffer format(double angle, StringBuffer toAppendTo, FieldPosition pos, char positiveSuffix, char negativeSuffix)
      Formats a latitude or longitude value in the given buffer. The magnitude of the angular value will be formatted according the pattern given to the last call of applyPattern(String), and one of the given suffix will be appended according the angle sign.
    • 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: 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.getRunLimit(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 NumberFormat.Field attributes in addition to the AngleFormat.Field ones. Consequently, the same character may have more than one attribute. For example, when formatting 45°30′15.0″N, then:

      In Apache SIS implementation, the returned character iterator also implements the CharSequence interface for convenience.
      Overrides:
      formatToCharacterIterator in class Format
      Parameters:
      value - the Angle object to format.
      Returns:
      a character iterator together with the attributes describing the formatted value.
      Throws:
      IllegalArgumentException - if value if not an instance of Angle.
    • skipSuffix

      private int skipSuffix(String source, ParsePosition pos, int expectedField)
      Ignores a field suffix, then returns the identifier of the suffix just skipped. This method is invoked by parse(String, ParsePosition) for determining what was the field it just parsed. For example if we just parsed "48°12'", then this method will skip the "°" part and returns DEGREES_FIELD.

      This method skips whitespaces before the suffix, then compares the characters with the suffix specified to applyPattern(String). If the suffix has not been recognized, then this method will compares against the standard ', ° and " ASCII symbols.

      Parameters:
      source - the string being parsed.
      pos - on input, index of the first source character to read. On output, index after the last suffix character.
      expectedField - first field to verify. For example, a value of MINUTES_FIELD means that the suffix for minute and seconds shall be verified before degrees.
      Returns:
      the *_FIELD constant for the suffix which has been found, or a value outside those constants if no suffix matched.
    • skipSpaces

      private static int skipSpaces(String source, int index, int length)
      Returns the index of the first non-space character in the given string. This method performs the same work than CharSequences.skipLeadingWhitespaces, except that it tests for spaces using the Character.isSpaceChar(int) method instead of Character.isWhitespace(int). The reason is that we really want to skip no-break spaces, since they are often used inside a single entity (e.g. the group separator in numbers formatted using the French locale). Furthermore, we do not want to skip tabulations or line feeds, since they are unlikely to be part of the angle to parse.
      Parameters:
      source - the string being parsed.
      index - index of the first source character to read.
      length - the length of source.
      Returns:
      index of the first non-space character, or the end of string if none.
    • 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 isFallbackAllowed() 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:
    • parse

      private Angle parse(String source, ParsePosition pos, boolean spaceAsSeparator)
      Parses the given string as an angle. The spaceAsSeparator additional argument specifies if spaces can be accepted as a field separator. For example if true, then "45 30" will be parsed as "45°30".
    • 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, ParsePosition) 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:
      ParseException - if the string cannot be fully parsed.
      See Also:
    • parseObject

      public Object parseObject(String source, ParsePosition pos)
      Parses a substring as an object. The default implementation delegates to parse(String, ParsePosition).
      Specified by:
      parseObject 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:
      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 cannot be 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:
      getLocale in interface Localized
      Returns:
      this formatter locale (never null).
    • clone

      public AngleFormat clone()
      Returns a clone of this AngleFormat.
      Overrides:
      clone in class Format
      Returns:
      a clone of this format.
    • hashCode

      public int hashCode()
      Returns a "hash value" for this object.
      Overrides:
      hashCode 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

      public String toString()
      Returns a string representation of this object for debugging purpose.
      Overrides:
      toString in class Object