nano-store 0.3.8 → 0.3.9

data/vendor/NanoStore/Classes/Public/NSFNanoObjectProtocol.h

@@ -1,119 +0,0 @@
-/*
-     NSFNanoObjectProtocol.h
-     NanoStore
-     
-     Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
-     
-     Redistribution and use in source and binary forms, with or without modification, are permitted
-     provided that the following conditions are met:
-     
-     * Redistributions of source code must retain the above copyright notice, this list of conditions
-     and the following disclaimer.
-     * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
-     and the following disclaimer in the documentation and/or other materials provided with the distribution.
-     * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
-     products derived from this software without specific prior written permission.
-     
-     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
-     WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-     PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
-     DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-     PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-     OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-     SUCH DAMAGE.
- */
-
-/*! @file NSFNanoObjectProtocol.h
- @brief A protocol declaring the interface that objects interfacing with NanoStore must implement.
- */
-
-/** @protocol NSFNanoObjectProtocol
- * A protocol declaring the interface that objects interfacing with NanoStore must implement.
- *
- * @note
- * Check NSFNanoBag or NSFNanoObject to see a concrete example of how NSFNanoObjectProtocol is implemented.
- */
-
-@class NSFNanoStore;
-
-@protocol NSFNanoObjectProtocol
-
-@required
-
-/** * Initializes a newly allocated object containing a given key and value associated with a document store.
- * @param theDictionary the information associated with the object.
- * @param aKey the key associated with the information.
- * @param theStore the document store where the object is stored.
- * @return An initialized object upon success, nil otherwise.
- * @details <b>Example:</b>
- @code
- - (id)initNanoObjectFromDictionaryRepresentation:(NSDictionary *)aDictionary forKey:(NSString *)aKey store:(NSFNanoStore *)aStore
- {
-    if (self = [self init]) {
-      info = [aDictionary retain];
-      key = [aKey copy];
-    }
- 
-    return self;
- }
- @endcode
- */
-
-- (id)initNanoObjectFromDictionaryRepresentation:(NSDictionary *)theDictionary forKey:(NSString *)aKey store:(NSFNanoStore *)theStore;
-
-/** * Returns a dictionary that contains the information stored in the object.
- * @see \link nanoObjectKey - (NSString *)nanoObjectKey \endlink
- */
-
-- (NSDictionary *)nanoObjectDictionaryRepresentation;
-
-/** * Returns the key associated with the object.
- * @note
- * The class NSFNanoEngine contains a convenience method for this purpose: \ref NSFNanoEngine::stringWithUUID "+(NSString*)stringWithUUID"
- *
- * @see \link nanoObjectDictionaryRepresentation - (NSDictionary *)nanoObjectDictionaryRepresentation \endlink
- */
-
-- (NSString *)nanoObjectKey;
-
-/** * Returns a reference to the object holding the private data or information that will be used for sorting.
- * Most custom objects will return <i>self</i>, as is the case for NSFNanoBag. Since we can sort a bag by <i>name</i>, <i>key</i> or <i>hasUnsavedChanges</i>,
- * NanoStore requires a hint to find the attribute. This hint is the root object, which KVC uses to perform the sort. Taking NSFNanoBag as an example:
- @code
- @interface NSFNanoBag : NSObject <NSFNanoObjectProtocol, NSCopying>
- {
-    NSFNanoStore            *store;
-    NSString                *name;
-    NSString                *key;
-    BOOL                    hasUnsavedChanges;
-}
- @endcode
- * The implementation of <i>rootObject</i> would look like so:
- @code
- - (id)rootObject
- {
-    return self;
- }
- @endcode
- * Other objects may point directly to the collection that holds the information. NSFNanoObject stores all its data in the <i>info</i> dictionary, so the
- * implementation looks like this:
- @code
- - (id)rootObject
- {
-    return info;
- }
- @endcode
- * Assuming that <i>info</i> contains a key named <i>City</i>, we would specify a NSFNanoSortDescriptor which would sort the cities like so:
- @code
- NSFNanoSortDescriptor *sortedCities = [[NSFNanoSortDescriptor alloc]initWithAttribute:@"City" ascending:YES];
- @endcode
- * If we had returned <i>self</i> as the root object, the sort descriptor would have to be written like so:
- @code
- NSFNanoSortDescriptor *sortedCities = [[NSFNanoSortDescriptor alloc]initWithAttribute:@"info.City" ascending:YES];
- @endcode
- */
-
-- (id)rootObject;
-
-@end

