diff --git a/Code/Support/RKDictionaryUtilities.h b/Code/Support/RKDictionaryUtilities.h index e83b5047..00a1e8f9 100644 --- a/Code/Support/RKDictionaryUtilities.h +++ b/Code/Support/RKDictionaryUtilities.h @@ -5,6 +5,18 @@ // Created by Blake Watters on 9/11/12. // Copyright (c) 2012 RestKit. All rights reserved. // +// 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 diff --git a/Code/Support/RKDotNetDateFormatter.h b/Code/Support/RKDotNetDateFormatter.h index 56a98ef1..9eaaded4 100644 --- a/Code/Support/RKDotNetDateFormatter.h +++ b/Code/Support/RKDotNetDateFormatter.h @@ -20,76 +20,54 @@ #import -// NSRegularExpression not available until OS X 10.7 and iOS 4.0 (NS_CLASS_AVAILABLE(10_7, 4_0)) -#if __MAC_OS_X_VERSION_MAX_ALLOWED >= 1070 || __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000 - /** - A subclass of NSDateFormatter that serves as translator between ASP.NET date serializations in JSON - strings and NSDate objects. This is useful for properly mapping these dates from an ASP.NET driven backend. - *NOTE *- DO NOT attempt to use setDateFormat: on this class. It will return invalid results. + A subclass of `NSDateFormatter` that serves as translator between ASP.NET date serializations in JSON strings and NSDate objects. This is useful for properly mapping these dates from an ASP.NET driven backend. + + @warning DO NOT attempt to use `setDateFormat:` on this class. It will return invalid results. */ -@interface RKDotNetDateFormatter : NSDateFormatter { - NSRegularExpression *dotNetExpression; -} +@interface RKDotNetDateFormatter : NSDateFormatter /** - Instantiates an autoreleased RKDotNetDateFormatter object with the timezone set to UTC - (Greenwich Mean Time). + Instantiates an autoreleased `RKDotNetDateFormatter` object with the timezone set to the given value. The default time zone is UTC. - @return An autoreleased RKDotNetDateFormatter object - @see dotNetDateFormatterWithTimeZone - */ -+ (RKDotNetDateFormatter *)dotNetDateFormatter; + The supplied timeZone, such as one produced with `[NSTimeZone timeZoneWithName:@"UTC"]`, + is only used during calls to `stringFromDate:, for a detailed explanation see `dateFromString:` -/** - Instantiates an autoreleased RKDotNetDateFormatter object. - The supplied timeZone, such as one produced with [NSTimeZone timeZoneWithName:@"UTC"], - is only used during calls to stringFromDate:, for a detailed explanation see dateFromString: - - @param timeZone An NSTimeZone object. - @return An autoreleased RKDotNetDateFormatter object + @param timeZone An NSTimeZone object. A `nil` value sets the timezone to the default value of UTC. + @return An autoreleased `RKDotNetDateFormatter` object @see dotNetDateFormatter */ + (RKDotNetDateFormatter *)dotNetDateFormatterWithTimeZone:(NSTimeZone *)timeZone; /** - Returns an NSDate object from an ASP.NET style date string respresentation, as seen in JSON. + Returns an `NSDate` object from an ASP.NET style date string respresentation, as seen in JSON. + Acceptable examples are: /Date(1112715000000-0500)/ /Date(1112715000000)/ /Date(-1112715000000)/ - Where 1112715000000 is the number of milliseconds since January 1, 1970 00:00 GMT/UTC, and -0500 represents the - timezone offset from GMT in 24-hour time. Negatives milliseconds are treated as dates before January 1, 1970. + Where 1112715000000 is the number of milliseconds since January 1, 1970 00:00 GMT/UTC, and -0500 represents the timezone offset from GMT in 24-hour time. Negatives milliseconds are treated as dates before January 1, 1970. - *NOTE *NSDate objects do not have timezones, and you should never change an actual date value based on a - timezone offset. However, timezones are important when presenting dates to the user. Therefore, - If an offset is present in the ASP.NET string (it should be), we actually ignore the offset portion because - we want to store the actual date value in its raw form, without any pollution of timezone information. - If, on the other hand, there is no offset in the ASP.NET string, we assume GMT (+0000) anyway. - In summation, for this class setTimeZone: is ignored except when using stringFromDate: + *NOTE* `NSDate` objects do not have timezones, and you should never change an actual date value based on a timezone offset. However, timezones are important when presenting dates to the user. Therefore, If an offset is present in the ASP.NET string (it should be), we actually ignore the offset portion because we want to store the actual date value in its raw form, without any pollution of timezone information. If, on the other hand, there is no offset in the ASP.NET string, we assume GMT (+0000) anyway. In summation, for this class `setTimeZone:` is ignored except when using `stringFromDate:` @param string The ASP.NET style string, /Date(1112715000000-0500)/ - @return An NSDate object - @see stringFromDate - @see NSDateFormatter - @see NSTimeZone + @return An `NSDate` object. + @see `stringFromDate` + @see `NSDateFormatter` + @see `NSTimeZone` */ - (NSDate *)dateFromString:(NSString *)string; /** - Returns an ASP.NET style date string from an NSDate, such as /Date(1112715000000+0000)/ - Where 1112715000000 is the number of milliseconds since January 1, 1970 00:00 GMT/UTC, and +0000 is the - timezone offset from GMT in 24-hour time. + Returns an ASP.NET style date string from an NSDate, such as /Date(1112715000000+0000)/ Where 1112715000000 is the number of milliseconds since January 1, 1970 00:00 GMT/UTC, and +0000 is the timezone offset from GMT in 24-hour time. - *NOTE *GMT (+0000) is assumed otherwise specified via setTimeZone: + *NOTE *GMT (+0000) is assumed otherwise specified via `setTimeZone:` - @param date An NSDate + @param date An `NSDate` object from which to return a string value. @return The ASP.NET style string, /Date(1112715000000-0500)/ - @see dateFromString - @see NSDateFormatter - @see NSTimeZone + @see `dateFromString` + @see `NSDateFormatter` + @see `NSTimeZone` */ - (NSString *)stringFromDate:(NSDate *)date; @end - -#endif diff --git a/Code/Support/RKDotNetDateFormatter.m b/Code/Support/RKDotNetDateFormatter.m index 969e5c01..8e0d4284 100644 --- a/Code/Support/RKDotNetDateFormatter.m +++ b/Code/Support/RKDotNetDateFormatter.m @@ -21,28 +21,22 @@ #import "RKDotNetDateFormatter.h" #import "RestKit.h" -#if __MAC_OS_X_VERSION_MAX_ALLOWED >= 1070 || __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000 - -BOOL isValidRange(NSRange rangeOfMatch); -NSTimeInterval secondsFromMilliseconds(NSTimeInterval millisecs); -NSTimeInterval millisecondsFromSeconds(NSTimeInterval seconds); +static BOOL RKDotNetDateFormatterIsValidRange(NSRange rangeOfMatch); +static NSTimeInterval RKDotNetDateFormatterSecondsFromMilliseconds(NSTimeInterval millisecs); +static NSTimeInterval RKDotNetDateFormatterMillisecondsFromSeconds(NSTimeInterval seconds); @interface RKDotNetDateFormatter () +@property (nonatomic, strong) NSRegularExpression *dotNetExpression; + - (NSString *)millisecondsFromString:(NSString *)string; @end @implementation RKDotNetDateFormatter -+ (RKDotNetDateFormatter *)dotNetDateFormatter -{ - return [RKDotNetDateFormatter dotNetDateFormatterWithTimeZone:nil]; -} - + (RKDotNetDateFormatter *)dotNetDateFormatterWithTimeZone:(NSTimeZone *)newTimeZone { RKDotNetDateFormatter *formatter = [[RKDotNetDateFormatter alloc] init]; - if (newTimeZone) - formatter.timeZone = newTimeZone; + if (newTimeZone) formatter.timeZone = newTimeZone; return formatter; } @@ -53,7 +47,7 @@ NSTimeInterval millisecondsFromSeconds(NSTimeInterval seconds); RKLogError(@"Attempted to interpret an invalid .NET date string: %@", string); return nil; } - NSTimeInterval seconds = secondsFromMilliseconds([milliseconds doubleValue]); + NSTimeInterval seconds = RKDotNetDateFormatterSecondsFromMilliseconds([milliseconds doubleValue]); return [NSDate dateWithTimeIntervalSince1970:seconds]; } @@ -79,7 +73,7 @@ NSTimeInterval millisecondsFromSeconds(NSTimeInterval seconds); { NSParameterAssert([value isKindOfClass:[NSDate class]]); NSString *timeZoneOffset = [super stringForObjectValue:value]; - NSTimeInterval milliseconds = millisecondsFromSeconds([(NSDate *)value timeIntervalSince1970]); + NSTimeInterval milliseconds = RKDotNetDateFormatterMillisecondsFromSeconds([(NSDate *)value timeIntervalSince1970]); return [NSString stringWithFormat:@"/Date(%1.0lf%@)/", milliseconds, timeZoneOffset]; } @@ -91,7 +85,7 @@ NSTimeInterval millisecondsFromSeconds(NSTimeInterval seconds); self.timeZone = [NSTimeZone timeZoneWithName:@"UTC"]; [self setDateFormat:@"ZZ"]; // GMT offset, like "-0500" NSString *pattern = @"\\/Date\\((-?\\d+)((?:[\\+\\-]\\d+)?)\\)\\/"; // /Date(mSecs)/ or /Date(-mSecs)/ or /Date(mSecs-0400)/ - dotNetExpression = [[NSRegularExpression alloc] initWithPattern:pattern options:NSRegularExpressionCaseInsensitive error:NULL]; + self.dotNetExpression = [[NSRegularExpression alloc] initWithPattern:pattern options:NSRegularExpressionCaseInsensitive error:NULL]; } return self; } @@ -101,33 +95,30 @@ NSTimeInterval millisecondsFromSeconds(NSTimeInterval seconds); - (NSString *)millisecondsFromString:(NSString *)string { - if (!string) - return nil; - NSTextCheckingResult *match = [dotNetExpression firstMatchInString:string options:NSMatchingCompleted range:NSMakeRange(0, [string length])]; - if (!match) - return nil; + if (!string) return nil; + NSTextCheckingResult *match = [self.dotNetExpression firstMatchInString:string options:NSMatchingCompleted range:NSMakeRange(0, [string length])]; + if (!match) return nil; NSRange millisecRange = [match rangeAtIndex:1]; - if (!isValidRange(millisecRange)) - return nil; - //NSRange timeZoneRange = [match rangeAtIndex:2]; + if (!RKDotNetDateFormatterIsValidRange(millisecRange)) return nil; NSString *milliseconds = [string substringWithRange:millisecRange]; return milliseconds; } @end -BOOL isValidRange(NSRange rangeOfMatch) { +static BOOL RKDotNetDateFormatterIsValidRange(NSRange rangeOfMatch) +{ return (!NSEqualRanges(rangeOfMatch, NSMakeRange(NSNotFound, 0))); } -NSTimeInterval secondsFromMilliseconds(NSTimeInterval millisecs) { +static NSTimeInterval RKDotNetDateFormatterSecondsFromMilliseconds(NSTimeInterval millisecs) +{ return millisecs / 1000.f; } -NSTimeInterval millisecondsFromSeconds(NSTimeInterval seconds) { +static NSTimeInterval RKDotNetDateFormatterMillisecondsFromSeconds(NSTimeInterval seconds) +{ return seconds *1000.f; } - -#endif diff --git a/Code/Support/RKMIMETypeSerialization.h b/Code/Support/RKMIMETypeSerialization.h index c08072ec..071869af 100644 --- a/Code/Support/RKMIMETypeSerialization.h +++ b/Code/Support/RKMIMETypeSerialization.h @@ -22,11 +22,7 @@ #import "RKSerialization.h" /** - The RKMIMETypeSerialization class provides support for the registration of classes - conforming to the RKSerialization protocol by MIME Type and the serialization and - deserialization of content by MIME Type. Serialization implementations may be registered - by an exact string match (i.e. 'application/json' for a JSON serialization implementation) - or by regular expression to match MIME Type by pattern. + The `RKMIMETypeSerialization` class provides support for the registration of classes conforming to the `RKSerialization` protocol by MIME Type and the serialization and deserialization of content by MIME Type. Serialization implementations may be registered by an exact string match (i.e. 'application/json' for a JSON serialization implementation) or by regular expression to match MIME Type by pattern. */ @interface RKMIMETypeSerialization : NSObject @@ -37,35 +33,28 @@ /** Registers the given serialization class to handle content for the given MIME Type identifier. - MIME Types may be given as either a string or as a regular expression that matches the MIME Types for which the - given serialization should handle. Serializations are searched in the reverse order of their registration. If a registration - is made for an already registered MIME Type, the new registration will take precedence. + MIME Types may be given as either a string or as a regular expression that matches the MIME Types for which the given serialization should handle. Serializations are searched in the reverse order of their registration. If a registration is made for an already registered MIME Type, the new registration will take precedence. @param serializationClass The class conforming to the RKSerialization protocol to be registered as handling the given MIME Type. - @param MIMETypeStringOrRegularExpression A string or regular expression specifying the MIME Type(s) that given serialization - implementation is to be registered as handling. + @param MIMETypeStringOrRegularExpression A string or regular expression specifying the MIME Type(s) that given serialization implementation is to be registered as handling. */ + (void)registerClass:(Class)serializationClass forMIMEType:(id)MIMETypeStringOrRegularExpression; /** Unregisters the given serialization class from handling any MIME Types. - After this method is invoked, invocations of `serializationForMIMEType:` will no longer return the unregistered - serialization class. + After this method is invoked, invocations of `serializationForMIMEType:` will no longer return the unregistered serialization class. - @param serializationClass The class conforming to the RKSerialization protocol to be unregistered. + @param serializationClass The class conforming to the `RKSerialization` protocol to be unregistered. */ + (void)unregisterClass:(Class)serializationClass; /** Returns the serialization class registered to handle the given MIME Type. - Searches the registrations in reverse order for the first serialization implementation registered to handle - the given MIME Type. Matches are determined by doing a lowercase string comparison if the MIME Type was registered - with a string identifier or by evaluating a regular expression match against the given MIME Type if registered with - a regular expression. + Searches the registrations in reverse order for the first serialization implementation registered to handle the given MIME Type. Matches are determined by doing a lowercase string comparison if the MIME Type was registered with a string identifier or by evaluating a regular expression match against the given MIME Type if registered with a regular expression. - @param MIMEType The MIME Type for which to return the registered RKSerialization conformant class. + @param MIMEType The MIME Type for which to return the registered `RKSerialization` conformant class. @return A class conforming to the RKSerialization protocol registered for the given MIME Type or nil if none was found. */ + (Class)serializationClassForMIMEType:(NSString *)MIMEType; @@ -82,13 +71,9 @@ ///--------------------------------------------------------- /** - Deserializes and returns a Foundation object representation of the given UTF-8 encoded data in - the serialization format for the given MIME Type. + Deserializes and returns a Foundation object representation of the given UTF-8 encoded data in the serialization format for the given MIME Type. - On invocation, searches the registrations by invoking `serializationClassForMIMEType:` with the given - MIME Type and then invokes `objectFromData:error:` on the RKSerialization conformant class returned. If - no serialization implementation is found to handle the given MIME Type, nil is returned and the given - error pointer will be set to an NSError object with the `RKMissingSerializationForMIMETypeError` code. + On invocation, searches the registrations by invoking `serializationClassForMIMEType:` with the given MIME Type and then invokes `objectFromData:error:` on the `RKSerialization` conformant class returned. If no serialization implementation is found to handle the given MIME Type, nil is returned and the given error pointer will be set to an NSError object with the `RKMissingSerializationForMIMETypeError` code. @param data The UTF-8 encoded data representation of the object to be deserialized. @param MIMEType The MIME Type of the serialization format the data is in. @@ -98,13 +83,9 @@ + (id)objectFromData:(NSData *)data MIMEType:(NSString *)MIMEType error:(NSError **)error; /** - Serializes and returns a UTF-8 encoded data representation of the given Foundation - object in the serialization format for the given MIME Type. + Serializes and returns a UTF-8 encoded data representation of the given Foundation object in the serialization format for the given MIME Type. - On invocation, searches the registrations by invoking `serializationClassForMIMEType:` with the given - MIME Type and then invokes `objectFromData:error:` on the RKSerialization conformant class returned. If - no serialization implementation is found to handle the given MIME Type, nil is returned and the given - error pointer will be set to an NSError object with the `RKMissingSerializationForMIMETypeError` code. + On invocation, searches the registrations by invoking `serializationClassForMIMEType:` with the given MIME Type and then invokes `objectFromData:error:` on the `RKSerialization` conformant class returned. If no serialization implementation is found to handle the given MIME Type, nil is returned and the given error pointer will be set to an NSError object with the `RKMissingSerializationForMIMETypeError` code. @param object The Foundation object to serialized. @param MIMEType The MIME Type of the serialization format the data is in. diff --git a/Code/Support/RKMacros.h b/Code/Support/RKMacros.h index 78a98c92..19c091fa 100644 --- a/Code/Support/RKMacros.h +++ b/Code/Support/RKMacros.h @@ -3,7 +3,6 @@ // RestKit // // Created by Jawwad Ahmad on 7/18/12. -// Copyright (c) 2012 RestKit. All rights reserved. // Copyright (c) 2009-2012 RestKit. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); diff --git a/Code/Support/RKPathMatcher.h b/Code/Support/RKPathMatcher.h index e5c473a1..138d7058 100644 --- a/Code/Support/RKPathMatcher.h +++ b/Code/Support/RKPathMatcher.h @@ -24,9 +24,9 @@ /** The `RKPathMatcher` class performs pattern matching and parameter parsing of strings, typically representing the path portion of an `NSURL` object. It provides much of the necessary tools to map a given path to local objects (the inverse of RKRouter's function). This makes it easier to implement the `RKManagedObjectCaching` protocol and generate `NSFetchRequest` objects from a given path. There are two means of instantiating and using a matcher object in order to provide more flexibility in implementations, and to improve efficiency by eliminating repetitive and costly pattern initializations. - @see RKManagedObjectCaching - @see RKMakePathWithObject - @see RKRouter + @see `RKManagedObjectCaching` + @see `RKPathFromPatternWithObject` + @see `RKRouter` */ @interface RKPathMatcher : NSObject @@ -35,34 +35,28 @@ ///--------------------------------- /** - Creates an RKPathMatcher starting from a path string. This method should be followed by - matchesPattern:tokenizeQueryStrings:parsedArguments: + Creates a path match object starting from a path string. This method should be followed by `matchesPattern:tokenizeQueryStrings:parsedArguments:` - @param pathString The string to evaluate and parse, such as /districts/tx/upper/?apikey=GC5512354 - @return An instantiated RKPathMatcher without an established pattern. + @param pathString The string to evaluate and parse, such as `/districts/tx/upper/?apikey=GC5512354` + @return An instantiated `RKPathMatcher` without an established pattern. */ + (RKPathMatcher *)matcherWithPath:(NSString *)pathString; /** - Determines if the path string matches the provided pattern, and yields a dictionary with the resulting - matched key/value pairs. Use of this method should be preceded by matcherWithPath: - Pattern strings should include encoded parameter keys, delimited by a single colon at the - beginning of the key name. + Determines if the path string matches the provided pattern, and yields a dictionary with the resulting matched key/value pairs. Use of this method should be preceded by `matcherWithPath:` Pattern strings should include encoded parameter keys, delimited by a single colon at the beginning of the key name. - *NOTE 1 *- Numerous colon-encoded parameter keys can be joined in a long pattern, but each key must be - separated by at least one unmapped character. For instance, /:key1:key2:key3/ is invalid, whereas - /:key1/:key2/:key3/ is acceptable. + *NOTE 1 *- Numerous colon-encoded parameter keys can be joined in a long pattern, but each key must be separated by at least one unmapped character. For instance, `/:key1:key2:key3/` is invalid, whereas `/:key1/:key2/:key3/` is acceptable. - *NOTE 2 *- The pattern matcher supports KVM, so :key1.otherKey normally resolves as it would in any other KVM + *NOTE 2 *- The pattern matcher supports KVM, so `:key1.otherKey` normally resolves as it would in any other KVM situation, ... otherKey is a sub-key on a the object represented by key1. This presents problems in circumstances where you might want to build a pattern like /:filename.json, where the dot isn't intended as a sub-key on the filename, but rather part of the json static string. In these instances, you need to escape the dot with two backslashes, like so: /:filename\\.json - @param patternString The pattern to use for evaluating, such as /:entityName/:stateID/:chamber/ + @param patternString The pattern to use for evaluating, such as `/:entityName/:stateID/:chamber/` @param shouldTokenize If YES, any query parameters will be tokenized and inserted into the parsed argument dictionary. @param arguments A pointer to a dictionary that contains the key/values from the pattern (and parameter) matching. - @return A boolean indicating if the path string successfully matched the pattern. + @return A boolean value indicating if the path string successfully matched the pattern. */ - (BOOL)matchesPattern:(NSString *)patternString tokenizeQueryStrings:(BOOL)shouldTokenize parsedArguments:(NSDictionary **)arguments; @@ -71,33 +65,24 @@ ///--------------------------------- /** - Creates an RKPathMatcher starting from a pattern string. This method should be followed by - matchesPath:tokenizeQueryStrings:parsedArguments: Patterns should include encoded parameter keys, - delimited by a single colon at the beginning of the key name. + Creates a path matcher object starting from a pattern string. This method should be followed by `matchesPath:tokenizeQueryStrings:parsedArguments:`. Patterns should include encoded parameter keys, delimited by a single colon at the beginning of the key name. - *NOTE 1 *- Numerous colon-encoded parameter keys can be joined in a long pattern, but each key must be - separated by at least one unmapped character. For instance, /:key1:key2:key3/ is invalid, whereas - /:key1/:key2/:key3/ is acceptable. + *NOTE 1 *- Numerous colon-encoded parameter keys can be joined in a long pattern, but each key must be separated by at least one unmapped character. For instance, `/:key1:key2:key3/` is invalid, whereas `/:key1/:key2/:key3/` is acceptable. - *NOTE 2 *- The pattern matcher supports KVM, so :key1.otherKey normally resolves as it would in any other KVM - situation, ... otherKey is a sub-key on a the object represented by key1. This presents problems in circumstances where - you might want to build a pattern like /:filename.json, where the dot isn't intended as a sub-key on the filename, but rather - part of the json static string. In these instances, you need to escape the dot with two backslashes, like so: - /:filename\\.json + *NOTE 2 *- The pattern matcher supports KVM, so `:key1.otherKey` normally resolves as it would in any other KVM situation, ... otherKey is a sub-key on a the object represented by key1. This presents problems in circumstances where you might want to build a pattern like `/:filename.json`, where the dot isn't intended as a sub-key on the filename, but rather part of the json static string. In these instances, you need to escape the dot with two backslashes, like so: `/:filename\\.json` - @param patternString The pattern to use for evaluating, such as /:entityName/:stateID/:chamber/ - @return An instantiated RKPathMatcher with an established pattern. + @param patternString The pattern to use for evaluating, such as `/:entityName/:stateID/:chamber/` + @return An instantiated `RKPathMatcher` with an established pattern. */ + (RKPathMatcher *)matcherWithPattern:(NSString *)patternString; /** - Determines if the given path string matches a pattern, and yields a dictionary with the resulting - matched key/value pairs. Use of this method should be preceded by matcherWithPattern: + Determines if the given path string matches a pattern, and yields a dictionary with the resulting matched key/value pairs. Use of this method should be preceded by `matcherWithPattern:`. - @param pathString The string to evaluate and parse, such as /districts/tx/upper/?apikey=GC5512354 + @param pathString The string to evaluate and parse, such as `/districts/tx/upper/?apikey=GC5512354` @param shouldTokenize If YES, any query parameters will be tokenized and inserted into the parsed argument dictionary. @param arguments A pointer to a dictionary that contains the key/values from the pattern (and parameter) matching. - @return A boolean indicating if the path string successfully matched the pattern. + @return A boolean value indicating if the path string successfully matched the pattern. */ - (BOOL)matchesPath:(NSString *)pathString tokenizeQueryStrings:(BOOL)shouldTokenize parsedArguments:(NSDictionary **)arguments; @@ -106,9 +91,7 @@ ///---------------------------------- /** - Generates a new path by interpolating the properties of the 'object' argument, assuming the existence - of a previously specified pattern established via matcherWithPattern:. Otherwise, this method is identical in - function to RKMakePathWithObject (in fact it is a shortcut for this method). + Generates a new path by interpolating the properties of the 'object' argument, assuming the existence of a previously specified pattern established via `matcherWithPattern:`. Otherwise, this method is identical in function to `RKPathFromPatternWithObject` (in fact it is a shortcut for this method). For example, given an 'article' object with an 'articleID' property value of 12345 ... @@ -119,28 +102,25 @@ @param object The object containing the properties to interpolate. @return A string with the object's interpolated property values inserted into the receiver's established pattern. - @see RKMakePathWithObject - @see RKRouter + @see `RKPathFromPatternWithObject` + @see `RKRouter` */ - (NSString *)pathFromObject:(id)object DEPRECATED_ATTRIBUTE; /** - Generates a path by interpolating the properties of the 'object' argument, assuming the existence - of a previously specified pattern established via matcherWithPattern:. Otherwise, this method is identical in - function to RKMakePathWithObject (in fact it is a shortcut for this method). + Generates a path by interpolating the properties of the 'object' argument, assuming the existence of a previously specified pattern established via `matcherWithPattern:`. Otherwise, this method is identical in function to `RKPathFromPatternWithObject` (in fact it is a shortcut for this method). For example, given an 'article' object with an 'articleID' property value of 12345 and a code of "This/That"... - RKPathMatcher *matcher = [RKPathMatcher matcherWithPattern:@"/articles/:articleID/:code"]; - NSString *path = [matcher pathFromObject:article addingEscapes:YES]; + RKPathMatcher *matcher = [RKPathMatcher matcherWithPattern:@"/articles/:articleID/:code"]; + NSString *path = [matcher pathFromObject:article addingEscapes:YES]; - ... will produce a 'path' containing the string "/articles/12345/This%2FThat" + ... will produce a 'path' containing the string `@"/articles/12345/This%2FThat"` @param object The object containing the properties to interpolate. @param addEscapes Conditionally add percent escapes to the interpolated property values @return A string with the object's interpolated property values inserted into the receiver's established pattern. - @see RKMakePathWithObjectAddingEscapes - @see RKRouter + @see `RKRouter` */ - (NSString *)pathFromObject:(id)object addingEscapes:(BOOL)addEscapes; diff --git a/Code/Support/RKPathUtilities.h b/Code/Support/RKPathUtilities.h index 09014f1c..cabe8a76 100644 --- a/Code/Support/RKPathUtilities.h +++ b/Code/Support/RKPathUtilities.h @@ -9,18 +9,18 @@ #import /** - Returns the path to the Application Data directory for the executing application. On iOS, this is a sandboxed path specific for the executing application. On OS X, this is an application specific path under NSApplicationSupportDirectory (i.e. ~/Application Support). + Returns the path to the Application Data directory for the executing application. On iOS, this is a sandboxed path specific for the executing application. On OS X, this is an application specific path under `NSApplicationSupportDirectory` (i.e. ~/Application Support). @return The full path to the application data directory. */ -NSString * RKApplicationDataDirectory(void); +NSString *RKApplicationDataDirectory(void); /** Returns a path to the root caches directory used by RestKit for storage. On iOS, this is a sanboxed path specific for the executing application. On OS X, this is an application specific path under NSCachesDirectory (i.e. ~/Library/Caches). @return The full path to the Caches directory. */ -NSString * RKCachesDirectory(void); +NSString *RKCachesDirectory(void); /** Ensures that a directory exists at a given path by checking for the existence of the directory and creating it if it does not exist. @@ -41,10 +41,10 @@ BOOL RKEnsureDirectoryExistsAtPath(NSString *path, NSError **error); @param pathPattern An `SOCPattern` string containing zero or more colon-prefixed property names. @param object The object to interpolate the properties against @return A new `NSString` object with the values of the given object interpolated for the colon-prefixed properties name in the given pattern string. - @see RKPathMatcher - @see SOCPattern + @see `RKPathMatcher` + @see `SOCPattern` */ -NSString * RKPathFromPatternWithObject(NSString *pathPattern, id object); +NSString *RKPathFromPatternWithObject(NSString *pathPattern, id object); /** Returns a MIME Type for a given path by using the Core Services framework. @@ -53,4 +53,4 @@ NSString * RKPathFromPatternWithObject(NSString *pathPattern, id object); @return The expected MIME Type of the resource identified by the path or nil if unknown. */ -NSString * RKMIMETypeFromPathExtension(NSString *path); +NSString *RKMIMETypeFromPathExtension(NSString *path); diff --git a/Code/Support/RKSerialization.h b/Code/Support/RKSerialization.h index 2b2aaea5..910caa5f 100644 --- a/Code/Support/RKSerialization.h +++ b/Code/Support/RKSerialization.h @@ -19,13 +19,9 @@ // /** - The RKSerialization protocol declares two methods that a class must implement - so that it can provide support for serializing objects to and deserializing objects - from UTF-8 encoded data representations of a serialization format such as JSON - or XML. Serialization implementations typically handle data in a given MIME Type - (i.e. application/json) and may be registered with the RKMIMETypeSerialization class. + The `RKSerialization` protocol declares two methods that a class must implement so that it can provide support for serializing objects to and deserializing objects from UTF-8 encoded data representations of a serialization format such as JSON or XML. Serialization implementations typically handle data in a given MIME Type (i.e. `application/json`) and may be registered with the `RKMIMETypeSerialization` class. - @see RKMIMETypeSerialization + @see `RKMIMETypeSerialization` */ @protocol RKSerialization @@ -34,11 +30,10 @@ ///------------------------------ /** - Deserializes and returns the given data in the format supported by the receiver - (i.e. JSON, XML, etc) as a Foundation object representation. + Deserializes and returns the given data in the format supported by the receiver (i.e. JSON, XML, etc) as a Foundation object representation. @param data The UTF-8 encoded data representation of the object to be deserialized. - @param error A pointer to an NSError object. + @param error A pointer to an `NSError` object. @return A Foundation object from the serialized data in data, or nil if an error occurs. */ + (id)objectFromData:(NSData *)data error:(NSError **)error; @@ -48,11 +43,10 @@ ///---------------------------- /** - Serializes and returns a UTF-8 encoded data representation of the given Foundation - object in the format supported by the receiver (i.e. JSON, XML, etc). + Serializes and returns a UTF-8 encoded data representation of the given Foundation object in the format supported by the receiver (i.e. JSON, XML, etc). @param object The object to be serialized. - @param A pointer to an NSError object. + @param A pointer to an `NSError` object. @param error A pointer to an NSError object. @return A data representation of the given object in UTF-8 encoding, or nil if an error occurred. */