Allocation of Return Values

There has been some confusion in the past over which functions allocate their return values and which functions return pointers to existing data. As of the Version 7 release, we have taken care to keep the treatment of return values consistent. For example, all functions that return strings now return “const char *” references to Alias data. We believe this approach to be more general--it does not force the developer to perform extra memory management if it is not necessary. If this returned string is required for future reference, then it is up to the developer to make a copy.

A Few Simple Rules for Return Values

While the allocation of return values may change and although there may be some exceptional cases, here are some rules of thumb to remember.

All methods that return strings return a const char * reference that is not allocated.
The downcasting methods in AlObject (as*Ptr) do not allocate their return values. They simply act as a safe type cast to the derived type.
The AlObjects passed to an AlIterator function are effectively not allocated. While they may still be allocated internally, the developer need not, and should not, perform any memory management on them - the applyIterator method handles that. If the iterator needs to return a pointer to a wrapper object it should copy it (that is, use the copyWrapper method).
The destructive methods (methods whose names end in “D”) do not perform any memory management. If they succeed, they transform the passed in object in place. If they fail, they do nothing to the passed in object.
Otherwise, any other method that returns a pointer to an object derived from AlObject allocates its return value. If this return value is not later deallocated, it will cause a memory leak.

It is important to remember that return values will point to internal Alias objects that may change. For example, the return of an Alias object’s name may change due to an action performed in the interactive package.