data/vendor/NanoStore/Classes/Public/NSFNanoPredicate.h

@@ -1,123 +0,0 @@
-/*
-     NSFNanoPredicate.h
-     NanoStore
-     
-     Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
-     
-     Redistribution and use in source and binary forms, with or without modification, are permitted
-     provided that the following conditions are met:
-     
-     * Redistributions of source code must retain the above copyright notice, this list of conditions
-     and the following disclaimer.
-     * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
-     and the following disclaimer in the documentation and/or other materials provided with the distribution.
-     * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
-     products derived from this software without specific prior written permission.
-     
-     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
-     WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-     PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
-     DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-     PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-     OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-     SUCH DAMAGE.
- */
-
-/*! @file NSFNanoPredicate.h
- @brief A predicate is an element of an expression used to perform complex queries.
- */
-
-/** @class NSFNanoPredicate
- * A predicate is an element of an expression used to perform complex queries.
- *
- * @note
- * A predicate must be added to a NSFNanoExpression.
- *
- * @details <b>Example:</b>
- @code
- // Instantiate a NanoStore and open it
- NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
- 
- // Add some data to the document store
- NSDictionary *info = ...;
- NSFNanoObject *object = [NSFNanoObject nanoObjectWithDictionary:info];
- [nanoStore addObject:object error:nil];
- 
- // Prepare the expression
- NSFNanoPredicate *attribute = [NSFNanoPredicate predicateWithColumn:NSFAttributeColumn matching:NSFEqualTo value:@"FirstName"];
- NSFNanoPredicate *value = [NSFNanoPredicate predicateWithColumn:NSFValueColumn matching:NSFEqualTo value:@"Hobbes"];
- NSFNanoExpression *expression = [NSFNanoExpression expressionWithPredicate:predicateAttribute];
- [expression addPredicate:predicateValue withOperator:NSFAnd];
- 
- // Setup the search with the document store and a given expression
- NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
- [search setExpressions:[NSArray arrayWithObject:expression]];
- 
- // Obtain the matching objects
- NSDictionary *searchResults = [search searchObjectsWithReturnType:NSFReturnObjects error:nil];
- 
- // Close the document store
- [nanoStore closeWithError:nil];
- @endcode
- *
- * @see \link NSFNanoExpression::expressionWithPredicate: + (NSFNanoExpression*)expressionWithPredicate:(NSFNanoPredicate *)thePredicate \endlink
- * @see \link NSFNanoExpression::initWithPredicate: - (id)initWithPredicate:(NSFNanoPredicate *)thePredicate \endlink
- * @see \link NSFNanoExpression::addPredicate:withOperator: - (void)addPredicate:(NSFNanoPredicate *)thePredicate withOperator:(NSFOperator)theOperator \endlink
- */
-
-#import <Foundation/Foundation.h>
-
-#import "NSFNanoGlobals.h"
-
-@interface NSFNanoPredicate : NSObject
-
-/** * The type of column being referenced. */
-@property (nonatomic, assign, readonly) NSFTableColumnType column;
-/** * The comparison operator to be used. */
-@property (nonatomic, assign, readonly) NSFMatchType match;
-/** * The value to be used for comparison.  */
-@property (nonatomic, copy, readonly) NSString *value;
-
-/** @name Creating and Initializing a Predicate
- */
-
-//@{
-
-/** * Creates and returns a predicate.
- * @param theType is the column type. Can be \link Globals::NSFKeyColumn NSFKeyColumn \endlink, \link Globals::NSFAttributeColumn NSFAttributeColumn \endlink or \link Globals::NSFValueColumn NSFValueColumn \endlink.
- * @param theMatch is the match operator.
- * @param theValue is the value.
- * @return A predicate which can be used in an NSFNanoExpression.
- * @see \link initWithColumn:matching:value: - (id)initWithColumn:(NSFTableColumnType)theType matching:(NSFMatchType)theMatch value:(NSString *)theValue \endlink
- */
-
-+ (NSFNanoPredicate*)predicateWithColumn:(NSFTableColumnType)theType matching:(NSFMatchType)theMatch value:(NSString *)theValue;
-
-/** * Initializes a newly allocated predicate.
- * @param theType is the column type. Can be \link Globals::NSFKeyColumn NSFKeyColumn \endlink, \link Globals::NSFAttributeColumn NSFAttributeColumn \endlink or \link Globals::NSFValueColumn NSFValueColumn \endlink.
- * @param theMatch is the match operator.
- * @param theValue is the value.
- * @return A predicate which can be used in an NSFNanoExpression.
- * @see \link predicateWithColumn:matching:value: + (NSFNanoPredicate*)predicateWithColumn:(NSFTableColumnType)theType matching:(NSFMatchType)theMatch value:(NSString *)theValue \endlink
- */
-
-- (id)initWithColumn:(NSFTableColumnType)theType matching:(NSFMatchType)theMatch value:(NSString *)theValue;
-
-//@}
-
-/** @name Miscellaneous
- */
-
-//@{
-
-/** * Returns a string representation of the predicate.
- * @note Check properties column, match and value to find out the current state of the predicate.
- * @see \link description - (NSString *)description \endlink
- */
-
-- (NSString *)description;
-
-//@}
-
-@end

