Subject: another revision of the documentation for "sort"
From: Robert Dodier
Date: Sun, 20 Nov 2011 23:05:33 -0700
FWIW. I've pushed the following. I tried to take into account
various comments made about previous versions.
I've tried to apply the following general guidelines which I have
also applied (inconsistently) to other documentation:
* separate exposition and examples
* examples recapitulate exposition
* order exposition by decreasing importance
* be precise, be complete, get to the point
Doubtless if you look hard enough you will see that I've violated my
own guidelines.
I apologize in advance.
Thanks a lot to everyone who has contributed to the discussion.
HTH
Robert Dodier
PS.
-- Function: sort (<L>, <P>)
-- Function: sort (<L>)
Sorts a list <L> according to a predicate `P' of two arguments
which defines a strict weak order on the elements of <L>. If
`<P>(a, b)' is `true', then `a' appears before `b' in the result.
If neither `<P>(a, b)' nor `<P>(b, a)' are `true', then `a' and
`b' are equivalent, and appear in the result in the same order as
in the input. That is, `sort' is a stable sort.
If `<P>(a, b)' and `<P>(b, a)' are both `true' for some elements
of <L>, then <P> is not a valid sort predicate, and the result is
undefined. If `<P>(a, b)' is something other than `true' or
`false', `sort' signals an error.
The predicate may be specified as the name of a function or binary
infix operator, or as a `lambda' expression. If specified as the
name of an operator, the name must be enclosed in double quotes.
The sorted list is returned as a new object; the argument <L> is
not modified.
`sort(<L>)' is equivalent to `sort(<L>, orderlessp)'.
The default sorting order is ascending, as determined by
`orderlessp'. The predicate `ordergreatp' sorts a list in
descending order.
All Maxima atoms and expressions are comparable under `orderlessp'
and `ordergreatp'.
Operators `<' and `>' order numbers, constants, and constant
expressions by magnitude. Note that `orderlessp' and
`ordergreatp' do not order numbers, constants, and constant
expressions by magnitude.
`ordermagnitudep' orders numbers, constants, and constant
expressions the same as `<', and all other elements the same as
`orderlessp'.
Examples:
`sort' sorts a list according to a predicate of two arguments
which defines a strict weak order on the elements of the list.
(%i1) sort ([1, a, b, 2, 3, c], 'orderlessp);
(%o1) [1, 2, 3, a, b, c]
(%i2) sort ([1, a, b, 2, 3, c], 'ordergreatp);
(%o2) [c, b, a, 3, 2, 1]
The predicate may be specified as the name of a function or binary
infix operator, or as a `lambda' expression. If specified as the
name of an operator, the name must be enclosed in double quotes.
(%i1) L : [[1, x], [3, y], [4, w], [2, z]];
(%o1) [[1, x], [3, y], [4, w], [2, z]]
(%i2) foo (a, b) := a[1] > b[1];
(%o2) foo(a, b) := a > b
1 1
(%i3) sort (L, 'foo);
(%o3) [[4, w], [3, y], [2, z], [1, x]]
(%i4) infix (">>");
(%o4) >>
(%i5) a >> b := a[1] > b[1];
(%o5) a >> b := a > b
1 1
(%i6) sort (L, ">>");
(%o6) [[4, w], [3, y], [2, z], [1, x]]
(%i7) sort (L, lambda ([a, b], a[1] > b[1]));
(%o7) [[4, w], [3, y], [2, z], [1, x]]
`sort(<L>)' is equivalent to `sort(<L>, orderlessp)'.
(%i1) L : [a, 2*b, -5, 7, 1 + %e, %pi];
(%o1) [a, 2 b, - 5, 7, %e + 1, %pi]
(%i2) sort (L);
(%o2) [- 5, 7, %e + 1, %pi, a, 2 b]
(%i3) sort (L, 'orderlessp);
(%o3) [- 5, 7, %e + 1, %pi, a, 2 b]
The default sorting order is ascending, as determined by
`orderlessp'. The predicate `ordergreatp' sorts a list in
descending order.
(%i1) L : [a, 2*b, -5, 7, 1 + %e, %pi];
(%o1) [a, 2 b, - 5, 7, %e + 1, %pi]
(%i2) sort (L);
(%o2) [- 5, 7, %e + 1, %pi, a, 2 b]
(%i3) sort (L, 'ordergreatp);
(%o3) [2 b, a, %pi, %e + 1, 7, - 5]
All Maxima atoms and expressions are comparable under `orderlessp'
and `ordergreatp'.
(%i1) L : [11, -17, 29b0, 9*c, 7.55, foo(x, y), -5/2, b + a];
5
(%o1) [11, - 17, 2.9b1, 9 c, 7.55, foo(x, y), - -, b + a]
2
(%i2) sort (L, orderlessp);
5
(%o2) [- 17, - -, 7.55, 11, 2.9b1, b + a, 9 c, foo(x, y)]
2
(%i3) sort (L, ordergreatp);
5
(%o3) [foo(x, y), 9 c, b + a, 2.9b1, 11, 7.55, - -, - 17]
2
Operators `<' and `>' order numbers, constants, and constant
expressions by magnitude. Note that `orderlessp' and
`ordergreatp' do not order numbers, constants, and constant
expressions by magnitude.
(%i1) L : [%pi, 3, 4, %e, %gamma];
(%o1) [%pi, 3, 4, %e, %gamma]
(%i2) sort (L, ">");
(%o2) [4, %pi, 3, %e, %gamma]
(%i3) sort (L, ordergreatp);
(%o3) [%pi, %gamma, %e, 4, 3]
`ordermagnitudep' orders numbers, constants, and constant
expressions the same as `<', and all other elements the same as
`orderlessp'.
(%i1) L : [%i, 1+%i, 2*x, minf, inf, %e, sin(1), 0, 1, 2, 3,
1.0, 1.0b0];
(%o1) [%i, %i + 1, 2 x, minf, inf, %e, sin(1), 0, 1, 2, 3, 1.0,
1.0b0]
(%i2) sort (L, ordermagnitudep);
(%o2) [minf, 0, sin(1), 1, 1.0, 1.0b0, 2, %e, 3, inf, %i,
%i + 1, 2 x]
(%i3) sort (L, orderlessp);
(%o3) [0, 1, 1.0, 2, 3, %e, %i, %i + 1, inf, minf, sin(1),
1.0b0, 2 x]