Merge branch 'master' of https://github.com/bordoley/SQLitePCL.pretty

Author: bordoley

README.md

@@ -111,88 +111,122 @@ SQLitePCL.pretty has a very simple table mapping ORM, available in the SQLitePCL
 
 ```CSharp
 
-    public void Example()
+// Per thread builder to limit the number of instances.
+private static readonly ThreadLocal<TestObject.Builder> testObjectBuilder = new 
+        ThreadLocal<TestObject.Builder>(() => new TestObject.Builder());
+
+public void Example()
+{
+    // You must provide a result selector to convert a result set row into an object.
+    // By making this an explicit parameter, SQLitePCL.pretty can support immutable object builders.
+    var resultSelector = 
+        ResultSet.RowToObject(
+            () => testObjectBuilder.Value, 
+            o => ((TestObject.Builder)o).Build());
+
+    using (var db = SQLite3.OpenInMemory())
     {
-        var table = TableMapping.Create<TestObject>(
-                        () => testObjectBuilder.Value, 
-                        o => ((TestObject.Builder)o).Build());
+        // Creates the table and indexes if they do not yet exist.
+        db.InitTable<TestObject>();
+
+        // Insert a new object into the database that has nullable values.
+        // InsertOrReplace returns the resulting object in the database along with
+        // its new primary key and any default values assigned by the database.
+        var inserted = 
+            db.InsertOrReplace(
+                new TestObject.Builder() { Value = "Hello" }.Build(), 
+                resultSelector);
+
+        // Lookup the object in the database.
+        TestObject found;
+        if (!db.TryFind(inserted.Id.Value, resultSelector, out found))
+        {
+            throw new Exception("item not found");
+        }
 
-        using (var db = SQLite3.OpenInMemory())
+        // We can use linq like syntax to write queries against the database.
+        var query = 
+            SqlQuery.From<TestObject>()
+                    .Select()
+                    // This creates a named bind parameter ":value"
+                    .Where<string>((x, value) => x.Value.Contains(value))
+                    .OrderBy(x => x.Value)
+                    .Take(100)
+                    .Skip(0);
+
+        using (var stmt = db.PrepareStatement(query))
         {
-            db.InitTable(table);
-
-            var inserted = db.InsertOrReplace(table, new TestObject.Builder() { Value = "Hello" }.Build());
-            
-            TestObject found;
-            if (!db.TryFind(table, inserted.Id, out found))
-            {
-                throw new Exception("item not found");
-            }
-            
-            TestObject deleted;
-            if (!db.TryDelete(table, inserted.Id, out deleted))
-            {
-                throw new Exception("deletion failed");
-            }
+            stmt.BindParameters[":value"].Bind("ell");
+            // This will throw if no results are returned
+            stmt.Query().First();
+        }
+
+        // Delete the object from the database.
+        TestObject deleted;
+        if (!db.TryDelete(inserted.Id.Value, resultSelector, out deleted))
+        {
+            throw new Exception("deletion failed");
         }
     }
+}
 
-    // Per thread builder to limit the number of instances.
-    private static readonly ThreadLocal<TestObject.Builder> testObjectBuilder = new 
-            ThreadLocal<TestObject.Builder>(() => new TestObject.Builder());
 
-    public sealed class TestObject : IEquatable<TestObject>
+public sealed class TestObject : IEquatable<TestObject>
+{
+    public class Builder
     {
-        public class Builder
-        {
-            private long? id;
-            private string value;
+        private long? id;
+        private string value;
 
-            public long? Id { get { return id; } set { this.id = value; } }
-            public string Value { get { return value; } set { this.value = value; } }
+        public long? Id { get { return id; } set { this.id = value; } }
+        public string Value { get { return value; } set { this.value = value; } }
 
-            public TestObject Build()
-            {
-                return new TestObject(id, value);
-            }
+        public TestObject Build()
+        {
+            return new TestObject(id, value);
         }
+    }
 
-        private long? id;
-        private string value; 
+    private long? id;
+    private string value; 
 
-        private TestObject(long? id, string value)
-        {
-            this.id = id;
-            this.value = value;
-        }
+    private TestObject(long? id, string value)
+    {
+        this.id = id;
+        this.value = value;
+    }
 
-        [PrimaryKey]
-        public long? Id { get { return id; } }
+    [PrimaryKey]
+    public long? Id { get { return id; } }
 
-        public string Value { get { return value; } }
+    public string Value { get { return value; } }
 
-        public bool Equals(TestObject other)
-        {
-            return this.Id == other.Id && 
-                this.Value == other.Value;
-        }
+    public bool Equals(TestObject other)
+    {
+        return this.Id == other.Id && 
+            this.Value == other.Value;
+    }
 
-        public override bool Equals(object other)
-        {
-            return other is TestObject && this.Equals((TestObject)other);
-        }
+    public override bool Equals(object other)
+    {
+        return other is TestObject && this.Equals((TestObject)other);
+    }
 
-        public override int GetHashCode()
-        {
-            int hash = 17;
-            hash = hash * 31 + this.Id.GetHashCode();
-            hash = hash * 31 + this.Value.GetHashCode();
+    public override int GetHashCode()
+    {
+        int hash = 17;
+        hash = hash * 31 + this.Id.GetHashCode();
+        hash = hash * 31 + this.Value.GetHashCode();
 
-            return hash;
-        }
+        return hash;
     }
+}
 ```
 
+# I'm getting crashes due to EntryPointNotFoundExceptions
+
+SQLite has continued to have active developement over the past few years. Unfortunately both Apple and Google aren't paying attention and have continued to ship ancient versions. SQLitePCL.raw includes optional DLLs that can be included in your application that also include a statically linked recent version of SQLite. You should use these instead, as SQLitePCL.pretty is dependent upon many modern SQLite features.
+
 # How does this compare to...
 ## [SQLitePCL.raw](https://github.com/ericsink/SQLitePCL.raw)
 
@@ -209,4 +243,4 @@ SQLitePCL is the original PCL library release by MSOpenTech. Stylistically, this
 
 ## [SQLite-Net](https://github.com/praeclarum/sqlite-net)
 
-SQLite-Net provides an ORM similar to the one provided by SQLitePCL.pretty to manipulate database objects. The most notable difference, is that SQLite-Net supports linq based querying of a database which is not yet supported (maybe never) by SQLitePCL.pretty. On the converse, SQLitePCL.pretty is more friendly to functional programmers who want to persist immutable objects to a SQLite database.
+SQLite-Net provides an ORM similar to the one provided by SQLitePCL.pretty to manipulate database objects. SQLite-NET is exceptionally well tested in the wild, and should generally be your default choice when being conservative. On the converse, SQLitePCL.pretty has extensive unit test coverage and supports many newer features available in more recent SQLite versions.