Use of pass by reference in Objective-C

Looking at the JSON-Framework source, it makes heavy use of pass by reference in many of the parser method signatures. i.e.

@interface SBJsonParser ()
  - (BOOL)scanValue:(NSObject **)o;
  - (BOOL)scanRestOfArray:(NSMutableArray **)o;
  - (BOOL)scanRestOfDictionary:(NSMutableDictionary **)o;
@end

This ends up being used something like this:

id o;
[self scanValue:&o];
// Do something with o

- (BOOL)scanValue:(NSObject **)o {
  // Cut down for brevity
  return [self scanRestOfDictionary:(NSMutableDictionary **)o];
}

- (BOOL)scanRestOfDictionary:(NSMutableDictionary **)o {
  // Cut down for brevity
  *o = [NSMutableDictionary dictionaryWithCapacity:7];
  [*o setObject:@"value" forKey:@"key"];
  return YES;
}

What开发者_StackOverflow社区 are the benefits to this approach?

---

EDIT: I'm asking more from a design point of view. I understand what pass by reference is, I'm just wondering when it's appropriate to use it. The design used in SBJsonParser is similar to the API used in NSScanner:

- (BOOL)scanUpToString:(NSString *)stopString intoString:(NSString **)stringValue;

To me, this implies that the string which was scanned is secondary to needing to know if something was scanned. This is in contrast to the API used by NSString:

+ (id)stringWithContentsOfFile:(NSString *)path encoding:(NSStringEncoding)enc error:(NSError **)error;

In that API, the contents of the file is the primary concern, and the NSError reference is used to pass back an error in the event that something goes wrong.

Just after some general thoughts on which API is most appropriate, when.

---

Those are "output" parameters. They allow the called method to assign a value to your local variable "o". In other words, you're not passing in a reference to an object, but a reference to a local variable.

In your case, the methods return a BOOL to indicate success or failure; therefore, they use output parameters to return other values and objects.

---

It's really just a style question. It should be consistent across an entire API.

On the one hand, you've got a style where the status code of the call is always returned and output of the call is in the parameter list.

Benefits? You can always check the call result for success. You can easily have multiple return values without changing the style.

Drawbacks? Can't just drop in calls in place of parameters. Harder to chain.

On the other hand, you've got a style where the primary data is returned from the call and any error codes are done through out parameters.

The benefits and drawbacks are essentially inverted.

To be fair, there's a third style: no results are passed out or returned. Instead, exceptions are used.

Benefits? Cleaner looking code.

Drawbacks? Works well for errors, but not so well for status codes that may go along with valid return codes.