ArcGIS Runtime SDK for iOS: AGSCoordinateFormatter Class Reference
ArcGIS Runtime SDK for iOS  100.12
AGSCoordinateFormatter Class Reference

Description

Formatter to convert between coordinates and their string representation.

Instances of this class represent a formatter than can convert between coordinates and their string representation in various formats such as decimal degrees; degrees, minutes, and seconds; U.S. National Grid (USNG); and Military Grid Reference System (MGRS).

Since
100.1
Inheritance diagram for AGSCoordinateFormatter:
AGSObject

Class Methods

(nullable NSString *) + GARSStringFromPoint:
 
(nullable NSString *) + GEOREFStringFromPoint:precision:
 
(nullable NSString *) + LatitudeLongitudeStringFromPoint:format:decimalPlaces:
 
(nullable NSString *) + MGRSStringFromPoint:conversionMode:precision:addSpaces:
 
(nullable AGSPoint *) + pointFromGARSString:spatialReference:conversionMode:
 
(nullable AGSPoint *) + pointFromGEOREFString:spatialReference:
 
(nullable AGSPoint *) + pointFromLatitudeLongitudeString:spatialReference:
 
(nullable AGSPoint *) + pointFromMGRSString:spatialReference:conversionMode:
 
(nullable AGSPoint *) + pointFromUSNGString:spatialReference:
 
(nullable AGSPoint *) + pointFromUTMString:spatialReference:conversionMode:
 
(nullable NSString *) + USNGStringFromPoint:precision:addSpaces:
 
(nullable NSString *) + UTMStringFromPoint:conversionMode:addSpaces:
 

Method Documentation

◆ GARSStringFromPoint:

+ (nullable NSString*) GARSStringFromPoint: (AGSPoint *)  point

Returns a coordinate notation string in Global Area Reference System (GARS) format representing the given point's location.

Parameters
pointto be represented in GARS notation. The point must have a spatial reference.
Returns
A GARS notation string representing the GARS cell containing the given point.
Since
100.1

◆ GEOREFStringFromPoint:precision:

+ (nullable NSString*) GEOREFStringFromPoint: (AGSPoint *)  point
precision: (NSInteger)  precision 

Returns a coordinate notation string in World Geographic Reference system (GEOREF) format representing the given point's location. The precision value controls the number of digits used to represent the fractional part of coordinate's latitude and longitude, expressed in minutes. For example:

Precision Example output Angular precision Approx precision*
0 MKML5056 1min 2km
1 MKML5056 1min 2km
2 MKML5056 1min 2km
3 MKML502566 0.1min 200m
4 MKML50285665 0.01min 20m
5 MKML5028256652 0.001min 2m

*At the equator to 1 significant figure.

Parameters
pointto be represented in GEOREF notation. The point must have a spatial reference.
precisionwith which to represent the coordinate. It should be in the interval [0, 9].
Returns
A GEOREF notation string representing the position of the given point. Returns nil on error.
Since
100.1

◆ LatitudeLongitudeStringFromPoint:format:decimalPlaces:

