15.3 Return values

Some general conventions for return values are worth mentioning:

• For methods that return an integer, a return value of -1 usually indicates soft method failure.
• For methods that return an integer, a return value of -2 usually indicates hard method failure.
• For methods that return an integer, a return value greater of zero or more usually indicates method success.
• If a method returns an pointer value, NULL usually indicates method failure. Any other result usually indicates method success.

The words “success” and “failure” are heavily overloaded in these documents. But in contexts where our meaning is clear we will usually abbreviate “method success” and “method failure” to “success” and “failure”, respectively.

While these general conventions are a memory aid, there are exceptions, and the programmer must look at the return value summary in the description of every method they use.

As one example of an exception, for certain methods, a return value of -2 is ambiguous: -2 can be both a valid return value for method success, and a potential indication of hard method failure. An example of a method where -2 is ambiguous is marpa_g_rule_rank_set(). See marpa_g_rule_rank_set. In cases like marpa_g_rule_rank_set(), the programmer must distinguish the two return statuses based on the error code.

Whenever a method departs from the general return value conventions, the departure will be detailed in the description of that method. Any departure by a method from the general return value conventions will always be indicated in the return value summary for that method.