Geometry formatters and value methods

platform/darwin/include/MGLClockDirectionFormatter.h

@@ -0,0 +1,52 @@
+#import <Foundation/Foundation.h>
+#import <CoreLocation/CoreLocation.h>
+
+#import "MGLTypes.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ The `MGLClockDirectionFormatter` class provides properly formatted descriptions
+ of headings relative to the user, known as <i>clock positions</i>. For
+ example, a value of `90` may be formatted as “3 o’clock”, depending on the
+ locale.
+
+ Use this class to create localized heading strings when displaying directions
+ relative to the user’s current location and heading. To format a direction
+ irrespective of the user’s orientation, use `MGLCompassDirectionFormatter`
+ instead.
+ */
+@interface MGLClockDirectionFormatter : NSFormatter
+
+/**
+ The unit style used by this formatter.
+
+ This property defaults to `NSFormattingUnitStyleMedium`.
+ */
+@property (nonatomic) NSFormattingUnitStyle unitStyle;
+
+/**
+ The locale of the receiver.
+
+ The locale determines the output language and numeral system of the output.
+ */
+@property (copy) NSLocale *locale;
+
+/**
+ Returns a clock position string for the provided value.
+
+ @param direction The heading, measured in degrees, where 0° means “straight
+    ahead” and 90° means “directly to your right”.
+ @return The clock position string appropriately formatted for the receiver’s
+    locale.
+ */
+- (NSString *)stringFromDirection:(CLLocationDirection)direction;
+
+/**
+ This method is not supported for the `MGLDirectionFormatter` class.
+ */
+- (BOOL)getObjectValue:(out id __nullable * __nullable)obj forString:(NSString *)string errorDescription:(out NSString * __nullable * __nullable)error;
+
+@end
+
+NS_ASSUME_NONNULL_END

platform/darwin/include/MGLCompassDirectionFormatter.h

@@ -0,0 +1,42 @@
+#import <Foundation/Foundation.h>
+#import <CoreLocation/CoreLocation.h>
+
+#import "MGLTypes.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ The `MGLCompassDirectionFormatter` class provides properly formatted
+ descriptions of absolute headings. For example, a value of `90` may be
+ formatted as “east”, depending on the locale.
+
+ Use this class to create localized heading strings when displaying directions
+ irrespective of the user’s current location. To format a direction relative to
+ the user’s current location, use `MGLCompassDirectionFormatter` instead.
+ */
+@interface MGLCompassDirectionFormatter : NSFormatter
+
+/**
+ The unit style used by this formatter.
+
+ This property defaults to `NSFormattingUnitStyleMedium`.
+ */
+@property (nonatomic) NSFormattingUnitStyle unitStyle;
+
+/**
+ Returns a heading string for the provided value.
+
+ @param direction The heading, measured in degrees, where 0° means “due north”
+    and 90° means “due east”.
+ @return The heading string appropriately formatted for the formatter’s locale.
+ */
+- (NSString *)stringFromDirection:(CLLocationDirection)direction;
+
+/**
+ This method is not supported for the `MGLDirectionFormatter` class.
+ */
+- (BOOL)getObjectValue:(out id __nullable * __nullable)obj forString:(NSString *)string errorDescription:(out NSString * __nullable * __nullable)error;
+
+@end
+
+NS_ASSUME_NONNULL_END

platform/darwin/include/MGLCoordinateFormatter.h

@@ -0,0 +1,31 @@
+#import <Foundation/Foundation.h>
+#import <CoreLocation/CoreLocation.h>
+
+#import "MGLTypes.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ The `MGLCoordinateFormatter` class provides properly formatted descriptions of
+ geographic coordinate pairs. Use this class to create localized coordinate
+ strings when displaying location information to users.
+ */
+@interface MGLCoordinateFormatter : NSFormatter
+
+/**
+ Returns a coordinate string for the provided value.
+
+ @param coordinate The coordinate’s value.
+ @return The coordinate string appropriately formatted for the formatter’s
+    locale.
+ */
+- (NSString *)stringFromCoordinate:(CLLocationCoordinate2D)coordinate;
+
+/**
+ This method is not supported for the `MGLCoordinateFormatter` class.
+ */
+- (BOOL)getObjectValue:(out id __nullable * __nullable)obj forString:(NSString *)string errorDescription:(out NSString * __nullable * __nullable)error;
+
+@end
+
+NS_ASSUME_NONNULL_END

platform/darwin/include/MGLGeometry.h

@@ -95,4 +95,11 @@ NS_INLINE CLLocationDegrees MGLDegreesFromRadians(CGFloat radians) {
     return radians * 180 / M_PI;
 }
 
+/**
+ Methods for round-tripping Mapbox geometry structure values.
+ */
+@interface NSValue (MGLGeometryAdditions)
+
+@end
+
 NS_ASSUME_NONNULL_END

platform/darwin/include/MGLOfflinePack.h

