The `sort()` function performs an in-place sorting on the given array,
invoking the specified callback (if any) to compare items during the
sort process.

If no callback is given or if the callback argument is `null`, a default
comparator function is used which will sort number values numerically
and all other value types lexically.

Returns the sorted input array.

Returns `null` if the given input array value is not an array.


-- Testcase --
{%
	print(join("\n", [
		// default numeric sort
		sort([ 6, 4.3, 1, 45, 3.01, 2 ]),

		// default lexical sort
		sort([ "qrx", "bar", "foo", "abc" ]),

		// default lexical sort due to implicit stringification
		sort([ true, false, null, 1, "2b" ]),

		// sort with custom callback (by word length)
		sort([ "apple", "pear", "banana", "grapefruit" ], (a, b) => length(a) - length(b)),

		// sort with custom callback (by type, then value)
		sort([ 4, 1, 9, 2, "x", "a", "q", "b" ], (a, b) => {
			let t1 = type(a), t2 = type(b);
			if (t1 < t2)
				return -1;
			else if (t1 > t2)
				return 1;

			if (a < b)
				return -1;
			else if (a > b)
				return 1;

			return 0;
		}),

		// default lexical object key sort
		sort({ qrx: 1, foo: 2, abc: 3 }),

		// object sort with custom callback (by value)
		sort({ a: 5, b: 3, c: 2, d: 4, e: 1 }, (k1, k2, v1, v2) => v1 - v2),

		// object sort with custom callback (by key length)
		sort({ "Bean": true, "Orange": true, "Apple": true }, (k1, k2) => length(k1) - length(k2))
	]), "\n");
%}
-- End --

-- Expect stdout --
[ 1, 2, 3.01, 4.3, 6, 45 ]
[ "abc", "bar", "foo", "qrx" ]
[ 1, "2b", false, null, true ]
[ "pear", "apple", "banana", "grapefruit" ]
[ 1, 2, 4, 9, "a", "b", "q", "x" ]
{ "abc": 3, "foo": 2, "qrx": 1 }
{ "e": 1, "c": 2, "b": 3, "d": 4, "a": 5 }
{ "Bean": true, "Apple": true, "Orange": true }
-- End --


Supplying an invalid callback will trigger an exception.

-- Testcase --
{%
	sort([3, 1, 2], "not_a_function")
%}
-- End --

-- Expect stderr --
Type error: left-hand side is not a function
In line 2, byte 34:

 `    sort([3, 1, 2], "not_a_function")`
  Near here --------------------------^


-- End --


Supplying a non-array, non-object value will yield `null`.

-- Testcase --
{%
	printf("%.J\n", sort("not_an_array", function(a, b) { return a - b }));
%}
-- End --

-- Expect stdout --
null
-- End --


Exceptions in the callback terminate the sort process and are
propagated to the calling context.

-- Testcase --
{%
	sort([ 1, 2, 3 ], function() { die() });
%}
-- End --

-- Expect stderr --
Died
In [anonymous function](), line 2, byte 37:
  called from function sort ([C])
  called from anonymous function ([stdin]:2:40)

 `    sort([ 1, 2, 3 ], function() { die() });`
  Near here -----------------------------^


-- End --