- All Implemented Interfaces:
Serializable,Cloneable,Localized
| 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 |
D, M and S stand for the integer parts of degrees,
minutes and seconds respectively. If present, they shall appear in that order.
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".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.
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".D, M, S and their lower-case counterpart is the number
of digits to format.
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").°, ′ 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.
0480439" with the "DDDMMmm" pattern will be parsed as 48°04.39′.? 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.
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).| 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:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classConstants that are used as attribute keys in the iterator returned fromformatToCharacterIterator(Object). -
Constructor Summary
ConstructorsConstructorDescriptionConstructs a newAngleFormatfor the default pattern and the current default locale.AngleFormat(String pattern) Constructs a newAngleFormatfor the specified pattern and the current default locale.AngleFormat(String pattern, Locale locale) Constructs a newAngleFormatusing the specified pattern and locale.AngleFormat(Locale locale) Constructs a newAngleFormatfor the default pattern and the specified locale. -
Method Summary
Modifier and TypeMethodDescriptionvoidapplyPattern(String pattern) Sets the pattern to use for parsing and formatting angles.clone()Returns a clone of thisAngleFormat.booleanCompares this format with the specified object for equality.final Stringformat(double angle) Formats an angle.format(double angle, StringBuffer toAppendTo, FieldPosition pos) Formats an angle 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.static AngleFormatConstructs a newAngleFormatfor the default pattern and the current default locale.static AngleFormatgetInstance(Locale locale) Constructs a newAngleFormatfor the default pattern and the specified locale.Returns this formatter locale.intReturns the maximum number of digits allowed in the fraction portion of the last field.intReturns the minimum number of digits allowed in the fraction portion of the last field.doubleReturns the precision of angles formatted by current pattern, in decimal degrees.Returns the rounding mode.intReturns a "hash value" for this object.booleanReturnstrueif theparsemethods are allowed to fallback on the build-in default symbols if the string to parse doesn't match the applied pattern.Parses the given string as an angle.parse(String source, ParsePosition pos) Parses the given string as an angle.parseObject(String source) Parses the given string as an object.parseObject(String source, ParsePosition pos) Parses a substring as an object.voidsetFallbackAllowed(boolean allowed) Sets whether theparsemethods are allowed to fallback on the build-in default symbols if the string to parse doesn't match the applied pattern.voidsetMaximumFractionDigits(int count) Sets the maximum number of digits allowed in the fraction portion of the last field.voidsetMaximumWidth(int width) Modifies, if needed, the pattern in order to fit formatted angles in the given maximum total width.voidsetMinimumFractionDigits(int count) Sets the minimum number of digits allowed in the fraction portion of the last field.voidsetPrecision(double resolution, boolean allowFieldChanges) Adjusts the number of fraction digits, and optionally the visible fields, for the given precision.voidSets the rounding mode to the specified value.Returns the pattern used for parsing and formatting angles.Returns a string representation of this object for debugging purpose.
-
Constructor Details
-
AngleFormat
public AngleFormat()Constructs a newAngleFormatfor the default pattern and the current default locale. -
AngleFormat
Constructs a newAngleFormatfor the default pattern and the specified locale.- Parameters:
locale- the locale to use.
-
AngleFormat
Constructs a newAngleFormatfor 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
Constructs a newAngleFormatusing 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
-
getInstance
Constructs a newAngleFormatfor the default pattern and the current default locale.- Returns:
- an angle format for the current default locale.
-
getInstance
Constructs a newAngleFormatfor the default pattern and the specified locale.- Parameters:
locale- the locale to use.- Returns:
- an angle format for the given locale.
-
applyPattern
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:
-
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:
-
getRoundingMode
Returns the rounding mode. Default value isRoundingMode.HALF_EVEN.- Returns:
- the rounding mode.
- Since:
- 0.8
- See Also:
-
setRoundingMode
Sets the rounding mode to the specified value. The given mode can be one of the following:
TheSupported rounding modes Rounding mode Result UPRound away from zero. DOWNRound towards zero. CEILINGRound towards positive infinity. FLOORRound towards negative infinity. HALF_EVENRound towards nearest neighbor. RoundingMode.HALF_UPandHALF_DOWNvalues are not supported by the currentAngleFormatimplementation.- Parameters:
mode- the new rounding mode.- Since:
- 0.8
- See Also:
-
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 theallowFieldChangesargument isfalse, then this method adjusts only the minimum and maximum fraction digits in order to show angles with at least the specified precision. But if theallowFieldChangesargument istrue, 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.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:- If needed, reduce the maximum number of fraction digits.
- 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.
- If the above changes are not sufficient, remove the minutes field (if any) from the pattern.
- If the above changes are not sufficient, set the minimal width of degrees field to 1.
This method does not take into account the space needed for the hemisphere symbol when formatting
LatitudeorLongitudeobjects.- Parameters:
width- the maximum total width of formatted angle.
-
format
Formats an angle. The angle will be formatted according the pattern given to the last call ofapplyPattern(String).- Parameters:
angle- angle to format, in decimal degrees.- Returns:
- the formatted string.
-
format
Formats an angle in the given buffer. The angle will be formatted according the pattern given to the last call ofapplyPattern(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, ornullif this information is not wanted. This field position shall be created with one of theAngleFormat.Fieldconstants.- Returns:
- the
toAppendTobuffer, 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 ofapplyPattern(String), with some variations that depend on thevalueclass:- If
valueis aLatitudeinstance, then the value is formatted as a positive angle followed by the "N" (positive value) or "S" (negative value) symbol. - If
valueis aLongitudeinstance, then the value is formatted as a positive angle followed by the "E" (positive value) or "W" (negative value) symbol. - If
valueis anyAngleother than aLatitudeorLongitude, then it is formatted as by theformat(double, StringBuffer, FieldPosition)method.
- Specified by:
formatin classFormat- Parameters:
value-Angleobject 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, ornullif this information is not wanted. This field position shall be created with one of theAngleFormat.Fieldconstants.- Returns:
- the
toAppendTobuffer, returned for method calls chaining. - Throws:
IllegalArgumentException- ifvalueif not an instance ofAngle.
- If
-
formatToCharacterIterator
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 byAttributedCharacterIterator 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). } }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.Fieldattributes in addition to theAngleFormat.Fieldones. Consequently, the same character may have more than one attribute. For example, when formatting 45°30′15.0″N, then:- The
45°part has theAngleFormat.Field.DEGREESattribute. - The
30′part has theAngleFormat.Field.MINUTESattribute. - The
15.0″part has theAngleFormat.Field.SECONDSattribute. - The
Npart has theAngleFormat.Field.HEMISPHEREattribute. - The
45,30and15parts have theNumberFormat.Field.INTEGERattribute. - The
.part has theNumberFormat.Field.DECIMAL_SEPARATORattribute. - The last
0part has theNumberFormat.Field.FRACTIONattribute.
CharSequenceinterface for convenience.- Overrides:
formatToCharacterIteratorin classFormat- Parameters:
value- theAngleobject to format.- Returns:
- a character iterator together with the attributes describing the formatted value.
- Throws:
IllegalArgumentException- ifvalueif not an instance ofAngle.
- The
-
parse
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 ifisFallbackAllowed()istrue, 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 ofLongitude. Otherwise this method returns an instance ofAngle.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, useparse(String)instead. -
parse
Parses the given string as an angle. This full string is expected to represents an angle value. This assumption allowsparse(String)to be more tolerant thanparse(String, ParsePosition)regarding white spaces between degrees, minutes and seconds fields.- Parameters:
source- the string to parse.- Returns:
- the parsed string as an
Angle,LatitudeorLongitudeobject. - Throws:
ParseException- if the string cannot be fully parsed.- See Also:
-
parseObject
Parses a substring as an object. The default implementation delegates toparse(String, ParsePosition).- Specified by:
parseObjectin classFormat- Parameters:
source- the string to parse.pos- the position where to start parsing.- Returns:
- the parsed string as an
Angle,LatitudeorLongitudeobject.
-
parseObject
Parses the given string as an object. The default implementation delegates toparse(String).- Overrides:
parseObjectin classFormat- Parameters:
source- the string to parse.- Returns:
- the parsed string as an
Angle,LatitudeorLongitudeobject. - Throws:
ParseException- if the string cannot be fully parsed.
-
isFallbackAllowed
public boolean isFallbackAllowed()Returnstrueif theparsemethods are allowed to fallback on the build-in default symbols if the string to parse doesn't match the applied pattern.- Returns:
trueif the ASCII quote characters are allowed at parsing time.
-
setFallbackAllowed
public void setFallbackAllowed(boolean allowed) Sets whether theparsemethods 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 (inparse(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.
true, because many end-users will not enter the Unicode′and″symbols. However, developers may need to set this flag tofalseif those ASCII symbols are used in a wider context (for example the"character for quoting strings).- Parameters:
allowed-trueif the ASCII quote characters are allowed at parsing time.
-
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:
getLocalein interfaceLocalized- Returns:
- this formatter locale (never
null).
-
clone
Returns a clone of thisAngleFormat. -
hashCode
public int hashCode()Returns a "hash value" for this object. -
equals
Compares this format with the specified object for equality. -
toString
Returns a string representation of this object for debugging purpose.
-