@@ -177,25 +177,4 @@ typedef struct MGLOfflinePackProgress {
 
 @end
 
-/**
- Methods for round-tripping `MGLOfflinePackProgress` values.
- */
-@interface NSValue (MGLOfflinePackAdditions)
-
-/**
- Creates a new value object containing the given `MGLOfflinePackProgress`
- structure.
-
- @param progress The value for the new object.
- @return A new value object that contains the offline pack progress information.
- */
-+ (NSValue *)valueWithMGLOfflinePackProgress:(MGLOfflinePackProgress)progress;
-
-/**
- The `MGLOfflinePackProgress` structure representation of the value.
- */
-@property (readonly) MGLOfflinePackProgress MGLOfflinePackProgressValue;
-
-@end
-
 NS_ASSUME_NONNULL_END

platform/darwin/include/MGLTypes.h

@@ -17,10 +17,15 @@ NS_ASSUME_NONNULL_BEGIN
 /** Indicates an error occurred in the Mapbox SDK. */
 extern NSString * const MGLErrorDomain;
 
+/** Error constants for the Mapbox SDK. */
 typedef NS_ENUM(NSInteger, MGLErrorCode) {
+    /** An unknown error occurred. */
     MGLErrorCodeUnknown = -1,
+    /** The resource could not be found. */
     MGLErrorCodeNotFound = 1,
+    /** The connection received an invalid server response. */
     MGLErrorCodeBadServerResponse = 2,
+    /** An attempt to establish a connection failed. */
     MGLErrorCodeConnectionFailed = 3,
 };
 

platform/darwin/include/NSValue+MGLAdditions.h

@@ -0,0 +1,75 @@
+#import <Foundation/Foundation.h>
+
+#import "MGLGeometry.h"
+#import "MGLOfflinePack.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ Methods for round-tripping values for Mapbox-defined types.
+ */
+@interface NSValue (MGLAdditions)
+
+#pragma mark Working with Geographic Coordinate Values
+
+/**
+ Creates a new value object containing the specified Core Location geographic
+ coordinate structure.
+
+ @param coordinate The value for the new object.
+ @return A new value object that contains the geographic coordinate information.
+ */
++ (instancetype)valueWithMGLCoordinate:(CLLocationCoordinate2D)coordinate;
+
+/**
+ The Core Location geographic coordinate structure representation of the value.
+ */
+@property (readonly) CLLocationCoordinate2D MGLCoordinateValue;
+
+/**
+ Creates a new value object containing the specified Mapbox coordinate span
+ structure.
+
+ @param span The value for the new object.
+ @return A new value object that contains the coordinate span information.
+ */
++ (instancetype)valueWithMGLCoordinateSpan:(MGLCoordinateSpan)span;
+
+/**
+ The Mapbox coordinate span structure representation of the value.
+ */
+@property (readonly) MGLCoordinateSpan MGLCoordinateSpanValue;
+
+/**
+ Creates a new value object containing the specified Mapbox coordinate bounds
+ structure.
+
+ @param bounds The value for the new object.
+ @return A new value object that contains the coordinate bounds information.
+ */
++ (instancetype)valueWithMGLCoordinateBounds:(MGLCoordinateBounds)bounds;
+
+/**
+ The Mapbox coordinate bounds structure representation of the value.
+ */
+@property (readonly) MGLCoordinateBounds MGLCoordinateBoundsValue;
+
+#pragma mark Working with Offline Map Values
+
+/**
+ Creates a new value object containing the given `MGLOfflinePackProgress`
+ structure.
+
+ @param progress The value for the new object.
+ @return A new value object that contains the offline pack progress information.
+ */
++ (NSValue *)valueWithMGLOfflinePackProgress:(MGLOfflinePackProgress)progress;
+
+/**
+ The `MGLOfflinePackProgress` structure representation of the value.
+ */
+@property (readonly) MGLOfflinePackProgress MGLOfflinePackProgressValue;
+
+@end
+
+NS_ASSUME_NONNULL_END

platform/darwin/src/MGLClockDirectionFormatter.m

@@ -0,0 +1,64 @@
+#import "MGLClockDirectionFormatter.h"
+
+#define wrap(value, min, max) \
+    (fmod((fmod((value - min), (max - min)) + (max - min)), (max - min)) + min)
+
+@implementation MGLClockDirectionFormatter {
+    NSNumberFormatter *_numberFormatter;
+}
+
+- (instancetype)init {
+    if (self = [super init]) {
+        _unitStyle = NSFormattingUnitStyleMedium;
+        _numberFormatter = [[NSNumberFormatter alloc] init];
+    }
+    return self;
+}
+
+- (NSLocale *)locale {
+    return _numberFormatter.locale;
+}
+
+- (void)setLocale:(NSLocale *)locale {
+    _numberFormatter.locale = locale;
+}
+
+- (NSString *)stringFromDirection:(CLLocationDirection)direction {
+    NSInteger hour = round(-wrap(-direction, -360, 0) / 360 * 12);
+    NSString *format;
+    NSNumberFormatterStyle style = NSNumberFormatterDecimalStyle;
+    switch (self.unitStyle) {
+        case NSFormattingUnitStyleShort:
+            format = NSLocalizedString(@"%@:00", @"Clock position format, short style");
+            break;
+
+        case NSFormattingUnitStyleMedium:
+            format = NSLocalizedString(@"%@ o’clock", @"Clock position format, medium style");
+
+            break;
+
+        case NSFormattingUnitStyleLong:
+            format = NSLocalizedString(@"%@ o’clock", @"Clock position format, long style");
+            style = NSNumberFormatterSpellOutStyle;
+            break;
+
+        default:
+            break;
+    }
+    _numberFormatter.numberStyle = style;
+    return [NSString stringWithFormat:format, [_numberFormatter stringFromNumber:@(hour)]];
+}
+
+- (nullable NSString *)stringForObjectValue:(id)obj {
+    if (![obj isKindOfClass:[NSValue class]]) {
+        return nil;
+    }
+    return [self stringFromDirection:[obj doubleValue]];
+}
+
+- (BOOL)getObjectValue:(out id __nullable * __nullable)obj forString:(NSString *)string errorDescription:(out NSString * __nullable * __nullable)error {
+    NSAssert(NO, @"-getObjectValue:forString:errorDescription: has not been implemented");
+    return NO;
+}
+
+@end