The function `sort` returns an index list:

list = sort(x); |

The list has the same length as the input vector `x`, and list(1) is
the index of the smallest element of `x`, list(2) the index of the
next smallest, and so on. Thus, `x(list)` will be `x` sorted
into ascending order.

By returning an index list instead of the sorted array, `sort`
simplifies the co-sorting of other arrays. For example, consider a
series of elaborate experiments. On each experiment, thermonuclear
yield and laser input energy are measured, as well as fuel mass. These
might reasonably be stored in three vectors `yield`, `input`,
and `mass`, each of which is a 1D array with as many elements as
experiments performed. The order of the elements in the arrays maight
naturally be the order in which the experiments were performed, so that
`yield(3)`, `input(3)`, and `mass(3)` represent the third
experiment. The experiments can be sorted into order of increasing
gain (yield per unit input energy) as follows:

list = sort(yield/input); yield = yield(list); input = input(list); mass = mass(list); |

The inverse list, which will return them to their orginal order, is:

invlist = list; /* faster than array(0, dimsof(list)) */ invlist(list) = indgen(numberof(list)); |

The `sort` function actually sorts along only one index of a
multi-dimensional array. The dimensions of the returned list are the
same as the dimensions of the input array; the values are indices
relative to the beginning of the entire array, not indices for the
dimension being sorted. Thus, `x(sort(x))` is the array `x`
sorted so that the elements along its first dimension are in ascending
order. In order to sort along another dimension, pass `sort` a
second argument – `x(sort(x,2))` will be `x` sorted into
increasing order along its second dimension, `x(sort(x,3))` along
its third dimension, and so on.

A related function is `median`. It takes one or two arguments, just
like `sort`, but its result – which is, of course, the median
values along the dimension being sorted – has one fewer dimension than
its input.