Updated readme

Migrated examples to Swift 3, correcting some API misusage along the way. Point Podfile and Cartfile to master for now, until the first Swift 3 release.

Author: 1ec5

README.md

@@ -20,17 +20,19 @@ Download a framework build from [the releases page](https://github.com/mapbox/Ma
 In your Podfile:
 
 ```podspec
-pod 'MapboxGeocoder.swift', :git => 'https://github.com/mapbox/MapboxGeocoder.swift.git', :tag => 'v0.5.2'
+pod 'MapboxGeocoder.swift', :git => 'https://github.com/mapbox/MapboxGeocoder.swift.git', :branch => 'master'
 ```
 
 **[Carthage](https://github.com/Carthage/Carthage)**
 
 In your Cartfile:
 
 ```sh
-github "Mapbox/MapboxGeocoder.swift" ~> 0.5
+github "Mapbox/MapboxGeocoder.swift" "master"
 ```
 
+v0.5.2 is the last release of MapboxGeocoder.swift written in Swift 2.3. The `swift2.3` branch corresponds to this release, plus any critical bug fixes that have been applied since. All subsequent releases will be based on the `master` branch, which is written in Swift 3. The Swift examples below are written in Swift 3; see the `swift2.3` branch’s readme for Swift 2.3 examples.
+
 This repository includes example applications written in both Swift and Objective-C showing use of the framework (as well as a comparison of writing apps in either language). More examples and detailed documentation are available in the [Mapbox API Documentation](https://www.mapbox.com/api-documentation/?language=Swift#geocoding).
 
 ## Usage
@@ -67,7 +69,7 @@ let geocoder = Geocoder.sharedGeocoder
 MBGeocoder *geocoder = [MBGeocoder sharedGeocoder];
 ```
 
-With the geocoder in hand, construct a geocode options object and pass it into the `Geocoder.geocode(options:completionHandler:)` method.
+With the geocoder in hand, construct a geocode options object and pass it into the `Geocoder.geocode(_:completionHandler:)` method.
 
 ### Forward geocoding
 
@@ -84,27 +86,29 @@ let options = ForwardGeocodeOptions(query: "200 queen street")
 // To refine the search, you can set various properties on the options object.
 options.allowedISOCountryCodes = ["CA"]
 options.focalLocation = CLLocation(latitude: 45.3, longitude: -66.1)
-options.allowedScopes = [.Address, .PointOfInterest]
+options.allowedScopes = [.address, .pointOfInterest]
 
-let task = geocoder.geocode(options: options) { (placemarks, attribution, error) in
-    if let placemark = placemarks?[0] {
-        print(placemark.name)
-            // 200 Queen St
-        print(placemark.qualifiedName)
-            // 200 Queen St, Saint John, New Brunswick E2L 2X1, Canada
-        
-        let coordinate = placemark.location!.coordinate
-        print("\(coordinate.latitude), \(coordinate.longitude)")
-            // 45.270093, -66.050985
-        
-        #if !os(tvOS)
+let task = geocoder.geocode(options) { (placemarks, attribution, error) in
+    guard let placemark = placemarks?.first else {
+        return
+    }
+    
+    print(placemark.name)
+        // 200 Queen St
+    print(placemark.qualifiedName)
+        // 200 Queen St, Saint John, New Brunswick E2L 2X1, Canada
+    
+    let coordinate = placemark.location.coordinate
+    print("\(coordinate.latitude), \(coordinate.longitude)")
+        // 45.270093, -66.050985
+    
+    #if !os(tvOS)
         let formatter = CNPostalAddressFormatter()
-        print(formatter.stringFromPostalAddress(placemark.postalAddress))
+        print(formatter.string(from: placemark.postalAddress!))
             // 200 Queen St
             // Saint John New Brunswick E2L 2X1
             // Canada
-        #endif
-    }
+    #endif
 }
 ```
 
@@ -121,10 +125,10 @@ options.allowedISOCountryCodes = @[@"CA"];
 options.focalLocation = [[CLLocation alloc] initWithLatitude:45.3 longitude:-66.1];
 options.allowedScopes = MBPlacemarkScopeAddress | MBPlacemarkScopePointOfInterest;
 
-NSURLSessionDataTask *task = [geocoder geocodeWithOptions:options
-                                        completionHandler:^(NSArray<MBGeocodedPlacemark *> * _Nullable placemarks,
-                                                            NSString * _Nullable attribution,
-                                                            NSError * _Nullable error) {
+NSURLSessionDataTask *task = [geocoder geocode:options
+                             completionHandler:^(NSArray<MBGeocodedPlacemark *> * _Nullable placemarks,
+                                                 NSString * _Nullable attribution,
+                                                 NSError * _Nullable error) {
     MBPlacemark *placemark = placemarks[0];
     NSLog(@"%@", placemark.name);
         // 200 Queen St
@@ -154,17 +158,20 @@ _Reverse geocoding_ takes a geographic coordinate and produces a hierarchy of pl
 let options = ReverseGeocodeOptions(coordinate: CLLocationCoordinate2D(latitude: 40.733, longitude: -73.989))
 // Or perhaps: ReverseGeocodeOptions(location: locationManager.location)
 
-let task = geocoder.geocode(options: options) { (placemarks, attribution, error) in
-    let placemark = placemarks[0]
-    print(placemark.imageName)
+let task = geocoder.geocode(options) { (placemarks, attribution, error) in
+    guard let placemark = placemarks?.first else {
+        return
+    }
+    
+    print(placemark.imageName ?? "")
         // telephone
-    print(placemark.genres?.joinWithSeparator(", "))
+    print(placemark.genres?.joined(separator: ", ") ?? "")
         // computer, electronic
-    print(placemark.region?.name)
+    print(placemark.administrativeRegion?.name ?? "")
         // New York
-    print(placemark.region?.code)
+    print(placemark.administrativeRegion?.code ?? "")
         // US-NY
-    print(placemark.place?.wikidataItemIdentifier)
+    print(placemark.place?.wikidataItemIdentifier ?? "")
         // Q60
 }
 ```
@@ -174,18 +181,18 @@ let task = geocoder.geocode(options: options) { (placemarks, attribution, error)
 MBReverseGeocodeOptions *options = [[MBReverseGeocodeOptions alloc] initWithCoordinate: CLLocationCoordinate2DMake(40.733, -73.989)];
 // Or perhaps: [[MBReverseGeocodeOptions alloc] initWithLocation:locationManager.location]
 
-NSURLSessionDataTask *task = [geocoder geocodeWithOptions:options
-                                        completionHandler:^(NSArray<MBGeocodedPlacemark *> * _Nullable placemarks,
-                                                            NSString * _Nullable attribution,
-                                                            NSError * _Nullable error) {
+NSURLSessionDataTask *task = [geocoder geocode:options
+                             completionHandler:^(NSArray<MBGeocodedPlacemark *> * _Nullable placemarks,
+                                                 NSString * _Nullable attribution,
+                                                 NSError * _Nullable error) {
     MBPlacemark *placemark = placemarks[0];
     NSLog(@"%@", placemark.imageName);
         // telephone
     NSLog(@"%@", [placemark.genres componentsJoinedByString:@", "]);
         // computer, electronic
-    NSLog(@"%@", placemark.region.name);
+    NSLog(@"%@", placemark.administrativeRegion.name);
         // New York
-    NSLog(@"%@", placemark.region.code);
+    NSLog(@"%@", placemark.administrativeRegion.code);
         // US-NY
     NSLog(@"%@", placemark.place.wikidataItemIdentifier);
         // Q60
@@ -194,7 +201,7 @@ NSURLSessionDataTask *task = [geocoder geocodeWithOptions:options
 
 ### Batch geocoding
 
-With _batch geocoding_, you can perform up to 50 distinct forward or reverse geocoding requests simultaneously and store the results in a private database. Create a ForwardBatchGeocodingOptions or ReverseBatchGeocodingOptions object in Swift, or an MBForwardBatchGeocodingOptions or MBReverseBatchGeocodingOptions object in Objective-C, and pass it into the `Geocoder.batchGeocode(options:completionHandler:)` method.
+With _batch geocoding_, you can perform up to 50 distinct forward or reverse geocoding requests simultaneously and store the results in a private database. Create a ForwardBatchGeocodingOptions or ReverseBatchGeocodingOptions object in Swift, or an MBForwardBatchGeocodingOptions or MBReverseBatchGeocodingOptions object in Objective-C, and pass it into the `Geocoder.batchGeocode(_:completionHandler:)` method.
 
 Batch geocoding is available to Mapbox enterprise accounts. See the [Mapbox Geocoding](https://www.mapbox.com/geocoding/) website for more information.