SYNOPSIS
	mixed *sort_array(mixed *arr, string wrong_order, object|string ob)
	mixed *sort_array(mixed *arr, closure cl)

DESCRIPTION
	Returns an array sorted either by the ordering function
	ob->wrong_order(a, b), or by the closure expression 'cl'.
	If the 'arr' argument equals 0, the result is also 0.
	'ob' is the object in which the ordering function is called
	and may be given as object or by its filename. If omitted, the
	function is called in the current object.

	The elements from the array to be sorted are passed in pairs to
	the function 'wrong_order' as arguments.
	The function should return a positive number if the elements
	are in the wrong order. It should return 0 or a negative
	number if the elements are in the correct order.

EXAMPLES
	To sort an array

	  arr = ({ 3, 8, 1, 3 })

	in ascending order with the help of the ordering function

	  int is_greater (int a, int b) {
	    return a > b;
	  }

	the following uses of sort_array() are equivalent:

	  sort_array(arr, "is_greater", this_object())
	  sort_array(arr, "is_greater")
	  sort_array(arr, #'is_greater)
	  sort_array(arr, #'>)  (this is the preferred variant :-)
	  sort_array(arr, lambda(({'a, 'b}), ({#'>, 'a, 'b})))

	A more complicated example is to sort the array

	  arr = ({ ({ "foo", 3 }), ({ "quux", 1 }), ... })

	in ascending order by the second element of each subarray.
	For this, the ordering function should be like

	  int is_greater (mixed *a, mixed *b) {
	    return a[1] > b[1];
	  }

SEE ALSO
	transpose_array(E), filter_array(E), map_array(E), alists(LPC)
