NAME
	sort_array - sort an array through a specific sort function

SYNOPSIS
	mixed *sort_array(mixed *array, void|function|string sortfunc,
			  void|string|object sortob)

DESCRIPTION
	Sorts an array. By default, it sorts string alphabetically or integers
	numerically, but you can also make your own sort function. To make a
	sort function, it must have the following header:

	    int sort_func(mixed a, mixed b)

	that returns the following values:

	    < 0  when  a < b      Note that a<b, a=b and a>b can be according
	    = 0  when  a = b      to any definition you fancy. If a and b are
	    > 0  when  a > b      are objects, it would we weight, value ...

ARGUMENTS
	array    - the array of whatever you want to sort
	sortfunc - the custom function to sort the value with, if any. It is
		   recommended to use a function reference, and not the string
		   reference, which is only kept for backward compatibility.
		   Note the sortfunc may not be an efun.
	sortob   - kept for backward compatibility only with string reference
		   sortfunc.

HINT
	Since the custom routine only has to return positive, negative, or 0,
	we can make a very short routine in case we're sorting objects, based
	on some criterion:

	int sort_ascending(object a, object b) { return a->age() - b->age(); }
	int sort_descending(object a, object b) { return b->age() - a->age(); }

WARNING
	Note that sort_array() will modify the original array that was passed
	through the header and return a pointer to the same! If you don't want
	this, use secure_var() on the argument before calling sort_array().

	int *a = ({ 4, 1, 3, 2 });
	int *b = sort_array(a); b[2] = 5;
	Now the value of a is ({ 1, 2, 5, 4 }); 
