X-Git-Url: https://git.mdrn.pl/wl-app.git/blobdiff_plain/53b27422d140022594fc241cca91c3183be57bca..48b2fe9f7c2dc3d9aeaaa6dbfb27c7da4f3235ff:/iOS/Pods/Realm/include/RLMObject.h diff --git a/iOS/Pods/Realm/include/RLMObject.h b/iOS/Pods/Realm/include/RLMObject.h new file mode 100644 index 0000000..33d0a95 --- /dev/null +++ b/iOS/Pods/Realm/include/RLMObject.h @@ -0,0 +1,555 @@ +//////////////////////////////////////////////////////////////////////////// +// +// Copyright 2014 Realm Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// +//////////////////////////////////////////////////////////////////////////// + +#import + +#import +#import + +NS_ASSUME_NONNULL_BEGIN + +@class RLMNotificationToken; +@class RLMObjectSchema; +@class RLMPropertyChange; +@class RLMPropertyDescriptor; +@class RLMRealm; +@class RLMResults; + +/** + `RLMObject` is a base class for model objects representing data stored in Realms. + + Define your model classes by subclassing `RLMObject` and adding properties to be managed. + Then instantiate and use your custom subclasses instead of using the `RLMObject` class directly. + + // Dog.h + @interface Dog : RLMObject + @property NSString *name; + @property BOOL adopted; + @end + + // Dog.m + @implementation Dog + @end //none needed + + ### Supported property types + + - `NSString` + - `NSInteger`, `int`, `long`, `float`, and `double` + - `BOOL` or `bool` + - `NSDate` + - `NSData` + - `NSNumber`, where `X` is one of `RLMInt`, `RLMFloat`, `RLMDouble` or `RLMBool`, for optional number properties + - `RLMObject` subclasses, to model many-to-one relationships. + - `RLMArray`, where `X` is an `RLMObject` subclass, to model many-to-many relationships. + + ### Querying + + You can initiate queries directly via the class methods: `allObjects`, `objectsWhere:`, and `objectsWithPredicate:`. + These methods allow you to easily query a custom subclass for instances of that class in the default Realm. + + To search in a Realm other than the default Realm, use the `allObjectsInRealm:`, `objectsInRealm:where:`, + and `objectsInRealm:withPredicate:` class methods. + + @see `RLMRealm` + + ### Relationships + + See our [Cocoa guide](https://realm.io/docs/objc/latest#relationships) for more details. + + ### Key-Value Observing + + All `RLMObject` properties (including properties you create in subclasses) are + [Key-Value Observing compliant](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html), + except for `realm` and `objectSchema`. + + Keep the following tips in mind when observing Realm objects: + + 1. Unlike `NSMutableArray` properties, `RLMArray` properties do not require + using the proxy object returned from `-mutableArrayValueForKey:`, or defining + KVC mutation methods on the containing class. You can simply call methods on + the `RLMArray` directly; any changes will be automatically observed by the containing + object. + 2. Unmanaged `RLMObject` instances cannot be added to a Realm while they have any + observed properties. + 3. Modifying managed `RLMObject`s within `-observeValueForKeyPath:ofObject:change:context:` + is not recommended. Properties may change even when the Realm is not in a write + transaction (for example, when `-[RLMRealm refresh]` is called after changes + are made on a different thread), and notifications sent prior to the change + being applied (when `NSKeyValueObservingOptionPrior` is used) may be sent at + times when you *cannot* begin a write transaction. + */ + +@interface RLMObject : RLMObjectBase + +#pragma mark - Creating & Initializing Objects + +/** + Creates an unmanaged instance of a Realm object. + + Call `addObject:` on an `RLMRealm` instance to add an unmanaged object into that Realm. + + @see `[RLMRealm addObject:]` + */ +- (instancetype)init NS_DESIGNATED_INITIALIZER; + + +/** + Creates an unmanaged instance of a Realm object. + + Pass in an `NSArray` or `NSDictionary` instance to set the values of the object's properties. + + Call `addObject:` on an `RLMRealm` instance to add an unmanaged object into that Realm. + + @see `[RLMRealm addObject:]` + */ +- (instancetype)initWithValue:(id)value NS_DESIGNATED_INITIALIZER; + + +/** + Returns the class name for a Realm object subclass. + + @warning Do not override. Realm relies on this method returning the exact class + name. + + @return The class name for the model class. + */ ++ (NSString *)className; + +/** + Creates an instance of a Realm object with a given value, and adds it to the default Realm. + + If nested objects are included in the argument, `createInDefaultRealmWithValue:` will be recursively called + on them. + + The `value` argument can be a key-value coding compliant object, an array or dictionary returned from the methods in + `NSJSONSerialization`, or an array containing one element for each managed property. + + An exception will be thrown if any required properties are not present and those properties + were not defined with default values. + + If the `value` argument is an array, all properties must be present, valid and in the same + order as the properties defined in the model. + + @param value The value used to populate the object. + + @see `defaultPropertyValues` + */ ++ (instancetype)createInDefaultRealmWithValue:(id)value; + +/** + Creates an instance of a Realm object with a given value, and adds it to the specified Realm. + + If nested objects are included in the argument, `createInRealm:withValue:` will be recursively called + on them. + + The `value` argument can be a key-value coding compliant object, an array or dictionary returned from the methods in + `NSJSONSerialization`, or an array containing one element for each managed property. + + An exception will be thrown if any required properties are not present and those properties + were not defined with default values. + + If the `value` argument is an array, all properties must be present, valid and in the same + order as the properties defined in the model. + + @param realm The Realm which should manage the newly-created object. + @param value The value used to populate the object. + + @see `defaultPropertyValues` + */ ++ (instancetype)createInRealm:(RLMRealm *)realm withValue:(id)value; + +/** + Creates or updates a Realm object within the default Realm. + + This method may only be called on Realm object types with a primary key defined. If there is already + an object with the same primary key value in the default Realm, its values are updated and the object + is returned. Otherwise, this method creates and populates a new instance of the object in the default Realm. + + If nested objects are included in the argument, `createOrUpdateInDefaultRealmWithValue:` will be + recursively called on them if they have primary keys, `createInDefaultRealmWithValue:` if they do not. + + The `value` argument is used to populate the object. It can be a Realm object, a key-value coding + compliant object, an array or dictionary returned from the methods in `NSJSONSerialization`, or an + array containing one element for each managed property. + + If the object is being created, an exception will be thrown if any required properties + are not present and those properties were not defined with default values. + + If the `value` argument is a Realm object already managed by the default Realm, the + argument's type is the same as the receiver, and the objects have identical values for + their managed properties, this method does nothing. + + If the object is being updated, all properties defined in its schema will be set by copying from + `value` using key-value coding. If the `value` argument does not respond to `valueForKey:` for a + given property name (or getter name, if defined), that value will remain untouched. + Nullable properties on the object can be set to nil by using `NSNull` as the updated value. + + If the `value` argument is an array, all properties must be present, valid and in the same + order as the properties defined in the model. + + @param value The value used to populate the object. + + @see `defaultPropertyValues`, `primaryKey` + */ ++ (instancetype)createOrUpdateInDefaultRealmWithValue:(id)value; + +/** + Creates or updates an Realm object within a specified Realm. + + This method may only be called on Realm object types with a primary key defined. If there is already + an object with the same primary key value in the given Realm, its values are updated and the object + is returned. Otherwise this method creates and populates a new instance of this object in the given Realm. + + If nested objects are included in the argument, `createOrUpdateInRealm:withValue:` will be + recursively called on them if they have primary keys, `createInRealm:withValue:` if they do not. + + The `value` argument is used to populate the object. It can be a Realm object, a key-value coding + compliant object, an array or dictionary returned from the methods in `NSJSONSerialization`, or an + array containing one element for each managed property. + + If the object is being created, an exception will be thrown if any required properties + are not present and those properties were not defined with default values. + + If the `value` argument is a Realm object already managed by the given Realm, the + argument's type is the same as the receiver, and the objects have identical values for + their managed properties, this method does nothing. + + If the object is being updated, all properties defined in its schema will be set by copying from + `value` using key-value coding. If the `value` argument does not respond to `valueForKey:` for a + given property name (or getter name, if defined), that value will remain untouched. + Nullable properties on the object can be set to nil by using `NSNull` as the updated value. + + If the `value` argument is an array, all properties must be present, valid and in the same + order as the properties defined in the model. + + @param realm The Realm which should own the object. + @param value The value used to populate the object. + + @see `defaultPropertyValues`, `primaryKey` + */ ++ (instancetype)createOrUpdateInRealm:(RLMRealm *)realm withValue:(id)value; + +#pragma mark - Properties + +/** + The Realm which manages the object, or `nil` if the object is unmanaged. + */ +@property (nonatomic, readonly, nullable) RLMRealm *realm; + +/** + The object schema which lists the managed properties for the object. + */ +@property (nonatomic, readonly) RLMObjectSchema *objectSchema; + +/** + Indicates if the object can no longer be accessed because it is now invalid. + + An object can no longer be accessed if the object has been deleted from the Realm that manages it, or + if `invalidate` is called on that Realm. + */ +@property (nonatomic, readonly, getter = isInvalidated) BOOL invalidated; + + +#pragma mark - Customizing your Objects + +/** + Returns an array of property names for properties which should be indexed. + + Only string, integer, boolean, and `NSDate` properties are supported. + + @return An array of property names. + */ ++ (NSArray *)indexedProperties; + +/** + Override this method to specify the default values to be used for each property. + + @return A dictionary mapping property names to their default values. + */ ++ (nullable NSDictionary *)defaultPropertyValues; + +/** + Override this method to specify the name of a property to be used as the primary key. + + Only properties of types `RLMPropertyTypeString` and `RLMPropertyTypeInt` can be designated as the primary key. + Primary key properties enforce uniqueness for each value whenever the property is set, which incurs minor overhead. + Indexes are created automatically for primary key properties. + + @return The name of the property designated as the primary key. + */ ++ (nullable NSString *)primaryKey; + +/** + Override this method to specify the names of properties to ignore. These properties will not be managed by the Realm + that manages the object. + + @return An array of property names to ignore. + */ ++ (nullable NSArray *)ignoredProperties; + +/** + Override this method to specify the names of properties that are non-optional (i.e. cannot be assigned a `nil` value). + + By default, all properties of a type whose values can be set to `nil` are considered optional properties. + To require that an object in a Realm always store a non-`nil` value for a property, + add the name of the property to the array returned from this method. + + Properties of `RLMObject` type cannot be non-optional. Array and `NSNumber` properties + can be non-optional, but there is no reason to do so: arrays do not support storing nil, and + if you want a non-optional number you should instead use the primitive type. + + @return An array of property names that are required. + */ ++ (NSArray *)requiredProperties; + +/** + Override this method to provide information related to properties containing linking objects. + + Each property of type `RLMLinkingObjects` must have a key in the dictionary returned by this method consisting + of the property name. The corresponding value must be an instance of `RLMPropertyDescriptor` that describes the class + and property that the property is linked to. + + return @{ @"owners": [RLMPropertyDescriptor descriptorWithClass:Owner.class propertyName:@"dogs"] }; + + @return A dictionary mapping property names to `RLMPropertyDescriptor` instances. + */ ++ (NSDictionary *)linkingObjectsProperties; + + +#pragma mark - Getting & Querying Objects from the Default Realm + +/** + Returns all objects of this object type from the default Realm. + + @return An `RLMResults` containing all objects of this type in the default Realm. + */ ++ (RLMResults *)allObjects; + +/** + Returns all objects of this object type matching the given predicate from the default Realm. + + @param predicateFormat A predicate format string, optionally followed by a variable number of arguments. + + @return An `RLMResults` containing all objects of this type in the default Realm that match the given predicate. + */ ++ (RLMResults *)objectsWhere:(NSString *)predicateFormat, ...; + +/// :nodoc: ++ (RLMResults<__kindof RLMObject *> *)objectsWhere:(NSString *)predicateFormat args:(va_list)args; + + +/** + Returns all objects of this object type matching the given predicate from the default Realm. + + @param predicate The predicate with which to filter the objects. + + @return An `RLMResults` containing all objects of this type in the default Realm that match the given predicate. + */ ++ (RLMResults *)objectsWithPredicate:(nullable NSPredicate *)predicate; + +/** + Retrieves the single instance of this object type with the given primary key from the default Realm. + + Returns the object from the default Realm which has the given primary key, or + `nil` if the object does not exist. This is slightly faster than the otherwise + equivalent `[[SubclassName objectsWhere:@"primaryKeyPropertyName = %@", key] firstObject]`. + + This method requires that `primaryKey` be overridden on the receiving subclass. + + @return An object of this object type, or `nil` if an object with the given primary key does not exist. + @see `-primaryKey` + */ ++ (nullable instancetype)objectForPrimaryKey:(nullable id)primaryKey; + + +#pragma mark - Querying Specific Realms + +/** + Returns all objects of this object type from the specified Realm. + + @param realm The Realm to query. + + @return An `RLMResults` containing all objects of this type in the specified Realm. + */ ++ (RLMResults *)allObjectsInRealm:(RLMRealm *)realm; + +/** + Returns all objects of this object type matching the given predicate from the specified Realm. + + @param predicateFormat A predicate format string, optionally followed by a variable number of arguments. + @param realm The Realm to query. + + @return An `RLMResults` containing all objects of this type in the specified Realm that match the given predicate. + */ ++ (RLMResults *)objectsInRealm:(RLMRealm *)realm where:(NSString *)predicateFormat, ...; + +/// :nodoc: ++ (RLMResults<__kindof RLMObject *> *)objectsInRealm:(RLMRealm *)realm where:(NSString *)predicateFormat args:(va_list)args; + +/** + Returns all objects of this object type matching the given predicate from the specified Realm. + + @param predicate A predicate to use to filter the elements. + @param realm The Realm to query. + + @return An `RLMResults` containing all objects of this type in the specified Realm that match the given predicate. + */ ++ (RLMResults *)objectsInRealm:(RLMRealm *)realm withPredicate:(nullable NSPredicate *)predicate; + +/** + Retrieves the single instance of this object type with the given primary key from the specified Realm. + + Returns the object from the specified Realm which has the given primary key, or + `nil` if the object does not exist. This is slightly faster than the otherwise + equivalent `[[SubclassName objectsInRealm:realm where:@"primaryKeyPropertyName = %@", key] firstObject]`. + + This method requires that `primaryKey` be overridden on the receiving subclass. + + @return An object of this object type, or `nil` if an object with the given primary key does not exist. + @see `-primaryKey` + */ ++ (nullable instancetype)objectInRealm:(RLMRealm *)realm forPrimaryKey:(nullable id)primaryKey; + +#pragma mark - Notifications + +/** + A callback block for `RLMObject` notifications. + + If the object is deleted from the managing Realm, the block is called with + `deleted` set to `YES` and the other two arguments are `nil`. The block will + never be called again after this. + + If the object is modified, the block will be called with `deleted` set to + `NO`, a `nil` error, and an array of `RLMPropertyChange` objects which + indicate which properties of the objects were modified. + + If an error occurs, `deleted` will be `NO`, `changes` will be `nil`, and + `error` will include information about the error. The block will never be + called again after an error occurs. + */ +typedef void (^RLMObjectChangeBlock)(BOOL deleted, + NSArray *_Nullable changes, + NSError *_Nullable error); + +/** + Registers a block to be called each time the object changes. + + The block will be asynchronously called after each write transaction which + deletes the object or modifies any of the managed properties of the object, + including self-assignments that set a property to its existing value. + + For write transactions performed on different threads or in differen + processes, the block will be called when the managing Realm is + (auto)refreshed to a version including the changes, while for local write + transactions it will be called at some point in the future after the write + transaction is committed. + + Notifications are delivered via the standard run loop, and so can't be + delivered while the run loop is blocked by other activity. When notifications + can't be delivered instantly, multiple notifications may be coalesced into a + single notification. + + Unlike with `RLMArray` and `RLMResults`, there is no "initial" callback made + after you add a new notification block. + + Only objects which are managed by a Realm can be observed in this way. You + must retain the returned token for as long as you want updates to be sent to + the block. To stop receiving updates, call `-invalidate` on the token. + + It is safe to capture a strong reference to the observed object within the + callback block. There is no retain cycle due to that the callback is retained + by the returned token and not by the object itself. + + @warning This method cannot be called during a write transaction, when the + containing Realm is read-only, or on an unmanaged object. + + @param block The block to be called whenever a change occurs. + @return A token which must be held for as long as you want updates to be delivered. + */ +- (RLMNotificationToken *)addNotificationBlock:(RLMObjectChangeBlock)block; + +#pragma mark - Other Instance Methods + +/** + Returns YES if another Realm object instance points to the same object as the receiver in the Realm managing + the receiver. + + For object types with a primary, key, `isEqual:` is overridden to use the same logic as this + method (along with a corresponding implementation for `hash`). + + @param object The object to compare the receiver to. + + @return Whether the object represents the same object as the receiver. + */ +- (BOOL)isEqualToObject:(RLMObject *)object; + +#pragma mark - Dynamic Accessors + +/// :nodoc: +- (nullable id)objectForKeyedSubscript:(NSString *)key; + +/// :nodoc: +- (void)setObject:(nullable id)obj forKeyedSubscript:(NSString *)key; + +@end + +/** + Information about a specific property which changed in an `RLMObject` change notification. + */ +@interface RLMPropertyChange : NSObject + +/** + The name of the property which changed. + */ +@property (nonatomic, readonly, strong) NSString *name; + +/** + The value of the property before the change occurred. This will always be `nil` + if the change happened on the same thread as the notification and for `RLMArray` + properties. + + For object properties this will give the object which was previously linked to, + but that object will have its new values and not the values it had before the + changes. This means that `previousValue` may be a deleted object, and you will + need to check `invalidated` before accessing any of its properties. + */ +@property (nonatomic, readonly, strong, nullable) id previousValue; + +/** + The value of the property after the change occurred. This will always be `nil` + for `RLMArray` properties. + */ +@property (nonatomic, readonly, strong, nullable) id value; +@end + +#pragma mark - RLMArray Property Declaration + +/** + Properties on `RLMObject`s of type `RLMArray` must have an associated type. A type is associated + with an `RLMArray` property by defining a protocol for the object type that the array should contain. + To define the protocol for an object, you can use the macro RLM_ARRAY_TYPE: + + RLM_ARRAY_TYPE(ObjectType) + ... + @property RLMArray *arrayOfObjectTypes; + */ +#define RLM_ARRAY_TYPE(RLM_OBJECT_SUBCLASS)\ +@protocol RLM_OBJECT_SUBCLASS \ +@end + +NS_ASSUME_NONNULL_END