1 files changed, 139 insertions, 62 deletions
diff --git a/swift.html.markdown b/swift.html.markdown
index f451288d..b6554dc6 100644
--- a/swift.html.markdown
+++ b/swift.html.markdown
@@ -6,6 +6,8 @@ contributors:
   - ["Joey Huang", "http://github.com/kamidox"]
   - ["Anthony Nguyen", "http://github.com/anthonyn60"]
   - ["Clayton Walker", "https://github.com/cwalk"]
+  - ["Fernando Valverde", "http://visualcosita.xyz"]
+  - ["Alexey Nazaroff", "https://github.com/rogaven"]
 filename: learnswift.swift
 ---
 
@@ -25,12 +27,13 @@ import UIKit
 
 // Xcode supports landmarks to annotate your code and lists them in the jump bar
 // MARK: Section mark
+// MARK: - Section mark with a separator line
 // TODO: Do something soon
 // FIXME: Fix this code
 
 // In Swift 2, println and print were combined into one print method. Print automatically appends a new line.
 print("Hello, world") // println is now print
-print("Hello, world", appendNewLine: false) // printing without appending a newline
+print("Hello, world", terminator: "") // printing without appending a newline
 
 // variables (var) value can change after being set
 // constants (let) value can NOT be changed after being set
@@ -44,7 +47,7 @@ let `class` = "keyword" // backticks allow keywords to be used as variable names
 let explicitDouble: Double = 70
 let intValue = 0007 // 7
 let largeIntValue = 77_000 // 77000
-let label = "some text " + String(myVariable) // Casting
+let label = "some text " + String(myVariable) // String construction
 let piText = "Pi = \(π), Pi 2 = \(π * 2)" // String interpolation
 
 // Build Specific values
@@ -58,14 +61,14 @@ let piText = "Pi = \(π), Pi 2 = \(π * 2)" // String interpolation
 print("Build value: \(buildValue)") // Build value: 7
 
 /*
-    Optionals are a Swift language feature that either contains a value,
-    or contains nil (no value) to indicate that a value is missing.
-    A question mark (?) after the type marks the value as optional.
+Optionals are a Swift language feature that either contains a value,
+or contains nil (no value) to indicate that a value is missing.
+A question mark (?) after the type marks the value as optional.
 
-    Because Swift requires every property to have a value, even nil must be
-    explicitly stored as an Optional value.
+Because Swift requires every property to have a value, even nil must be
+explicitly stored as an Optional value.
 
-    Optional<T> is an enum.
+Optional<T> is an enum.
 */
 var someOptionalString: String? = "optional" // Can be nil
 // same as above, but ? is a postfix operator (syntax candy)
