Documentation


#1

I know this chapter shows you how to use the Apple documentation, but is there a reference book where it kinda give more details and examples for each class - I am sure the documentation is great but I think its a little over my head at this moment - any advice?


#2

Keep going; you’ll be ready to read Apple’s references soon!


#3

One thing that would be helpful to add to this chapter is how to say in english the reference’d code. For example:

My feeble brain can almost turn that into code I would write to take advantage of this method, but not quite!

It’s possible I’ve simply forgotten this from an earlier chapter, or that it’s coming up soon, but part of me just wants a hint here in the docs chapter about it.


#4

In this case:

is looking in a container class like NSArray or NSSet. It searches for anObject and returns a BOOL.

In English it says does this array or set contain this particular object? Tell me YES or NO.


#5

Cool. So, to see if I’m tracking this, if I wanted to “call” this method (correct term?), I would do something like this?

[code] // For completeness, create three objects
NSString *larry = [NSString stringWithFormat:@“larry”];
NSString *curly = [NSString stringWithFormat:@“curly”];
NSString *mo = [NSString stringWithFormat:@“mo”];

    // Create an array containing the three objects
    NSArray *myObjects = [NSArray arrayWithObjects:larry, curly, mo, nil];
    
    // Determine if 'larry' is in the array
    BOOL inMyArray = [myObjects containsObject:larry];
    
    // The following would return YES
    NSLog(@"Is larry in my array? %@", inMyArray ? @"YES" : @"NO");

[/code]

Seem reasonable? This code appears to work, so I guess my question is: am I using the right terminology, and with appropriate coding style? The key that still seems a little dense to me is how this:

maps to/from:

I probably just need to keep going and not get too hung up here in the syntax.

Thanks for your help.


#6

Yes, I’d say you’ve got it.

I’ll take a stab at helping you find the mapping, but yeah, just plugging onward is a viable option.

Let’s start with the documentation first.

- (BOOL)containsObject:(id)anObject

This is documented, among other places, as a method in Apple’s NSArray documentation. That fact alone, though, doesn’t tell us whether this is a method that is defined as a class method (invoked directly from NSArray class, such as alloc) or an instance method. For that, we look at the first character, the - at the beginning of the line. If it were a +, that would mean a class method, but it isn’t, so this is called against individual arrays.

We look at your sample invocation to grab the variable name, then, and make our first step (this won’t compile, we’re not nearly done yet):

- (BOOL) myObjects containsObject:(id)anObject

But in order to actually call a method on the myObjects instance, we have to use Objective-C’s bracket syntax:

- (BOOL) [myObjects containsObject:(id)anObject]

And we already determined that the minus sign is an indicator of whether this method is defined at the class or instance level; we don’t actually need it when we’re invoking the class, so we must get rid of it:

(BOOL) [myObjects containsObject:(id)anObject]

After dropping the minus sign, we have b[/b] as a next reasonable syntax piece for analysis. Using b[/b] syntax in your code can mean you’re casting from one type to another (* footnote below) or that you’re declaring a method to return that type. In this case, the documentation is telling us that containsObject: returns a boolean (true/false) value.

Now that we know that, we could (again referring to your sample code) place its return value into a variable:

BOOL inMyArray = [myObjects containsObject:(id)anObject]

Getting closer.

Now we need to look at the other end of what’s left. A method that takes at least one argument uses a colon to indicate that, with the type of argument following (again, using the cast-like notation).

So containsObject:(id)anObject means that the containsObject: method (always using the colon when writing the method name, in case there’s an alternate version that doesn’t take an argument) takes one argument, a generic object (type “id”).

id is a topic all its own, but let’s set that aside for the moment and focus on the role it plays here. An NSArray instance can store any object of any type, so we can ask it whether it stores any object of any type.

Your sample code has a specific object that you’re curious about, larry, so let’s drop that in. Replace the entire argument, including the b[/b] type indicator:

BOOL inMyArray = [myObjects containsObject:larry]

The sharp-eyed will point out that we’re not done yet, because any statement in Objective-C must end with a semi-colon. (“statement” has a very literal meaning here; loops don’t end with semi-colons, but they’re not formally speaking statements.)

So we make our final step along the path we’ve chosen:

BOOL inMyArray = [myObjects containsObject:larry];

Whew.

I thought I might work backwards as well, but I think I’ll leave it there.

  • Footnote: more on casting and the b[/b] or b[/b] syntax:

Parentheses in Objective-C are used for a few different purposes, such as grouping operations appropriately, but it’s also used for casting values from one type to another. For example, if we have a function that returns a long integer (64 bits) and we pass it to a function that expects an integer (32 bits), the compiler will complain unless we cast it.

If longfun() returns a long, and intfun() expects an integer, we can write this:

intfun((int)longfun());

We took the return value from longfun and cast it to a shorter 32-bit integer. This is only safe and advisable if you’re absolutely confident that the value can’t be larger than 32 bits.


#7

Wow, that’s amazingly helpful, thank you!

I hereby nominate @macintux for Most Helpful Post on the Internet, December 2011.

Seriously, I will digest and continue onward in my journey.


#8

Only today I was searching for an explanation of the “-” and “+” that precedes these class method “things!” Of course, I can’t find the page now, but this is close: https://developer.apple.com/library/mac/#referencelibrary/GettingStarted/Learning_Objective-C_A_Primer/_index.html

This will probably be covered in Chapter 16, of course, since it covers classes. I’m going to print out [color=navy][size=85]macintux[/size][/color]'s post since it takes things step by step and very thoroughly! When are you going to write a book? :smiley: I’m also impressed with [color=navy][size=85]myacavone[/size][/color]'s understanding of how to use them! :sunglasses:


#9

Thanks so much guys… The explanation of + Vs - as the difference between class methods and instance methods is great… and makes sense…

However, while I look through the NSMutableArray Class reference I would have expected to see “array” as a class method. Why is this not the case? Is the expectation that I should know that [[NSMutableArray alloc] init] is the equivalent of [NSMutableArray array]?
Thanks!
R


#10

NSMutableArray is a subclass of NSArray, which declares the array class method: + (id)array.


#11

Hmmmmm… (Thanks)

So unlike Javadoc’s (bad example I know) the Apple documentation doesn’t clearly show methods (class or implementation) which are inherited?!?!

Seems hard to believe…

R.