46.9. $reclaim

$reclaim is a low-level STRING space manipulation PROCEDURE that can be used to enhance efficiency in certain situations. However, incautious use of $reclaim can corrupt MAINSAIL's STRING space; this PROCEDURE should be used only by those who have a good understanding of what it does.

$reclaim reclaims the characters of a STRING s if s is at the top of the area ap's STRING space; otherwise, it does nothing.

The behavior of $reclaim is undefined unless it conforms to the following restrictions:

• The STRING s must have been constructed using a system PROCEDURE that does not take any STRINGs as USES or MODIFIES arguments (such as non-STRING forms of cvs). Do not call $reclaim if s has been constructed with, for example, the concatenation operator ($concat), STRING forms of cWrite, STRING forms of scan, or $dup, since all of these take STRINGs as USES or MODIFIES arguments. If s has been constructed with a PROCEDURE that takes a STRING USES or MODIFIES argument, it is possible to free STRINGs that were not intended, thereby corrupting STRING space.

• s must not have been obtained as the return value from cvcs.

• The STRING s must be in a user-created area, not in $defaultArea or in any other area created by the runtime system. System PROCEDUREs may put STRINGs in $defaultArea (or other system areas, if any) at unpredictable times, and reclaiming these STRINGs may have undefined effects.

Example:

s := cvs(lr,'0,myArea);
...
$reclaim(s,myArea);
    # frees storage if s is at top of myArea's
    # STRING space