Class and Instance Methods

Methods are normal C functions which are registered as methods at runtime. Methods can be send to classes as well as to instances, both types of methods basically have the same format:

MY_CLASS *my_class_method_name(parm1, parm2, ...)
{
  MY_CLASS *self;

  self = (MY_CLASS *)START_METHOD(METHOD_TYPE);
  ASSURE(self, "", END_METHOD(NULL));

  ...

  END_METHOD(self);
}

The name of the method function is composed of the name of the class the method belongs to followed by a _ and the method name itself.

Class and instance methods are distinguished by the argument of the START_METHOD macro. For METHOD_TYPE there are three possibilities:

G_INSTANCE:

The object this method is send to has to be an instance of class class or of one of its subclasses. In this case TYPE stands for the typedef of the struct defining class class.

G_CLASS:

The method has to be send to class class or one of its subclasses. The object returned by START_METHOD then has type CLASS *. Class methods are for example used to create new instances.

G_CLASS|G_INSTANCE:

This is the special case of a method that can be send both to a class or an instance. You have to decide yourself if the method was called on a class or an instance by checking the object returned by START_METHOD against the class pointer of the object:

      if(self == (MY_CLASS *)self->class) {
        CLASS *class = (CLASS *)self;
        /* called on class */
        ...
      } else {
        /* called on instance */
        ...
      }

This type of mixed method should only be used if you really need a method with the same name on both the class and instances of the class.

Writing a method function is like writing a normal function. The only differences are that the object the method is applied to enters the method via START_METHOD and is returned by END_METHOD. Between these calls the method's object can be manipulated as usual. The parameters of the method call are passed to the method function like to a normal C function, but be aware of the automatic type conversions described at the end of section 5.2.1.

Of course the object of a method may have any valid C name, but calling it self makes things easier -- you immediatedly know which object you are working on when looking at some part of the method code.

The value returned by START_METHOD should be tested, because it could be NULL if an instance method was called on a class or vice versa. This can be done with the ASSURE macro which is described in section 5.4.3 below. You don't have to print an error message in the case because this will be done by the START_METHOD macro, therefore the error string is empty.

A method function may return any pointer with END_METHOD, not just the one obtained by START_METHOD, an example where these objects differ is the method "new-instance". The return type of a method is defined as the return type of the method function, in case of an error methods always should return NULL so that the failure can be detected by the caller.

To avoid trouble with the GRAPE function you must start all methods with START_METHOD, even if the method's object is not needed for the method. And never use return instead of END_METHOD to end a method function, this will confuse the internal GRAPE stack.