README.md in nano-store-0.6.0

- old
+ new

@@ -1,6 +1,7 @@
 # Welcome To NanoStore
+-
 
 **What is NanoStore?**
 
 NanoStore is an open source, lightweight schema-less local key-value document store written in Objective-C for Mac OS X and iOS.
 
@@ -20,11 +21,20 @@
 * Full SQLite access available
 * Mac OS X Lion 10.7 and iOS 5 ready
 * iOS library runs on the device and simulator
 * ARC compliant
 
+# Latest changes
+-
+v2.5 - January 1, 2013
+
+* Starting with v2.5, the plist mechanism has been replaced with NSKeyedArchiver. There are several reasons for it: it's more compact, faster and uses less memory. Perhaps the most important reason is that it opens the possibility to store other data types.
+
+* NSNull is now supported. Big thanks to Wanny (https://github.com/mrwanny) for taking the time to improve this section of NanoStore.
+
 # Installation
+-
 
 Building NanoStore is very easy. Just follow these steps:
 
     1) Download NanoStore
     2) Open the NanoStore.xcodeproj file
@@ -62,10 +72,11 @@
 	2) Select the MyDemoApp target
 	3) Expand the Target Dependencies box
 	4) Click "+" and add NanoStore
 					
 # How does NanoStore work?
+-
 
 The basic unit of data in NanoStore is called NanoObject. A NanoObject is any object which conforms to the `NSFNanoObjectProtocol` protocol.
 
 At its core, a NanoObject is nothing more than a wrapper around two properties:
 
@@ -102,10 +113,11 @@
 	App B retrieves the object, but since it doesn't know anything about the class Car, NanoStore returns a NSFNanoObject.
 	App B updates the object, with additional information. NanoStore saves it as a Car, not as a NSFNanoObject.
 	App A retrieves the updated object as a Car object, in exactly the same format as it was originally stored.
 
 # Types of Document Stores
+-
 
 There are three types of document stores available in NanoStore: in-memory, temporary and file-based. These document stores are defined by the `NSFNanoStoreType` type:
 
 `NSFMemoryStoreType`
 
@@ -165,10 +177,11 @@
 
 ### Note
 	Check the section Performance Tips below for important information about how to get the most out of NanoStore.
 
 # Working with a NanoObject
+-
 
 There are three basic operations that NanoStore can perform with a NanoObject:
 
 * Add it to the document store
 * Update an existing object in the document store
@@ -246,20 +259,22 @@
     
     // ... or you could pass the key instead
     [nanoStore removeObjectsWithKeysInArray:[NSArray arrayWithObject:[object nanoObjectKey]] error:nil];
 
 # It's not a flat World
+-
 
 Most database solutions force the developer to think in a two-dimensional space (rows and columns), forcing the developer to plan the schema ahead of time. This situation is not ideal because in most cases schema refinements could be required, oftentimes impacting the code as well.
 
 NanoStore goes beyond that allowing the developer to store objects in their natural form. These objects must conform to the `NSFNanoObjectProtocol` protocol, providing NanoStore with the NSDictionary that will be stored. By using a dictionary data can be inspected very quickly, and it also allows the structure to be defined in a hierarchical fashion as well, due to the fact that it includes support for nested collections (of type NSDictionary and NSArray.) Each inner-object is indexed automatically, thus allowing to quickly find objects which contain a specific key and/or value.
 
 By default, NanoStore allows objects to be stored without any sense of relationship to other objects. This simple format, while powerful, is limited because the developer has to keep track of the relationships among objects. Some applications may need to relate objects, some of them perhaps of different nature or class type. This is exactly what NanoBag (represented by the `NSFNanoBag` class) does: it allows any object conforming to the `NSFNanoObjectProtocol` protocol to be added to the bag. By saving the bag with one single call, the new and/or modified NanoObjects are taken care of seamlessly.
 
 The `NSFNanoBag` API is rich, allowing the developer to add, remove, reload and undo its changes, deflate it (thus saving memory) and inflate it whenever it's required. In addition, it provides methods to obtain all bags, specific bags matching some keys, and bags containing a specific object (see `NSFNanoStore` for more information).
 
 # Where are my objects?
+-
 
 While `NSFNanoStore` provides some convenience methods to obtain standard objects such as bags, the bulk of the search mechanism is handled by `NSFNanoSearch`. The steps involved to perform a search are quite simple:
 
     1) Instantiate a search object
     2) Configure the search via its accessors
@@ -312,10 +327,11 @@
     search.value = @"Doe";
     
     float averageSalary = [[search aggregateOperation:NSFAverage onAttribute:@"Salary"]floatValue];
 
 # Sorting
+-
 
 Combining search and sort is an extremely easy operation. There are two simple parts:
 
     1) Preparing your classes for sorting
     2) Setup a search operation and set its sort descriptors
@@ -367,11 +383,42 @@
     NSArray *searchResults = [search searchObjectsWithReturnType:NSFReturnObjects error:nil];
     
     // Cleanup
     [sortByLastName release];
 
+# Paging using Limit and Offset
+-
+
+SQLite provides a really cool feature called OFFSET that is usually used with a LIMIT clause.
+
+The LIMIT clause is used to limit the number of results returned in a SQL statement. So if you have 1000 rows in a table, but only want to return the first 10, you would do something like this:
+
+    SELECT column FROM table LIMIT 10
+
+Now suppose you wanted to show results 11-20. With the OFFSET keyword it's just as easy. The following query will do:
+
+    SELECT column FROM table LIMIT 10 OFFSET 10
+
+Using pagination is also quite easy with NanoStore. This example based on one of the unit tests provided with the NanoStore distro:
+
+	NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
+    
+	// Assume we have added objects to the store
+    
+	NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
+	search.value = @"Barcelona";
+	search.match = NSFEqualTo;
+	search.limit = 5;
+	search.offset = 3;
+    
+	NSDictionary *searchResults = [search searchObjectsWithReturnType:NSFReturnObjects error:nil];
+
+	// Assuming the query matches some results, NanoStore should have retrieved
+	// the first 5 records right after the 3rd one from the result set.
+
 # Performance Tips
+-
 
 NanoStore by defaults saves every object to disk one by one. To speed up inserts and edited objects, increase NSFNanoStore's `saveInterval` property.
 
 ### Example
 
@@ -399,17 +446,19 @@
 ### Warning
 	Setting saveInterval to a large number could result in decreased performance because SQLite's would have to spend more
 	time reading the journal file and writing the changes to the store.
 
 # Need more help?
+-
 
 There are two quick ways to find answers: reading the documentation and browsing the Unit tests.
 
 While several attempts have been made to make the documentation easy to read and understand, it's far from perfect. If you find that the documentation is incomplete, incorrect or needs some clarification, please file a bug. I'll appreciate it and correct it as soon as possible:
 
 * NanoStore Documentation: http://dl.dropbox.com/u/2601212/NanoStore%202.0/html/index.html
 * NanoStore Bug Tracker: https://github.com/tciuro/NanoStore/issues
 * Twitter: http://twitter.com/nanostoredev
 
 # Official Source Repository
+-
 
 The official repository for NanoStore is hosted on GitHub: https://github.com/tciuro/NanoStore
\ No newline at end of file