Merge branch 'release/1.1.0'

BRFullTextSearch.podspec

@@ -1,7 +1,7 @@
 Pod::Spec.new do |s|
 
   s.name         = "BRFullTextSearch"
-  s.version      = "1.0.10"
+  s.version      = "1.1.0"
   s.summary      = "iOS Objective-C full text search engine."
   s.description  = <<-DESC
                    This project provides a way to integrate full-text search

BRFullTextSearch/BRIndexable.h

@@ -10,6 +10,8 @@
 
 #import "BRSearchFields.h"
 
+NS_ASSUME_NONNULL_BEGIN
+
 /** A search document original field value storage type. */
 typedef NS_ENUM (unsigned int, BRIndexableStorageType) {
 	/** Store the original field value in the index. Useful for tokenized or omitted field index types. */
@@ -58,7 +60,8 @@ typedef NS_ENUM (unsigned int, BRIndexableIndexType) {
  * Get the type of object this document represents.
  *
  * Search documents are uniquely identified by combining their `indexObjectType` **and**
- * `indexIdentifier` values.
+ * `indexIdentifier` values. The actual values used are arbitrary and application dependent.
+ * Simple applications might use a single value for all search documents.
  *
  * @return the type of object
  */
@@ -119,3 +122,5 @@ typedef NS_ENUM (unsigned int, BRIndexableIndexType) {
 - (BRIndexableIndexType)indexFieldIndexType:(NSString *)fieldName;
 
 @end
+
+NS_ASSUME_NONNULL_END

BRFullTextSearch/BRSearchFields.h

@@ -10,6 +10,8 @@
 extern "C" {
 #endif
 
+NS_ASSUME_NONNULL_BEGIN
+
 /** Search field constant for the search document unique identifier value (`id`). */
 extern NSString *const kBRSearchFieldNameIdentifier;
 
@@ -25,7 +27,7 @@ extern NSString *const kBRSearchFieldNameValue;
 /** Search field constant for a date value (`s`). */
 extern NSString *const kBRSearchFieldNameTimestamp;
 
-/** Type definition for a "type of" search object flag. */
+/** Type definition for a "type of" search object flag. Values are arbitrary and application dependent. */
 typedef char BRSearchObjectType;
 
 /**
@@ -48,6 +50,8 @@ extern NSString *StringForBRSearchObjectType(BRSearchObjectType type);
  */
 extern BRSearchObjectType BRSearchObjectTypeForString(NSString *string);
 
+NS_ASSUME_NONNULL_END
+
 #ifdef __cplusplus
 }
 #endif

BRFullTextSearch/BRSearchResult.h

@@ -10,6 +10,8 @@
 
 #import "BRSearchFields.h"
 
+NS_ASSUME_NONNULL_BEGIN
+
 /**
  * API for a search result match.
  *
@@ -32,7 +34,7 @@
  * @param fieldName the name of the field to get the value for
  * @return the value of the field, or `nil` if no value is available
  */
-- (id)valueForField:(NSString *)fieldName;
+- (nullable id)valueForField:(NSString *)fieldName;
 
 /**
  * Get the date components, in local time, for a timestamp field.
@@ -55,3 +57,5 @@
 - (NSDictionary *)dictionaryRepresentation;
 
 @end
+
+NS_ASSUME_NONNULL_END

BRFullTextSearch/BRSearchResults.h

@@ -10,6 +10,8 @@
 
 #import "BRSearchResult.h"
 
+NS_ASSUME_NONNULL_BEGIN
+
 /**
  * Block for iterating over search result matches.
  *
@@ -69,3 +71,6 @@ typedef void (^BRSearchServiceSearchResultsIterator)(NSUInteger index, id <BRSea
 - (NSArray *)resultsGroupedByDay:(NSString *)fieldName;
 
 @end
+
+NS_ASSUME_NONNULL_END
+

BRFullTextSearch/BRSearchService.h

@@ -13,31 +13,9 @@
 #import "BRSearchFields.h"
 #import "BRSearchResult.h"
 #import "BRSearchResults.h"
+#import "BRSortDescriptor.h"
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/**
- * A search result field value sort type.
- *
- * When sorting search results by a particular field, all field values are assumed to
- * have the same data type, as specified by these constants.
- */
-typedef NS_ENUM (unsigned int, BRSearchSortType) {
-	/** Sort based on lexicographical order of field values. */
-	BRSearchSortTypeString = 0,
-
-	/** Sort based on integer order of field values. */
-	BRSearchSortTypeInteger,
-
-	/** Sort based on floating point order of field values. */
-	BRSearchSortTypeFloat,
-};
-
-#ifdef __cplusplus
-}
-#endif
+NS_ASSUME_NONNULL_BEGIN
 
 /** A `NSError` domain for search services to use. */
 extern NSString *const BRSearchServiceErrorDomain;
@@ -68,15 +46,15 @@ extern NSString * const BRSearchServiceQueryParsingException;
  *
  * @param error an error, or `nil` if no error occurred
  */
-typedef void (^BRSearchServiceCallbackBlock)(NSError *error);
+typedef void (^BRSearchServiceCallbackBlock)(NSError * _Nullable error);
 
 /**
  * An update operation completion block callback.
  *
  * @param updateCount the number of updates that occurred
  * @param error an error, or `nil` if no error occurred
  */
-typedef void (^BRSearchServiceUpdateCallbackBlock)(int updateCount, NSError *error);
+typedef void (^BRSearchServiceUpdateCallbackBlock)(int updateCount, NSError * _Nullable error);
 
 /**
  * API for a service supporting both indexing documents and executing queries to find matches to those documents.
@@ -109,7 +87,7 @@ typedef void (^BRSearchServiceUpdateCallbackBlock)(int updateCount, NSError *err
  * @param finishedQueue the dispatch queue to execute the completion block on, or `NULL` for an arbitrary global queue
  * @param finished a block to execute after adding the object to the index, or `NULL`
  */
-- (void)addObjectToIndex:(id <BRIndexable> )object queue:(dispatch_queue_t)finishedQueue finished:(BRSearchServiceCallbackBlock)finished;
+- (void)addObjectToIndex:(id <BRIndexable> )object queue:(nullable dispatch_queue_t)finishedQueue finished:(nullable BRSearchServiceCallbackBlock)finished;
 
 /**
  * Add an array of objects to the index.
@@ -121,7 +99,7 @@ typedef void (^BRSearchServiceUpdateCallbackBlock)(int updateCount, NSError *err
  * @param finishedQueue the dispatch queue to execute the completion block on, or `NULL` for an arbitrary global queue
  * @param finished a block to execute after adding the object to the index, or `NULL`
  */
-- (void)addObjectsToIndex:(NSArray *)objects queue:(dispatch_queue_t)finishedQueue finished:(BRSearchServiceCallbackBlock)finished;
+- (void)addObjectsToIndex:(NSArray *)objects queue:(nullable dispatch_queue_t)finishedQueue finished:(nullable BRSearchServiceCallbackBlock)finished;
 
 /**
  * Add a single object to the index on the current thread.
@@ -161,8 +139,8 @@ typedef void (^BRSearchServiceUpdateCallbackBlock)(int updateCount, NSError *err
  */
 - (void)removeObjectsFromIndex:(BRSearchObjectType)type
                withIdentifiers:(NSSet *)identifiers
-                         queue:(dispatch_queue_t)finishedQueue
-                      finished:(BRSearchServiceUpdateCallbackBlock)finished;
+                         queue:(nullable dispatch_queue_t)finishedQueue
+                      finished:(nullable BRSearchServiceUpdateCallbackBlock)finished;
 
 /**
  * Remove a set of objects of the same type based on their unique identifiers on the current thread.
@@ -187,8 +165,8 @@ typedef void (^BRSearchServiceUpdateCallbackBlock)(int updateCount, NSError *err
  * @see searchWithPredicate:sortBy:sortType:ascending: for a discussion on predicate queries
  */
 - (void)removeObjectsFromIndexMatchingPredicate:(NSPredicate *)predicate
-                                          queue:(dispatch_queue_t)finishedQueue
-                                       finished:(BRSearchServiceUpdateCallbackBlock)finished;
+                                          queue:(nullable dispatch_queue_t)finishedQueue
+                                       finished:(nullable BRSearchServiceUpdateCallbackBlock)finished;
 
 /**
  * Remove a set of documents from the search index that match a predicate query, on the current thread.
@@ -228,7 +206,7 @@ typedef void (^BRSearchServiceIndexUpdateBlock)(id <BRIndexUpdateContext> update
  * @param finishedQueue the dispatch queue to execute the completion block on, or `NULL` for an arbitrary global queue
  * @param finished a block to execute after the bulk operations are complete, or `NULL`
  */
-- (void)bulkUpdateIndex:(BRSearchServiceIndexUpdateBlock)updateBlock queue:(dispatch_queue_t)finishedQueue finished:(BRSearchServiceUpdateCallbackBlock)finished;
+- (void)bulkUpdateIndex:(BRSearchServiceIndexUpdateBlock)updateBlock queue:(nullable dispatch_queue_t)finishedQueue finished:(nullable BRSearchServiceUpdateCallbackBlock)finished;
 
 /**
  * Perform a batch set of index update operations on the current thread.
@@ -304,32 +282,64 @@ typedef void (^BRSearchServiceIndexUpdateBlock)(id <BRIndexUpdateContext> update
 /**
  * Execute a search using an implementation-specific query string, optionally sorting the results by a search document field.
  *
- * The query string must be parseable by the implementing search service.
+ * The query string must be parseable by the implementing search service. This is a convenience method for the more general
+ * `search:withSortDescriptors:` method.
  *
  * @param query the search query
  * @param sortFieldName the name of the search document field to order the matches by, or `nil` to sort by relevance
  * @param sortType the data type of the sort field (ignored if `sortFieldName` is `nil`)
  * @param ascending `YES` for ascending sort order, `NO` for descending (ignored if `sortFieldName` is `nil`)
+ * @return the search results
  */
 - (id <BRSearchResults> )search:(NSString *)query
-                         sortBy:(NSString *)sortFieldName
+                         sortBy:(nullable NSString *)sortFieldName
                        sortType:(BRSearchSortType)sortType
                       ascending:(BOOL)ascending;
 
+/**
+ * Execute a search using an implementation-specific query string, optionally sorting the results by a set of sort descriptors.
+ *
+ * The query string must be parseable by the implementing search service.
+ *
+ * @param query the search query
+ * @param sorts the array of sort descriptors, or `nil` to sort by relevance
+ * @return the search results
+ */
+- (id <BRSearchResults> )search:(NSString *)query withSortDescriptors:(nullable NSArray<id<BRSortDescriptor>> *)sorts;
+
 /**
  * Execute a search using a predicate, optionally sorting the results by a search document field.
  *
  * Predicates are constructed with field names as the left-hand expression, and the right-hand expression the constant
  * value to search for within that field. The supported comparison types is implementation specific, as is the support
  * for nested predicates and boolean predicates. Consult the documentation of the implementation for more information.
  *
+ * This is a convenience method for the more general `searchWithPredicate:sortDescriptors:` method.
+ *
+ * @param predicate the search predicate
  * @param sortFieldName the name of the search document field to order the matches by, or `nil` to sort by relevance
  * @param sortType the data type of the sort field (ignored if `sortFieldName` is `nil`)
  * @param ascending `YES` for ascending sort order, `NO` for descending (ignored if `sortFieldName` is `nil`)
+ * @return the search results
  */
 - (id <BRSearchResults> )searchWithPredicate:(NSPredicate *)predicate
-                                      sortBy:(NSString *)sortFieldName
+                                      sortBy:(nullable NSString *)sortFieldName
                                     sortType:(BRSearchSortType)sortType
                                    ascending:(BOOL)ascending;
 
+/**
+ * Execute a search using a predicate, optionally sorting the results by a search document field.
+ *
+ * Predicates are constructed with field names as the left-hand expression, and the right-hand expression the constant
+ * value to search for within that field. The supported comparison types is implementation specific, as is the support
+ * for nested predicates and boolean predicates. Consult the documentation of the implementation for more information.
+ *
+ * @param predicate the search predicate
+ * @param sorts the array of sort descriptors, or `nil` to sort by relevance
+ * @return the search results
+ */
+- (id <BRSearchResults> )searchWithPredicate:(NSPredicate *)predicate sortDescriptors:(nullable NSArray<id<BRSortDescriptor>> *)sorts;
+
 @end
+
+NS_ASSUME_NONNULL_END

BRFullTextSearch/BRSimpleSortDescriptor.h

@@ -0,0 +1,33 @@
+//
+//  BRSimpleSortDescriptor.h
+//  BRFullTextSearch
+//
+//  Created by Matt on 25/02/16.
+//  Copyright © 2016 Blue Rocket. Distributable under the terms of the Apache License, Version 2.0.
+//
+
+#import "BRSortDescriptor.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ A basic implementation of the \c BRSortDescriptor API.
+ */
+@interface BRSimpleSortDescriptor : NSObject <BRSortDescriptor>
+
+/**
+ Initialize with settings.
+ 
+ @param fieldName The field name to sort by.
+ @param type      The type of sort to apply.
+ @param ascending YES for ascending, NO for descending order.
+ 
+ @return The initialized instance.
+ */
+- (instancetype)initWithFieldName:(NSString *)fieldName
+							 type:(BRSearchSortType)type
+						ascending:(BOOL)ascending NS_DESIGNATED_INITIALIZER;
+
+@end
+
+NS_ASSUME_NONNULL_END

BRFullTextSearch/BRSimpleSortDescriptor.m

@@ -0,0 +1,36 @@
+//
+//  BRSimpleSortDescriptor.m
+//  BRFullTextSearch
+//
+//  Created by Matt on 25/02/16.
+//  Copyright © 2016 Blue Rocket. Distributable under the terms of the Apache License, Version 2.0.
+//
+
+#import "BRSimpleSortDescriptor.h"
+
+#import "BRSearchFields.h"
+
+@implementation BRSimpleSortDescriptor {
+	NSString *sortFieldName;
+	BRSearchSortType sortType;
+	BOOL ascending;
+}
+
+@synthesize sortFieldName;
+@synthesize sortType;
+@synthesize ascending;
+
+- (instancetype)init {
+	return [self initWithFieldName:kBRSearchFieldNameTimestamp type:BRSearchSortTypeString ascending:NO];
+}
+
+- (instancetype)initWithFieldName:(NSString *)fieldName type:(BRSearchSortType)type ascending:(BOOL)asc {
+	if ( (self = [super init]) ) {
+		sortFieldName = fieldName;
+		sortType = type;
+		ascending = asc;
+	}
+	return self;
+}
+
+@end

BRFullTextSearch/BRSortDescriptor.h

@@ -0,0 +1,54 @@
+//
+//  BRSortDescriptor.h
+//  BRFullTextSearch
+//
+//  Created by Matt on 25/02/16.
+//  Copyright © 2016 Blue Rocket. Distributable under the terms of the Apache License, Version 2.0.
+//
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * A search result field value sort type.
+ *
+ * When sorting search results by a particular field, all field values are assumed to
+ * have the same data type, as specified by these constants.
+ */
+typedef NS_ENUM (unsigned int, BRSearchSortType) {
+	/** Sort based on lexicographical order of field values. */
+	BRSearchSortTypeString = 0,
+
+	/** Sort based on integer order of field values. */
+	BRSearchSortTypeInteger,
+
+	/** Sort based on floating point order of field values. */
+	BRSearchSortTypeFloat,
+};
+
+#ifdef __cplusplus
+}
+#endif
+
+/**
+ API for a description of sort characteristics.
+ */
+@protocol BRSortDescriptor <NSObject>
+
+/** The name of the search document field to order the matches by. */
+@property (nonatomic, readonly) NSString *sortFieldName;
+
+/** The type of sort to use. */
+@property (nonatomic, readonly) BRSearchSortType sortType;
+
+/** YES to sort in ascending order, NO for descending. */
+@property (nonatomic, readonly, getter=isAscending) BOOL ascending;
+
+@end
+
+NS_ASSUME_NONNULL_END