Simplify query change interface

The fact that `insert()`, `update()`, and `delete()` have a number of
overloads that can only be disambiguated by specifying a type, a tuple
member, or `!` is a big point of confusion for new users of
SQLite.swift. The overloads add some interesting patterns to the mix,
but aren't worth the pain points.

If we eliminate the overloads, we can insert/update/delete in place.
This allows for subtle bugs to be introduced into apps (where the
developer doesn't check for a rowid or that an update/delete was
successful), but is a tradeoff we'll have to make. It doesn't make sense
to enforce a different kind of interface/access at the expense of
confusion.

Given:

    let user = email <- "[email protected]")

The old way:

    users.insert(user)!
    let rowid = users.insert(user)!
    if let rowid = users.insert(user) { /* ... */ }
    let (rowid, statement) = users.insert(user)
    // etc.

The new way:

    users.insert(user)
    let rowid = users.insert(user).rowid!
    if let rowid = users.insert(user).rowid { /* ... */ }
    let (rowid, statement) = users.insert(user)
    // etc.

Slightly and rarely more verbose and readable, with less confusing
compiler errors and hand-holding.

Signed-off-by: Stephen Celis <[email protected]>

Author: stephencelis

Documentation/Index.md

@@ -393,62 +393,33 @@ Additional constraints may be provided outside the scope of a single column usin
 
 ## Inserting Rows
 