+ (nullable NSString*) LatitudeLongitudeStringFromPoint: (AGSPoint *)  point
format: (AGSLatitudeLongitudeFormat format
decimalPlaces: (NSInteger)  decimalPlaces 

Returns a coordinate notation string in latitude-longitude format representing the given point's location. The latitude-longitude string will contain a space separating the latitude from the longitude value, and the characters 'N' or 'S', and 'E' and 'W', to indicate the hemisphere of each value. The string will also contain spaces separating the components (degrees, minutes, seconds) of each value. The precision of the output is controlled by both the format and decimalPlaces parameters. For example:

DecimalPlaces Format Example output Angular precision Approx precision*
0 AGSLatitudeLongitudeFormatDecimalDegrees 056N 0003W 1deg 100km
1 AGSLatitudeLongitudeFormatDecimalDegrees 55.9N 003.2W 0.1deg 10km
2 AGSLatitudeLongitudeFormatDecimalDegrees 55.94N 003.16W 0.01deg 1km
3 AGSLatitudeLongitudeFormatDecimalDegrees 55.944N 003.162W 0.001deg 100m
0 AGSLatitudeLongitudeFormatDegreesDecimalMinutes 55 057N 003 010W 1min 2km
1 AGSLatitudeLongitudeFormatDegreesDecimalMinutes 55 56.7N 003 09.7W 0.1min 200m
2 AGSLatitudeLongitudeFormatDegreesDecimalMinutes 55 56.65N 003 09.72W 0.01min 20m
3 AGSLatitudeLongitudeFormatDegreesDecimalMinutes 55 56.650N 003 09.717W 0.001min 2m
0 AGSLatitudeLongitudeFormatDegreesMinutesSeconds 55 56 039N 003 09 043W 1sec 30m
1 AGSLatitudeLongitudeFormatDegreesMinutesSeconds 55 56 39.1N 003 09 43.0W 0.1sec 3m
2 AGSLatitudeLongitudeFormatDegreesMinutesSeconds 55 56 39.12N 003 09 43.03W 0.01sec 300mm
3 AGSLatitudeLongitudeFormatDegreesMinutesSeconds 55 56 39.123N 003 09 43.034W 0.001sec 30mm

*At the equator to 1 significant figure.

Parameters
pointto be represented in latitude-longitude notation. The point must have a spatial reference.
formatThe mode to use when formatting the latitude-longitude string.
decimalPlacesThe number of decimal places to use. It should be in the interval [0, 16].
Returns
A latitude-longitude notation string representing the position of the given point. Returns nil on error.
Since
100.1

◆ MGRSStringFromPoint:conversionMode:precision:addSpaces:

+ (nullable NSString*) MGRSStringFromPoint: (AGSPoint *)  point
conversionMode: (AGSMGRSConversionMode conversionMode
precision: (NSInteger)  precision
addSpaces: (BOOL)  addSpaces 

Returns a coordinate notation string in Military Grid Reference System (MGRS) format representing the given point's location. The precision value controls the number of digits used to represent each numerical easting and northing value within the MGRS string. For example:

Precision Add spaces Example output Approx precision
0 false 30UVG 100km
1 false 30UVG89 10km
2 false 30UVG8999 1km
3 false 30UVG898998 100m
4 false 30UVG89889988 10m
5 false 30UVG8988499881 1m
0 true 30U VG 100km
1 true 30U VG 8 9 10km
2 true 30U VG 89 99 1km
3 true 30U VG 898 998 100m
4 true 30U VG 8988 9988 10m
5 true 30U VG 89884 99881 1m
Parameters
pointto be represented in MGRS notation. The point must have a spatial reference.
conversionModeThe mode to use for the returned MGRS notation string.
precisionThe precision with which to represent the coordinate. It should be in the interval [0, 8].
addSpacesIf false, the generated string will contain no spaces. If true, a space separates the grid zone designator, the 100km square identifier, and the numerical easting and northing values.
Returns
A MGRS notation string representing the position of the given point. Returns nil on error.
Since
100.1

◆ pointFromGARSString:spatialReference:conversionMode:

+ (nullable AGSPoint*) pointFromGARSString: (NSString *)  GARSString
spatialReference: (nullable AGSSpatialReference *)  spatialReference
conversionMode: (AGSGARSConversionMode conversionMode 

Returns a point by parsing a coordinate notation string in the Global Area Reference System (GARS) format.

GARS notation examples
354ND
354ND22
Note
The spatial reference provided must have an ellipsoid and datum matching those used by the source of the GARS string. If no spatial reference is provided, it is assumed the GARS string is referenced to WGS 84. The GARS string must not contain any whitespace.
Parameters
GARSStringthe coordinate notation string in GARS format
spatialReferencein which the point should be returned
conversionModedetermining whether the returned point will represent the lower-left (south-west) or center of the GARS cell, quadrant or area.
Returns
A point with the location from the GARS string in the spatial reference provided.
Since
100.1

◆ pointFromGEOREFString:spatialReference:

+ (nullable AGSPoint*) pointFromGEOREFString: (NSString *)  GEOREFString
spatialReference: (nullable AGSSpatialReference *)  spatialReference 

Returns a point by parsing a coordinate notation string in the World Geographic Reference system (GEOREF) format.

GEOREF notation examples
MKML5056
MKML50285665
Note
The spatial reference provided must have an ellipsoid and datum matching those used by the source of the GEOREF string. If no spatial reference is provided, it is assumed the GEOREF string is referenced to WGS 84. The GEOREF string may contain leading and trailing whitespace.
Parameters
GEOREFStringthe coordinate notation string in GEOREF format
spatialReferencein which the point should be returned
Returns
A point with the location from the GEOREF string in the spatial reference provided.
Since
100.1

◆ pointFromLatitudeLongitudeString:spatialReference:

+ (nullable AGSPoint*) pointFromLatitudeLongitudeString: (NSString *)  latLongString
spatialReference: (nullable AGSSpatialReference *)  spatialReference 

Returns a point by parsing a coordinate notation string in latitude-longitude format such as decimal degrees, degrees and decimal minutes, or degrees, minutes, and seconds. The latitude-longitude string may contain leading and trailing whitespace, and may also contain a space, comma, or vertical bar symbol to separate the latitude from the longitude. It may also contain the characters 'N', 'S', 'E' and 'W', or use a minus (-) symbol to indicate the hemisphere of each value.

Latitude-longitude notation examples
55 56 39.123N 003 09 43.034W
55°56′39″N 3°09′43″W
55~56.65205', -003~09.71723'
55.9442008* | -3.1619539*
Supported characters
Symbol Character Name Unicode number HTML code
Degree Asterisk U+002A *
^ Circumflex Accent U+005E ^
~ Tilde U+007E ~
° Degree Sign U+00B0 °
º Masculine Ordinal Indicator U+00BA º
˚ Ring Above U+02DA ˚
Superscript Zero U+2070 ⁰
Minute ' Apostrophe U+0027 '
Right Single Quotation Mark U+2019 ᾿
Prime U+2032 ′
Second " Quotation Mark U+0022 "
˝ Double Acute Accent U+02DD ˝
Right Double Quotation Mark U+201D ”
Double Prime U+2033 ″
Note
The spatial reference provided must have an ellipsoid and datum matching those used by the source of the latitude-longitude string. If no spatial reference is provided, it is assumed the latitude-longitude coordinates are referenced to WGS 84.
Parameters
latLongStringthe coordinate notation string in latitude-longitude format
spatialReferencein which the point should be returned
Returns
A point with the location from the latitude-longitude string in the spatial reference provided.
Since
100.1

◆ pointFromMGRSString:spatialReference:conversionMode:

+ (nullable AGSPoint*) pointFromMGRSString: (NSString *)  MGRSString
spatialReference: (nullable AGSSpatialReference *)  spatialReference
conversionMode: (AGSMGRSConversionMode conversionMode 

Returns a point by parsing a coordinate notation string in the Military Grid Reference System (MGRS) format.

MGRS notation examples
30UVG898998
30UVG 89885 99877
Note
The spatial reference provided must have an ellipsoid and datum matching those used by the source of the MGRS string. If no spatial reference is provided, it is assumed the MGRS string is referenced to WGS 84. For an explanation of the different modes for interpreting an MGRS notation string, please see AGSMGRSConversionMode. Note that the choice between zone 01 and 60 has no impact when reading from an MGRS notation string. The MGRS string can contain leading and trailing whitespace and can have whitespace between the grid zone designator, the 100km square identifier, and the numerical eastings and northings.
Parameters
MGRSStringthe coordinate notation string in MGRS format
spatialReferencein which the point should be returned
conversionModedetermining the lettering scheme and treatment of coordinates at 180 degrees longitude.
Returns
A point with the location from the MGRS string in the spatial reference provided.
Since
100.1

◆ pointFromUSNGString:spatialReference:

+ (nullable AGSPoint*) pointFromUSNGString: (NSString *)  USNGString
spatialReference: (nullable AGSSpatialReference *)  spatialReference 

Returns a point by parsing a coordinate notation string in the United States National Grid (USNG) format.

USNG notation examples
13TFJ 23 59
13TFJ2374159574
Note
The spatial reference provided must have an ellipsoid and datum matching those used by the source of the USNG string. If no spatial reference is provided and the USNG string is suffixed with "(NAD 27)", it is assumed the USNG string is referenced to NAD 27. If no spatial reference is provided and no such suffix exists, it is assumed the USNG string is referenced to WGS 84. The USNG string can contain leading and trailing whitespace and can have whitespace between the grid zone designator, the 100km square identifier and the numerical eastings and northings.
Parameters
USNGStringthe coordinate notation string in USNG format
spatialReferencein which the point should be returned
Returns
A point with the location from the USNG string in the spatial reference provided.
Since
100.1

◆ pointFromUTMString:spatialReference:conversionMode:

+ (nullable AGSPoint*) pointFromUTMString: (NSString *)  UTMString
spatialReference: (nullable AGSSpatialReference *)  spatialReference
conversionMode: (AGSUTMConversionMode conversionMode 

Returns a point by parsing a coordinate notation string in the Universal Transverse Mercator (UTM) format.

UTM notation examples
30U 489885 6199877
30U4898856199877
30N 489885 6199877 (using N/S indicator)
Note
The spatial reference provided must have an ellipsoid and datum matching those used by the source of the UTM string. If no spatial reference is provided, it is assumed the UTM string is referenced to WGS 84. The UTM string can contain leading and trailing whitespace and can have whitespace between the zone and latitude designator and the numerical eastings and northings..
Parameters
UTMStringthe coordinate notation string in UTM format
spatialReferencein which the point should be returned
conversionModeindicating whether the coordinate string contains North or South Hemisphere indicators, or a latitude band identified with letters C through X (omitting I and O).
Returns
A point with the location from the UTM string in the spatial reference provided.
Since
100.1

◆ USNGStringFromPoint:precision:addSpaces:

+ (nullable NSString*) USNGStringFromPoint: (AGSPoint *)  point
precision: (NSInteger)  precision
addSpaces: (BOOL)  addSpaces 

Returns a coordinate notation string in United States National Grid (USNG) format representing the given point's location. The precision value controls the number of digits used to represent each numerical easting and northing value within the USNG string. For example:

Precision Add spaces Example output Approx precision
0 false 13TFJ 100km
1 false 13TFJ25 10km
2 false 13TFJ2359 1km
3 false 13TFJ237595 100m
4 false 13TFJ23745951 10m
5 false 13TFJ2374359512 1m
0 true 13T FJ 100km
1 true 13T FJ 2 5 10km
2 true 13T FJ 23 59 1km
3 true 13T FJ 237 595 100m
4 true 13T FJ 2374 5951 10m
5 true 13T FJ 23743 59512 1m
*4 false 13TFJ23795929 (NAD 27) 10m
*2 true 13T FJ 23 59 (NAD 27) 1km

*When the point's spatial reference is based on NAD 27

Parameters
pointto be represented in USNG notation. The point must have a spatial reference.
precisionThe precision with which to represent the coordinate. It should be in the interval [0, 8].
addSpacesIf false, the generated string will contain no spaces. If true, a space separates the grid zone designator, the 100km square identifier, and the numerical easting and northing values.
Returns
A USNG notation string representing the position of the given point. Returns nil on error.
Since
100.1

◆ UTMStringFromPoint:conversionMode:addSpaces:

+ (nullable NSString*) UTMStringFromPoint: (AGSPoint *)  point
conversionMode: (AGSUTMConversionMode conversionMode
addSpaces: (BOOL)  addSpaces 

Returns a coordinate notation string in Universal Transverse Mercator (UTM) format representing the given point's location.

UTM Conversion Mode add_spaces Example output
AGSUTMConversionModeLatitudeBandIndicators false 30U4898846199881
AGSUTMConversionModeLatitudeBandIndicators true 30U 489884 6199881
AGSUTMConversionModeNorthSouthIndicators false 30N4898846199881
AGSUTMConversionModeNorthSouthIndicators true 30N 489884 6199881
Parameters
pointto be represented in UTM notation. The point must have a spatial reference.
conversionModeThe latitude notation scheme to use in the returned UTM notation string, either a latitudinal band, or a hemisphere designator.
addSpacesIf false, the generated string will contain no spaces. If true, a space separates the UTM zone and latitude designator, and each numerical easting and northing value
Returns
A UTM notation string representing the position of the given point.
Since
100.1