← Back to branch summary

~ubuntu-branches/ubuntu/trusty/gnustep-base/trusty

« back to all changes in this revision

Viewing changes to Documentation/manual/WritingNewClasses.texi

Tags: upstream-1.11.2
Import upstream version 1.11.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/manual/WritingNewClasses.texi
89
89
@}
90
90
 
91
91
// class methods
92
 
+ new;
93
 
+ newWithX: (float)x0 Y: (float)y0;
 
92
+ (id) new;
 
93
+ (id) newWithX: (float)x0 Y: (float)y0;
 
94
+ (Point*) point;
 
95
+ (Point*) pointWithX: (float)x0 Y: (float)y0;
94
96
 
95
97
// instance methods
96
 
- init;
97
 
- initWithX: (float)x0 Y: (float)y0;
 
98
- (id) init;
 
99
- (id) initWithX: (float)x0 Y: (float)y0;
98
100
- (float) x;  // (field accessor)
99
101
- (float) y;
100
102
- (void) setX: (float)newX;
234
236
  Point *lowerLeft;
235
237
  float sideLength;
236
238
@}
237
 
+ newWithLowerLeft: (Point *)lowerLeft sideLength: (float)sideLength;
 
239
+ (id) newWithLowerLeft: (Point *)lowerLeft sideLength: (float)sideLength;
238
240
 
239
 
- initWithLowerLeft: (Point *)lowerLeft sideLength: (float)sideLength;
 
241
- (id) initWithLowerLeft: (Point *)lowerLeft sideLength: (float)sideLength;
240
242
 
241
243
- (Point *) lowerLeft;
242
244
- (float) sideLength;
289
291
#import "Point.h"
290
292
@@implementation Point
291
293
// method implementations
292
 
+ new
 
294
+ (id)new
293
295
@{
294
296
  // statements ...
295
297
@}
296
298
 
297
 
+newWithX: (float)x Y: (float)y
 
299
+ (id)newWithX: (float)x Y: (float)y
298
300
@{
299
301
  // statements ...
300
302
@}
301
303
 
302
304
// ...
303
305
 
304
 
- (void) setY: (float)newY
 
306
- (void)setY: (float)newY
305
307
@{
306
308
  // statements ...
307
309
@}
375
377
 
376
378
Typically, a class will also provide one or more @code{initWith...} methods
377
379
for initialization with arguments, and it may optionally also provide
378
 
convenience class methods that act like constructors.  The general approach
 
380
@code{+new} methods and convenience class methods that act like constructors.
 
381
The general approach
379
382
to implementing these is illustrated here for the @code{Point} class.
380
383
 
381
384
@example
382
385
+ new
383
386
@{
384
 
  Point *point = [[self alloc] init];
385
 
    // note "self" refers to the "Point" _class_ object!
386
 
  return AUTORELEASE(point);
 
387
  Point *point;
 
388
 
 
389
  // note "self" refers to the "Point" _class_ object!
 
390
  point = [[self allocWithZone: NSDefaultMallocZone()] init];
 
391
  return point;
387
392
@}
388
393
 
389
394
+ newWithX: (float)x0 Y: (float)y0
390
395
@{
391
 
  Point *point = [[self alloc] initWithX: x Y: y];
 
396
  Point *point;
 
397
 
 
398
  point = [[self allocWithZone: NSDefaultMallocZone()] initWithX: x Y: y];
 
399
  return point;
 
400
@}
 
401
 
 
402
+ point
 
403
@{
 
404
  Point *point;
 
405
 
 
406
  // note "self" refers to the "Point" _class_ object!
 
407
  point = [self new];
 
408
  return AUTORELEASE(point);
 
409
@}
 
410
 
 
411
+ pointWithX: (float)x0 Y: (float)y0
 
412
@{
 
413
  Point *point;
 
414
 
 
415
  point = [self newWithX: x Y: y];
392
416
  return AUTORELEASE(point);
393
417
@}
394
418
 
411
435
@end example
412
436
 
413
437
Notice that, first, the convenience constructors (@code{new} and
414
 
@code{newWithX:Y:}) execute @code{[self alloc]} to begin with.  The
 
438
@code{newWithX:Y:}) execute @code{[self allocWithZone:]} to begin with.  The
415
439
``@code{self}'' here refers to the @i{class} object, since it is used inside a
416
440
@i{class} method.  Thus the effect is the same as if ``@code{[Point alloc]}''
417
 
had been executed in external code.  Second, notice that they autorelease the
418
 
new instance before returning it.  This is to follow the rules of memory
 
441
had been executed in external code.  Second, notice that the other
 
442
convenience constructors (@code{point} and @code{pointWithX:Y:})
 
443
autorelease the new instance before returning it.
 
444
This is to follow the rules of memory
419
445
management discussed in @ref{Objects, earlier, Memory Management}.  Third,
420
446
note that the @code{new..}  methods each call a corresponding @code{init...}
421
447
method.  It is not necessary to maintain such a one to one correspondence but
422
448
it is a common convention to have the convenience implementations rely on
423
 
instance @code{init} methods as shown.
 
449
instance @code{init} methods as shown.  Fourth, note that the use of
 
450
@code{[self allocWithZone: NSDefaultMallocZone()]} rather than
 
451
@code{[self alloc]} is generally unnecessary, but provides a slight
 
452
efficiency gain since @code{+alloc} is implemented by calling
 
453
@code{+allocWithZone:} on the default zone.
424
454
 
425
455
@b{Designated Initializer}
426
456
 
488
518
  self = [[self alloc] init];
489
519
    // note "self" now refers to the new instance!
490
520
  [self setX: 1.0];
491
 
  return AUTORELEASE(self);
 
521
  return self;
492
522
@}
493
523
@end example
494
524