data/vendor/NanoStore/Classes/Public/NSFNanoPredicate.m

@@ -1,130 +0,0 @@
-/*
-     NSFNanoExpression.m
-     NanoStore
-     
-     Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
-     
-     Redistribution and use in source and binary forms, with or without modification, are permitted
-     provided that the following conditions are met:
-     
-     * Redistributions of source code must retain the above copyright notice, this list of conditions
-     and the following disclaimer.
-     * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
-     and the following disclaimer in the documentation and/or other materials provided with the distribution.
-     * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
-     products derived from this software without specific prior written permission.
-     
-     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
-     WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-     PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
-     DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-     PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-     OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-     SUCH DAMAGE.
- */
-
-#import "NSFNanoExpression.h"
-#import "NanoStore_Private.h"
-
-@implementation NSFNanoPredicate
-
-@synthesize column, match, value;
-
-// ----------------------------------------------
-// Initialization / Cleanup
-// ----------------------------------------------
-
-+ (NSFNanoPredicate*)predicateWithColumn:(NSFTableColumnType)type matching:(NSFMatchType)matching value:(NSString *)aValue
-{
-    if (nil == aValue)
-        [[NSException exceptionWithName:NSFUnexpectedParameterException
-                                 reason:[NSString stringWithFormat:@"*** -[%@ %s]: value is nil.", [self class], _cmd]
-                               userInfo:nil]raise];
-    
-    return [[self alloc]initWithColumn:type matching:matching value:aValue];
-}
-
-- (id)initWithColumn:(NSFTableColumnType)type matching:(NSFMatchType)matching value:(NSString *)aValue
-{
-    if (nil == aValue)
-        [[NSException exceptionWithName:NSFUnexpectedParameterException
-                                 reason:[NSString stringWithFormat:@"*** -[%@ %s]: value is nil.", [self class], _cmd]
-                               userInfo:nil]raise];
-    
-    if ((self = [super init])) {
-        column = type;
-        match = matching;
-        value = aValue;
-    }
-    
-    return self;
-}
-
-- (NSString *)description
-{
-    NSMutableString *description = [NSMutableString string];
-    NSMutableString *mutatedString = nil;
-    NSInteger mutatedStringLength = 0;
-    NSString *columnValue = nil;
-    
-    switch (column) {
-        case NSFKeyColumn:
-            columnValue = NSFKey;
-            break;
-        case NSFAttributeColumn:
-            columnValue = NSFAttribute;
-            break;
-        default:
-            columnValue = NSFValue;
-            break;
-    }
-    
-    switch (match) {
-        case NSFEqualTo:
-            [description appendString:[NSString stringWithFormat:@"%@ = '%@'", columnValue, value]];
-            break;
-        case NSFBeginsWith:
-            mutatedString = [NSMutableString stringWithString:value];
-            mutatedStringLength = [value length];
-            [mutatedString replaceCharactersInRange:NSMakeRange(mutatedStringLength - 1, 1) withString:[NSString stringWithFormat:@"%c", [mutatedString characterAtIndex:mutatedStringLength - 1]+1]];
-            [description appendString:[NSString stringWithFormat:@"(%@ >= '%@' AND %@ < '%@')", columnValue, value, columnValue, mutatedString]];
-            break;
-        case NSFContains:
-            [description appendString:[NSString stringWithFormat:@"%@ GLOB '*%@*'", columnValue, value]];
-            break;
-        case NSFEndsWith:
-            [description appendString:[NSString stringWithFormat:@"%@ GLOB '*%@'", columnValue, value]];
-            break;
-        case NSFInsensitiveEqualTo:
-            [description appendString:[NSString stringWithFormat:@"upper(%@) = '%@'", columnValue, [value uppercaseString]]];
-            break;
-        case NSFInsensitiveBeginsWith:
-            mutatedString = [NSMutableString stringWithString:value];
-            mutatedStringLength = [value length];
-            [mutatedString replaceCharactersInRange:NSMakeRange(mutatedStringLength - 1, 1) withString:[NSString stringWithFormat:@"%c", [mutatedString characterAtIndex:mutatedStringLength - 1]+1]];
-            [description appendString:[NSString stringWithFormat:@"(upper(%@) >= '%@' AND upper(%@) < '%@')", columnValue, [value uppercaseString], columnValue, [mutatedString uppercaseString]]];
-            break;
-        case NSFInsensitiveContains:
-            [description appendString:[NSString stringWithFormat:@"%@ LIKE '%@%@%@'", columnValue, @"%", value, @"%"]];
-            break;
-        case NSFInsensitiveEndsWith:
-            [description appendString:[NSString stringWithFormat:@"%@ LIKE '%@%@'", columnValue, @"%", value]];
-            break;
-        case NSFGreaterThan:
-            [description appendString:[NSString stringWithFormat:@"%@ > '%@'", columnValue, value]];
-            break;
-        case NSFLessThan:
-            [description appendString:[NSString stringWithFormat:@"%@ < '%@'", columnValue, value]];
-            break;
-    }
-    
-    return description;
-}
-
-/** \cond */
-
-
-/** \endcond */
-
-@end