-We can insert rows into a table by calling a [query’s](#queries) `insert` function with a list of [setters](#setters), typically [typed column expressions](#expressions) and values (which can also be expressions), each joined by the `<-` operator.
+We can insert rows into a table by calling a [query’s](#queries) `insert` function with a list of [setters](#setters)—typically [typed column expressions](#expressions) and values (which can also be expressions)—each joined by the `<-` operator.
 
 ``` swift
-users.insert(email <- "[email protected]", name <- "Alice")?
+users.insert(email <- "[email protected]", name <- "Alice")
 // INSERT INTO "users" ("email", "name") VALUES ('[email protected]', 'Alice')
 
 users.insert(or: .Replace, email <- "[email protected]", name <- "Alice B.")
 // INSERT OR REPLACE INTO "users" ("email", "name") VALUES ('[email protected]', 'Alice B.')
 ```
 
-The `insert` function can return several different types that are useful in different contexts.
+The `insert` function returns a tuple with an `Int64?` representing the inserted row’s [`ROWID`][ROWID] (or `nil` on failure) and the associated `Statement`.
 
-  - An `Int64?` representing the inserted row’s [`ROWID`][ROWID] (or `nil` on failure), for simplicity.
-
-    ``` swift
-    if let insertId = users.insert(email <- "[email protected]") {
-        println("inserted id: \(insertId)")
-    }
-    ```
-
-    If a value is always expected, we can disambiguate with a `!`.
-
-    ``` swift
-    users.insert(email <- "[email protected]")!
-    ```
-
-  - A `Statement`, for [the transaction and savepoint helpers](#transactions-and-savepoints) that take a list of statements.
-
-    ``` swift
-    db.transaction()
-        && users.insert(email <- "[email protected]")
-        && users.insert(email <- "[email protected]")
-        && db.commit() || db.rollback()
-    // BEGIN DEFERRED TRANSACTION;
-    // INSERT INTO "users" ("email") VALUES ('[email protected]');
-    // INSERT INTO "users" ("email") VALUES ('[email protected]');
-    // COMMIT TRANSACTION;
-    ```
-
-  - A tuple of the above [`ROWID`][ROWID] and statement: `(rowid: Int64?, statement: Statement)`, for flexibility.
-
-    ``` swift
-    let (rowid, statement) = users.insert(email <- "[email protected]")
-    if let rowid = rowid {
-        println("inserted id: \(rowid)")
-    } else if statement.failed {
-        println("insertion failed: \(statement.reason)")
-    }
-    ```
+``` swift
+let insert = users.insert(email <- "[email protected]")
+if let rowid = insert.rowid {
+    println("inserted id: \(rowid)")
+} else if insert.statement.failed {
+    println("insertion failed: \(insert.statement.reason)")
+}
+```
 
 The [`update`](#updating-rows) and [`delete`](#deleting-rows) functions follow similar patterns.
 
 > _Note:_ If `insert` is called without any arguments, the statement will run with a `DEFAULT VALUES` clause. The table must not have any constraints that aren’t fulfilled by default values.
 >
 > ``` swift
-> timestamps.insert()!
+> timestamps.insert()
 > // INSERT INTO "timestamps" DEFAULT VALUES
 > ```
 
@@ -816,42 +787,33 @@ users.filter(name != nil).count
 
 ## Updating Rows
 
-We can update a table’s rows by calling a [query’s](#queries) `update` function with a list of [setters](#setters), typically [typed column expressions](#expressions) and values (which can also be expressions), each joined by the `<-` operator.
+We can update a table’s rows by calling a [query’s](#queries) `update` function with a list of [setters](#setters)—typically [typed column expressions](#expressions) and values (which can also be expressions)—each joined by the `<-` operator.
 
 When an unscoped query calls `update`, it will update _every_ row in the table.
 
 ``` swift
-users.update(email <- "[email protected]")?
+users.update(email <- "[email protected]")
 // UPDATE "users" SET "email" = '[email protected]'
 ```
 
 Be sure to scope `UPDATE` statements beforehand using [the `filter` function](#filtering-rows).
 
 ``` swift
 let alice = users.filter(id == 1)
-alice.update(email <- "[email protected]")?
+alice.update(email <- "[email protected]")
 // UPDATE "users" SET "email" = '[email protected]' WHERE ("id" = 1)
 ```
 
-Like [`insert`](#inserting-rows) (and [`delete`](#updating-rows)), `update` can return several different types that are useful in different contexts.
-
-  - An `Int?` representing the number of updated rows (or `nil` on failure), for simplicity.
-
-    ``` swift
-    if alice.update(email <- "[email protected]") > 0 {
-        println("updated Alice")
-    }
-    ```
+The `update` function returns a tuple with an `Int?` representing the number of updates (or `nil` on failure) and the associated `Statement`.
 
-    If a value is always expected, we can disambiguate with a `!`.
-
-    ``` swift
-    alice.update(email <- "[email protected]")!
-    ```
-
-  - A `Statement`, for [the transaction and savepoint helpers](#transactions-and-savepoints) that take a list of statements.
-
-  - A tuple of the above number of updated rows and statement: `(changes: Int?, Statement)`, for flexibility.
+``` swift
+let update = alice.update(email <- "[email protected]")
+if let changes = update.changes where changes > 0 {
+    println("updated alice")
+} else if update.statement.failed {
+    println("update failed: \(update.statement.reason)")
+}
+```
 
 
 ## Deleting Rows
@@ -861,42 +823,33 @@ We can delete rows from a table by calling a [query’s](#queries) `delete` func
 When an unscoped query calls `delete`, it will delete _every_ row in the table.
 
 ``` swift
-users.delete()?
+users.delete()
 // DELETE FROM "users"
 ```
 
 Be sure to scope `DELETE` statements beforehand using [the `filter` function](#filtering-rows).
 
 ``` swift
 let alice = users.filter(id == 1)
-alice.delete()?
+alice.delete()
 // DELETE FROM "users" WHERE ("id" = 1)
 ```
 
-Like [`insert`](#inserting-rows) and [`update`](#updating-rows), `delete` can return several different types that are useful in different contexts.
-
-  - An `Int?` representing the number of deleted rows (or `nil` on failure), for simplicity.
-
-    ``` swift
-    if alice.delete() > 0 {
-        println("deleted Alice")
-    }
-    ```
-
-    If a value is always expected, we can disambiguate with a `!`.
-
-    ``` swift
-    alice.delete()!
-    ```
-
-  - A `Statement`, for [the transaction and savepoint helpers](#transactions-and-savepoints) that take a list of statements.
+The `delete` function returns a tuple with an `Int?` representing the number of deletes (or `nil` on failure) and the associated `Statement`.
 
-  - A tuple of the above number of deleted rows and statement: `(changes: Int?, Statement)`, for flexibility.
+``` swift
+let delete = delete.update(email <- "[email protected]")
+if let changes = delete.changes where changes > 0 {
+    println("deleted alice")
+} else if delete.statement.failed {
+    println("delete failed: \(delete.statement.reason)")
+}
+```
 
 
 ## Transactions and Savepoints
 
-Using the `transaction` and `savepoint` functions, we can run a series of statements, committing the changes to the database if they all succeed. If a single statement fails, we can bail out early and roll back.
+Using the `transaction` and `savepoint` functions, we can run a series of statements chained together (using `&&`). If a single statement fails, we can short-circuit the series (using `||`) and roll back the changes.
 
 ``` swift
 db.transaction()
@@ -905,18 +858,21 @@ db.transaction()
     && db.commit() || db.rollback()
 ```
 
-The former statement can also be written as
+> _Note:_ Each statement is captured in an auto-closure and won’t execute till the preceding statement succeeds. This is why we can use the `lastInsertRowid` property on `Database` to reference the previous statement’s insert [`ROWID`][ROWID].
+
+For more complex transactions and savepoints, block helpers exist. Using a block helper, the former statement can be written (more verbosely) as follows:
+
 ``` swift
-db.transaction { _ in
-    for obj in objects {
-        stmt.run(obj.email)
+db.transaction { txn in
+    if let rowid = users.insert(email <- "[email protected]").rowid {
+        if users.insert(email <- "[email protected]", manager_id <- db.lastInsertRowid).rowid != nil {
+            return .Commit
+        }
     }
-    return .Commit || .Rollback
+    return .Rollback
 }
 ```
 
-> _Note:_ Each statement is captured in an auto-closure and won’t execute till the preceding statement succeeds. This means we can use the `lastInsertRowid` property on `Database` to reference the previous statement’s insert [`ROWID`][ROWID].
-
 
 ## Altering the Schema