REFERENCE COUNTING CONVENTIONS
------------------------------

In order to avoid losing track of reference counts, functions should
follow certain conventions according to their behavior.  The following
list describes several types of functions and their behaviors:

Constructors: Functions which construct new values should assign them
	      a reference count of one, so that the calling function
	      is responsible for discarding the value.

Constructors/retrievers: Functions which construct new values under
			 some circumstances but retrieve values under
			 other circumstances should assign new objects
			 a reference count of one and should increase
			 the reference count of existing objects, so
			 that the calling function is responsible for
			 discarding the value.

Retrievers: Functions which merely retrieve values should not increase
	    the reference count, so that the calling function need not
	    discard them.

Assignment: Functions which merely assign values to structures should
	    not increase the reference count, since they are simply
	    abbreviations for assignment.

Storage: Anything more complicated than a simple assignment function
	 should update the reference counts of any objects it stores.

Mutators: Functions which take a value and return a modified value
	  should claim the reference count on the value so that they
	  can operate more efficiently.

Users: Functions which look at values without modifying them should
       generally not modify the reference count on the data they take
       as arguments.

Exceptions to these conventions (e.g. user functions which mutate
values for efficiency but do not return new values of the same type)
should be clearly marked, preferrably by name (e.g.
add_and_discard_string()), and should not have external linkage.