data/vendor/NanoStore/Classes/Public/NSFNanoSearch.h

@@ -1,381 +0,0 @@
-/*
-     NSFNanoSearch.h
-     NanoStore
-     
-     Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
-     
-     Redistribution and use in source and binary forms, with or without modification, are permitted
-     provided that the following conditions are met:
-     
-     * Redistributions of source code must retain the above copyright notice, this list of conditions
-     and the following disclaimer.
-     * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
-     and the following disclaimer in the documentation and/or other materials provided with the distribution.
-     * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
-     products derived from this software without specific prior written permission.
-     
-     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
-     WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-     PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
-     DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-     PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-     OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-     SUCH DAMAGE.
- */
-
-/*! @file NSFNanoSearch.h
- @brief A unit that provides an API to retrieve data from the document store.
- */
-
-/** @class NSFNanoSearch
- * A unit that provides an API to retrieve data from the document store.
- *
- * The search can be conducted in two ways: programatically via setters or by providing a SQL statement. In both cases,
- * it's necessary to indicate which object type should be returned. The type \link Globals::NSFReturnType NSFReturnType \endlink provides two options: \link Globals::NSFReturnObjects NSFReturnObjects \endlink and \link Globals::NSFReturnKeys NSFReturnKeys \endlink.
- *
- *           -  \link Globals::NSFReturnObjects NSFReturnObjects \endlink will return a dictionary with the key of the NanoObject (key) and the NanoObject itself (value).
- *           -  \link Globals::NSFReturnKeys NSFReturnKeys \endlink will return an array of NanoObjects.
- *
- * @par <b>Some observations about retrieving data</b><br>
- * 
- * Given the following data set:
- * 
- *           - Number of dictionaries:    3.956
- *           - Number of attributes:    593.862
- * 
- * The table describing different timings to perform a simple value search (i.e. 'Barcelona') is included below, ordered from fastest to slowest:
- *
- *<table border="1" cellpadding="5">
- *<tr>
- *<th>Match type</th>
- *<th>Seconds</th>
- *</tr>
- *<tr><td>Equal to</td><td>0.295</td></tr>
- *<tr><td>Begins with</td><td>0.295</td></tr>
- *<tr><td>Contains</td><td>1.295</td></tr>
- *<tr><td>Contains (insensitive)</td><td>1.339</td></tr>
- *<tr><td>Ends with (insensitive)</td><td>1.341</td></tr>
- *<tr><td>Ends with</td><td>1.351</td></tr>
- *<tr><td>Equal to (insensitive)</td><td>1.890</td></tr>
- *<tr><td>Begins with (insensitive)</td><td>2.412</td></tr>
- *<tr><td>Greater than</td><td>18.246</td></tr>
- *<tr><td>Less than</td><td>27.677</td></tr>
- *</table>
- 
- @section wherearetheobjects_sec Where are my objects?
- 
- While NSFNanoStore provides some convenience methods to obtain standard objects (such as objects of type NSFNanoBag), 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
- - 3) Obtain the results specifying whether objects or keys should be returned (*)
- 
- (*) Request objects if you're interested in the data. Otherwise, you should request keys if you need to feed the result to another method, such as NSFNanoStore
- \link NSFNanoStore::removeObjectsWithKeysInArray:error: -(BOOL)removeObjectsWithKeysInArray:(NSArray *)theKeys error:(out NSError **)outError \endlink method.
- 
- @details <b>Example: finding all objects with the attribute 'LastName' and value 'Doe'.</b>
- @code
- NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
- 
- search.attribute = @"LastName";
- search.match = NSFEqualTo;
- search.value = @"Doe";
- 
- // Returns a dictionary with the UUID of the object (key) and the NanoObject (value).
- NSDictionary *searchResults = [search searchObjectsWithReturnType:NSFReturnObjects error:nil];
- @endcode
- 
- @details <b>Example: removing all objects with the attribute 'LastName' and value 'Doe'.</b>
- @code
- NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
- 
- search.attribute = @"LastName";
- search.match = NSFEqualTo;
- search.value = @"Doe";
- 
- // Returns an array of matching UUIDs
- NSArray *matchingKeys = [search searchObjectsWithReturnType:NSFReturnKeys error:nil];
- 
- // Remove the NanoObjects matching the selected UUIDs
- NSError *outError = nil;
- if (YES == [nanoStore removeObjectsWithKeysInArray:matchingKeys error:&outError]) {
- NSLog(@"The matching objects have been removed.");
- } else {
- NSLog(@"An error has occurred while removing the matching objects. Reason: %@", [outError localizedDescription]);
- }
- @endcode
- 
- Another cool feature is the possibility to invoke aggregated functions (count, avg, min, max and total) on the search results. Using the search snippet above,
- calculating the average salary of all people with last name equal to 'Doe' is very easy.
- 
- @details <b>Example: calculating the average salary of all objects with the attribute 'LastName' and value 'Doe'.</b>
- @code
- NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
- 
- search.attribute = @"LastName";
- search.match = NSFEqualTo;
- search.value = @"Doe";
- 
- float averageSalary = [[search aggregateOperation:NSFAverage onAttribute:@"Salary"]floatValue];
- @endcode
- 
- * @details <b>Example:</b>
- @code
- // Instantiate a NanoStore and open it
- NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
- 
- // Generate a NanoObject with a dictionary and a key
- NSString *key = @"ABC-123";
- NSDictionary *info = ...;
- NSFNanoObject *nanoObject = [NSFNanoObject nanoObjectWithDictionary:info];
- 
- // Add it to the document store
- [nanoStore addObject:nanoObject error:nil];
- 
- // Instantiate a search and specify the attribute(s) we want to search for
- NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
- search.key = key;
- 
- // Perform the search and obtain the results
- NSDictionary *searchResults = [search searchObjectsWithReturnType:NSFReturnObjects error:nil];
- 
- // Close the document store
- [nanoStore closeWithError:nil];
- @endcode
- */
-
-#import <Foundation/Foundation.h>
-
-#import "NSFNanoGlobals.h"
-
-@class NSFNanoStore, NSFNanoResult;
-
-@interface NSFNanoSearch : NSObject
-
-/** * The document store used for searching. */
-@property (nonatomic, weak, readonly) NSFNanoStore *nanoStore;
-/** * The set of attributes to be returned on matching objects. */
-@property (nonatomic, strong, readwrite) NSArray *attributesToBeReturned;
-/** * The key used for searching. */
-@property (nonatomic, copy, readwrite) NSString *key;
-/** * The attribute used for searching. */
-@property (nonatomic, copy, readwrite) NSString *attribute;
-/** * The value used for searching. */
-@property (nonatomic, copy, readwrite) id value;
-/** * The comparison operator used for searching. */
-@property (nonatomic, assign, readwrite) NSFMatchType match;
-/** * The list of NSFNanoExpression objects used for searching. */
-@property (nonatomic, strong, readwrite) NSArray *expressions;
-/** * If set to YES, specifying NSFReturnKeys applies the DISTINCT function and groups the values. */
-@property (nonatomic, assign, readwrite) BOOL groupValues;
-/** * The SQL statement used for searching. Set when executeSQL: is invoked. */
-@property (nonatomic, copy, readonly) NSString *sql;
-/** * The sort holds an array of one or more sort descriptors of type \link NSFNanoSortDescriptor NSFNanoSortDescriptor \endlink. */
-@property (nonatomic, strong, readwrite) NSArray *sort;
-
-/** @name Creating and Initializing a Search
- */
-
-//@{
-
-/** * Creates and returns a search element for a given document store.
- * @param theNanoStore the document store where the search will be performed. Must not be nil.
- * @return An search element upon success, nil otherwise.
- * @see \link initWithStore: - (id)initWithStore:(NSFNanoStore *)theNanoStore \endlink
- */
-
-+ (NSFNanoSearch *)searchWithStore:(NSFNanoStore *)theNanoStore;
-
-/** * Initializes a newly allocated search element for a given document store.
- * @param theNanoStore the document store where the search will be performed. Must not be nil.
- * @return An search element upon success, nil otherwise.
- * @see \link searchWithStore: + (NSFNanoSearch *)searchWithStore:(NSFNanoStore *)theNanoStore \endlink
- */
-
-- (id)initWithStore:(NSFNanoStore *)theNanoStore;
-
-//@}
-
-/** @name Searching
- */
-
-//@{
-
-/** * Performs a search using the values of the properties.
- * @param theReturnType the type of object to be returned. Can be \link Globals::NSFReturnObjects NSFReturnObjects \endlink or \link Globals::NSFReturnKeys NSFReturnKeys \endlink.
- * @param outError is used if an error occurs. May be NULL.
- * @return An array is returned if: 1) the sort has been specified or 2) the return type is \link Globals::NSFReturnKeys NSFReturnKeys \endlink. Otherwise, a dictionary is returned.
- * @note The sort descriptor will be ignored when returning requesting NSFReturnKeys.
- * @see \link searchObjectsAdded:date:returnType:error: - (id)searchObjectsAdded:(NSFDateMatchType)theDateMatch date:(NSDate *)theDate returnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink
- */
-
-- (id)searchObjectsWithReturnType:(NSFReturnType)theReturnType error:(out NSError **)outError;
-
-/** * Performs a search using the values of the properties before, on or after a given date.
- * @param theDateMatch the type of date comparison. Can be \link Globals::NSFBeforeDate NSFBeforeDate \endlink, \link Globals::NSFOnDate NSFOnDate \endlink or \link Globals::NSFAfterDate NSFAfterDate \endlink.
- * @param theDate the date to use as a pivot during the search.
- * @param theReturnType the type of object to be returned. Can be \link Globals::NSFReturnObjects NSFReturnObjects \endlink or \link Globals::NSFReturnKeys NSFReturnKeys \endlink.
- * @param outError is used if an error occurs. May be NULL.
- * @return If theReturnType is \link Globals::NSFReturnObjects NSFReturnObjects \endlink, a dictionary is returned. Otherwise, an array is returned.
- * @note The sort descriptor will be ignored when returning requesting NSFReturnKeys.
- * @see \link searchObjectsWithReturnType:error: - (id)searchObjectsWithReturnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink
- */
-
-- (id)searchObjectsAdded:(NSFDateMatchType)theDateMatch date:(NSDate *)theDate returnType:(NSFReturnType)theReturnType error:(out NSError **)outError;
-
-/** * Returns the result of the aggregate function.
- * @param theFunctionType is the function type to be applied.
- * @param theAttribute is the attribute used in the function.
- * @returns An NSNumber containing the result of the aggregate function.
- * @details <b>Example:</b>
- @code
- * NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
- *
- * // Assume we have saved data to the document store
- * ...
- * ...
- *
- * // Get the average for the attribute named 'SomeNumber'
- * NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
- * NSNumber *result = [search aggregateOperation:NSFAverage onAttribute:@"SomeNumber"];
- @endcode
- @note The sort descriptor will be ignored when executing aggregate operations.
- */
-
-- (NSNumber *)aggregateOperation:(NSFAggregateFunctionType)theFunctionType onAttribute:(NSString *)theAttribute;
-
-/** * Performs a search with a given SQL statement.
- * @param theSQLStatement is the SQL statement to be executed. Must not be nil or an empty string.
- * @param theReturnType the type of object to be returned. Can be \link Globals::NSFReturnObjects NSFReturnObjects \endlink or \link Globals::NSFReturnKeys NSFReturnKeys \endlink.
- * @param outError is used if an error occurs. May be NULL.
- * @return If theReturnType is \link Globals::NSFReturnObjects NSFReturnObjects \endlink, a dictionary is returned. Otherwise, an array is returned.
- * @note
- * Use this method when performing search on NanoObjects. If you need to perform more advanced SQL statements, you may want to use
- * \link executeSQL: - (NSFNanoResult *)executeSQL:(NSString *)theSQLStatement \endlink instead.
- * @par
- * The key difference between this method and \link executeSQL: - (NSFNanoResult *)executeSQL:(NSString *)theSQLStatement \endlink is that this method performs
- * a check to make sure the columns specified match the ones required by the \link Globals::NSFReturnType NSFReturnType \endlink type selected. If the column selection is wrong,
- * NanoStore rewrites the query by specifying the right set of columns while honoring the rest of the query.
- * @details <b>Example:</b>
- * @code
- * // Prepare a document store
- * NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
- *
- * // Prepare some data and wrap it in a NanoObject
- * NSString *key = @"ABC-123";
- * NSDictionary *info = ...;
- * NSFNanoObject *nanoObject = [NSFNanoObject nanoObjectWithDictionary:info];
- *
- * // Add it to the document store
- * [nanoStore addObjectsFromArray:[NSArray arrayWithObject:nanoObject] error:nil];
- *
- * // Instantiate a search and specify the attribute(s) we want to search for
- * NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
- *
- * // Perform the search
- * // The query will be rewritten as @"SELECT NSFKey, NSFPlist, NSFObjectClass FROM NSFKeys"
- * NSDictionary *results = [search executeSQL:@"SELECT foo, bar FROM NSFKeys" returnType:NSFReturnObjects error:nil];
- * @endcode
- * @note The sort descriptor will be ignored when executing custom SQL statements.
- * @see \link executeSQL: - (NSFNanoResult *)executeSQL:(NSString *)theSQLStatement \endlink
- */
-
-- (id)executeSQL:(NSString *)theSQLStatement returnType:(NSFReturnType)theReturnType error:(out NSError **)outError;
-
-/** * Performs a search with a given SQL statement.
- * @param theSQLStatement is the SQL statement to be executed. Must not be nil or an empty string.
- * @return Returns a NSFNanoResult.
- * @note
- * Use this method when you need to perform more advanced SQL statements. If you just want to query NanoObjects using your own SQL statement,
- * you may want to use \link executeSQL:returnType:error: - (id)executeSQL:(NSString *)theSQLStatement returnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink instead.
- * @par
- * The key difference between this method and \link executeSQL:returnType:error: - (id)executeSQL:(NSString *)theSQLStatement returnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink
- * is that this method doesn't perform any check at all. The SQL statement will be sent verbatim to SQLite.
- * @details <b>Example:</b>
- * @code
- * // Prepare a document store
- * NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
- *
- * // Prepare some data and wrap it in a NanoObject
- * NSString *key = @"ABC-123";
- * NSDictionary *info = ...;
- * NSFNanoObject *nanoObject = [NSFNanoObject nanoObjectWithDictionary:info];
- *
- * // Add it to the document store
- * [nanoStore addObjectsFromArray:[NSArray arrayWithObject:nanoObject] error:nil];
- *
- * // Instantiate a search and specify the attribute(s) we want to search for
- * NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
- *
- * // Perform the search
- * NSFNanoResult *result = [search executeSQL:@"SELECT COUNT(*) FROM NSFKEYS"];
- * @endcode
- * @see \link executeSQL:returnType:error: - (id)executeSQL:(NSString *)theSQLStatement returnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink
- * @note The sort descriptor will be ignored when executing custom SQL statements.
- */
-
-- (NSFNanoResult *)executeSQL:(NSString *)theSQLStatement;
-
-/** * Performs an analysis of the given SQL statement.
- * @param theSQLStatement is the SQL statement to be analyzed. Must not be nil or an empty string.
- * @return Returns a NSFNanoResult.
- * @note
- * Returns the sequence of virtual machine instructions with high-level information about what indices would have been used if the SQL statement had
- * been executed.
- *
- * @warning
- * The analysis generated by this method is intended for interactive analysis and troubleshooting only. The details of the output format
- * are subject to change from one release of SQLite to the next. Applications should not use this method in production code since the exact behavior
- * is undocumented, unspecified, and variable.
- *
- * For additional information about SQLite's Virtual Machine Opcodes, see http://www.sqlite.org/opcode.html
- *
- * The tutorial Virtual Database Engine of SQLite is available here: http://www.sqlite.org/vdbe.html
- *
- * @details <b>Example:</b>
- * @code
- * // Prepare a document store
- * NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
- *
- * // Instantiate a search object
- * NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
- *
- * // Perform the analysis
- * NSFNanoResult *results = [search explainSQL:@"SELECT * FROM NSFValues"];
- * @endcode
- * @see \link executeSQL: - (NSFNanoResult *)executeSQL:(NSString *)theSQLStatement \endlink
- * @see \link executeSQL:returnType:error: - (id)executeSQL:(NSString *)theSQLStatement returnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink
- */
-
-- (NSFNanoResult *)explainSQL:(NSString *)theSQLStatement;
-
-//@}
-
-/** @name Resetting Values
- */
-
-//@{
-
-/** * Resets the values to a know, default state.
- *      - key                 = nil;
- *      - attribute           = nil;
- *      - value               = nil;
- *      - match               = NSFContains;
- *      - object type         = NSFReturnObjects;
- *      - groupValues         = NO;
- *      - attributesReturned  = nil;
- *      - type returned       = NSFReturnObjects;
- *      - sql                 = nil;
- *      - sort                = nil;
- *
- * @note
- * When invoked, it sets the values of search to its initial state. Resetting and performing a search will select all records.
- */
-
-- (void)reset;
-
-//@}
-
-@end