@@ -82,9 +85,9 @@ if someOptionalString != nil {
 someOptionalString = nil
 
 /*
-    Trying to use ! to access a non-existent optional value triggers a runtime 
-    error. Always make sure that an optional contains a non-nil value before
-    using ! to force-unwrap its value.
+Trying to use ! to access a non-existent optional value triggers a runtime
+error. Always make sure that an optional contains a non-nil value before
+using ! to force-unwrap its value.
 */
 
 // implicitly unwrapped optional
@@ -92,6 +95,8 @@ var unwrappedString: String! = "Value is expected."
 // same as above, but ! is a postfix operator (more syntax candy)
 var unwrappedString2: ImplicitlyUnwrappedOptional<String> = "Value is expected."
 
+// If let structure -
+// If let is a special structure in Swift that allows you to check if an Optional rhs holds a value, and in case it does - unwraps and assigns it to the lhs.
 if let someOptionalStringConstant = someOptionalString {
     // has `Some` value, non-nil
     if !someOptionalStringConstant.hasPrefix("ok") {
@@ -100,10 +105,12 @@ if let someOptionalStringConstant = someOptionalString {
 }
 
 // Swift has support for storing a value of any type.
-// AnyObject == id
-// Unlike Objective-C `id`, AnyObject works with any value (Class, Int, struct, etc.)
-var anyObjectVar: AnyObject = 7
-anyObjectVar = "Changed value to a string, not good practice, but possible."
+// For that purposes there is two keywords: `Any` and `AnyObject`
+// `AnyObject` == `id` from Objective-C
+// `Any` – also works with any scalar values (Class, Int, struct, etc.)
+var anyVar: Any = 7
+anyVar = "Changed value to a string, not good practice, but possible."
+let anyObjectVar: AnyObject = Int(1) as NSNumber
 
 /*
     Comment here
@@ -118,8 +125,8 @@ anyObjectVar = "Changed value to a string, not good practice, but possible."
 //
 
 /*
-    Array and Dictionary types are structs. So `let` and `var` also indicate
-    that they are mutable (var) or immutable (let) when declaring these types.
+Array and Dictionary types are structs. So `let` and `var` also indicate
+that they are mutable (var) or immutable (let) when declaring these types.
 */
 
 // Array
@@ -128,6 +135,7 @@ shoppingList[1] = "bottle of water"
 let emptyArray = [String]() // let == immutable
 let emptyArray2 = Array<String>() // same as above
 var emptyMutableArray = [String]() // var == mutable
+var explicitEmptyMutableStringArray: [String] = [] // same as above
 
 
 // Dictionary
@@ -139,12 +147,21 @@ occupations["Jayne"] = "Public Relations"
 let emptyDictionary = [String: Float]() // let == immutable
 let emptyDictionary2 = Dictionary<String, Float>() // same as above
 var emptyMutableDictionary = [String: Float]() // var == mutable
+var explicitEmptyMutableDictionary: [String: Float] = [:] // same as above
 
 
 //
 // MARK: Control Flow
 //
 
+// Condition statements support "," (comma) clauses, which can be used
+// to help provide conditions on optional values.
+// Both the assignment and the "," clause must pass.
+let someNumber = Optional<Int>(7)
+if let num = someNumber, num > 3 {
+    print("num is greater than 3")
+}
+
 // for loop (array)
 let myArray = [1, 1, 2, 3, 5]
 for value in myArray {
@@ -174,8 +191,8 @@ while i < 1000 {
     i *= 2
 }
 
-// do-while loop
-do {
+// repeat-while loop
+repeat {
     print("hello")
 } while 1 == 2
 
@@ -194,7 +211,6 @@ default: // required (in order to cover all possible input)
     let vegetableComment = "Everything tastes good in soup."
 }
 
-
 //
 // MARK: Functions
 //
@@ -202,28 +218,28 @@ default: // required (in order to cover all possible input)
 // Functions are a first-class type, meaning they can be nested
 // in functions and can be passed around
 
-// Function with Swift header docs (format as reStructedText)
+// Function with Swift header docs (format as Swift-modified Markdown syntax)
 
 /**
-    A greet operation
+A greet operation
 
-    - A bullet in docs
-    - Another bullet in the docs
+- A bullet in docs
+- Another bullet in the docs
 
-    :param: name A name
-    :param: day A day
-    :returns: A string containing the name and day value.
+- Parameter name	: A name
+- Parameter day	: A day
+- Returns : A string containing the name and day value.
 */
 func greet(name: String, day: String) -> String {
     return "Hello \(name), today is \(day)."
 }
-greet("Bob", "Tuesday")
+greet(name: "Bob", day: "Tuesday")
 
 // similar to above except for the function parameter behaviors
-func greet2(#requiredName: String, externalParamName localParamName: String) -> String {
-    return "Hello \(requiredName), the day is \(localParamName)"
+func greet2(name: String, externalParamName localParamName: String) -> String {
+    return "Hello \(name), the day is \(localParamName)"
 }
-greet2(requiredName:"John", externalParamName: "Sunday")
+greet2(name: "John", externalParamName: "Sunday")
 
 // Function that returns multiple items in a tuple
 func getGasPrices() -> (Double, Double, Double) {
@@ -236,15 +252,37 @@ let (_, price1, _) = pricesTuple // price1 == 3.69
 print(price1 == pricesTuple.1) // true
 print("Gas price: \(price)")
 
+// Labeled/named tuple params
+func getGasPrices2() -> (lowestPrice: Double, highestPrice: Double, midPrice: Double) {
+    return (1.77, 37.70, 7.37)
+}
+let pricesTuple2 = getGasPrices2()
+let price2 = pricesTuple2.lowestPrice
+let (_, price3, _) = pricesTuple2
+print(pricesTuple2.highestPrice == pricesTuple2.1) // true
+print("Highest gas price: \(pricesTuple2.highestPrice)")
+
+// guard statements
+func testGuard() {
+    // guards provide early exits or breaks, placing the error handler code near the conditions.
+    // it places variables it declares in the same scope as the guard statement.
+    guard let aNumber = Optional<Int>(7) else {
+        return
+    }
+
+    print("number is \(aNumber)")
+}
+testGuard()
+
 // Variadic Args
 func setup(numbers: Int...) {
     // its an array
-    let number = numbers[0]
-    let argCount = numbers.count
+    let _ = numbers[0]
+    let _ = numbers.count
 }
 
 // Passing and returning functions
-func makeIncrementer() -> (Int -> Int) {
+func makeIncrementer() -> ((Int) -> Int) {
     func addOne(number: Int) -> Int {
         return 1 + number
     }
@@ -254,14 +292,14 @@ var increment = makeIncrementer()
 increment(7)
 
 // pass by ref
-func swapTwoInts(inout a: Int, inout b: Int) {
+func swapTwoInts(a: inout Int, b: inout Int) {
     let tempA = a
     a = b
     b = tempA
 }
 var someIntA = 7
 var someIntB = 3
-swapTwoInts(&someIntA, &someIntB)
+swapTwoInts(a: &someIntA, b: &someIntB)
 print(someIntB) // 7
 
 
@@ -289,23 +327,17 @@ numbers = numbers.map({ number in 3 * number })
 print(numbers) // [3, 6, 18]
 
 // Trailing closure
-numbers = sorted(numbers) { $0 > $1 }
+numbers = numbers.sorted { $0 > $1 }
 
 print(numbers) // [18, 6, 3]
 
-// Super shorthand, since the < operator infers the types
-
-numbers = sorted(numbers, < )
-
-print(numbers) // [3, 6, 18]
-
 //
 // MARK: Structures
 //
 
 // Structures and classes have very similar capabilities
 struct NamesTable {
-    let names = [String]()
+    let names: [String]
 
     // Custom subscript
     subscript(index: Int) -> String {
@@ -319,6 +351,44 @@ let name = namesTable[1]
 print("Name is \(name)") // Name is Them
 
 //
+// MARK: Error Handling
+//
+
+// The `Error` protocol is used when throwing errors to catch
+enum MyError: Error {
+    case BadValue(msg: String)
+    case ReallyBadValue(msg: String)
+}
+
+// functions marked with `throws` must be called using `try`
+func fakeFetch(value: Int) throws -> String {
+    guard 7 == value else {
+        throw MyError.ReallyBadValue(msg: "Some really bad value")
+    }
+
+    return "test"
+}
+
+func testTryStuff() {
+    // assumes there will be no error thrown, otherwise a runtime exception is raised
+    let _ = try! fakeFetch(value: 7)
+
+    // if an error is thrown, then it proceeds, but if the value is nil
+    // it also wraps every return value in an optional, even if its already optional
+    let _ = try? fakeFetch(value: 7)
+
+    do {
+        // normal try operation that provides error handling via `catch` block
+        try fakeFetch(value: 1)
+    } catch MyError.BadValue(let msg) {
+        print("Error message: \(msg)")
+    } catch {
+        // must be exhaustive
+    }
+}
+testTryStuff()
+
+//
 // MARK: Classes
 //
 
@@ -327,7 +397,7 @@ print("Name is \(name)") // Name is Them
 
 public class Shape {
     public func getArea() -> Int {
-        return 0;
+        return 0
     }
 }
 
@@ -349,6 +419,11 @@ internal class Rect: Shape {
         }
     }
 
+    // Computed properties must be declared as `var`, you know, cause' they can change
+    var smallestSideLength: Int {
+        return self.sideLength - 1
+    }
+
     // Lazily load a property
     // subShape remains nil (uninitialized) until getter called
     lazy var subShape = Rect(sideLength: 4)
@@ -371,7 +446,7 @@ internal class Rect: Shape {
 
     func shrink() {
         if sideLength > 0 {
-            --sideLength
+            sideLength -= 1
         }
     }
 
@@ -453,9 +528,10 @@ enum Suit {
 // when the variable is explicitly declared
 var suitValue: Suit = .Hearts
 
-// Non-Integer enums require direct raw value assignments
+// String enums can have direct raw value assignments
+// or their raw values will be derived from the Enum field
 enum BookName: String {
-    case John = "John"
+    case John
     case Luke = "Luke"
 }
 print("Name: \(BookName.John.rawValue)")
@@ -497,10 +573,11 @@ protocol ShapeGenerator {
 }
 
 // Protocols declared with @objc allow optional functions,
-// which allow you to check for conformance
+// which allow you to check for conformance. These functions must be
+// marked with @objc also.
 @objc protocol TransformShape {
-    optional func reshaped()
-    optional func canReshape() -> Bool
+    @objc optional func reshape()
+    @objc optional func canReshape() -> Bool
 }
 
 class MyShape: Rect {
@@ -512,9 +589,9 @@ class MyShape: Rect {
         // Place a question mark after an optional property, method, or
         // subscript to gracefully ignore a nil value and return nil
         // instead of throwing a runtime error ("optional chaining").
-        if let allow = self.delegate?.canReshape?() {
+        if let reshape = self.delegate?.canReshape?(), reshape {
             // test for delegate then for method
-            self.delegate?.reshaped?()
+            self.delegate?.reshape?()
         }
     }
 }
@@ -526,8 +603,8 @@ class MyShape: Rect {
 
 // `extension`s: Add extra functionality to an already existing type
 
-// Square now "conforms" to the `Printable` protocol
-extension Square: Printable {
+// Square now "conforms" to the `CustomStringConvertible` protocol
+extension Square: CustomStringConvertible {
     var description: String {
         return "Area: \(self.getArea()) - ID: \(self.identifier)"
     }
@@ -547,20 +624,20 @@ extension Int {
 }
 
 print(7.customProperty) // "This is 7"
-print(14.multiplyBy(3)) // 42
+print(14.multiplyBy(num: 3)) // 42
 
 // Generics: Similar to Java and C#. Use the `where` keyword to specify the
 //   requirements of the generics.
 
 func findIndex<T: Equatable>(array: [T], valueToFind: T) -> Int? {
-    for (index, value) in enumerate(array) {
+    for (index, value) in array.enumerated() {
         if value == valueToFind {
             return index
         }
     }
     return nil
 }
-let foundAtIndex = findIndex([1, 2, 3, 4], 3)
+let foundAtIndex = findIndex(array: [1, 2, 3, 4], valueToFind: 3)
 print(foundAtIndex == 2) // true
 
 // Operators:
@@ -568,10 +645,10 @@ print(foundAtIndex == 2) // true
 //      / = - + * % < > ! & | ^ . ~
 // or
 // Unicode math, symbol, arrow, dingbat, and line/box drawing characters.
-prefix operator !!! {}
+prefix operator !!!
 
 // A prefix operator that triples the side length when used
-prefix func !!! (inout shape: Square) -> Square {
+prefix func !!! (shape: inout Square) -> Square {
     shape.sideLength *= 3
     return shape
 }
@@ -584,8 +661,8 @@ print(mySquare.sideLength) // 4
 print(mySquare.sideLength) // 12
 
 // Operators can also be generics
-infix operator <-> {}
-func <-><T: Equatable> (inout a: T, inout b: T) {
+infix operator <->
+func <-><T: Equatable> (a: inout T, b: inout T) {
     let c = a
     a = b
     b = c