## SORT Sort

Section: Array Generation and Manipulations

### Usage

Sorts an n-dimensional array along the specified dimensional. The first form sorts the array along the first non-singular dimension.

      B = sort(A)

Alternately, the dimension along which to sort can be explicitly specified

      B = sort(A,dim)

FreeMat does not support vector arguments for `dim` - if you need `A` to be sorted along multiple dimensions (i.e., row first, then columns), make multiple calls to `sort`. Also, the direction of the sort can be specified using the `mode` argument

      B = sort(A,dim,mode)

where `mode = 'ascend'` means to sort the data in ascending order (the default), and `mode = 'descend'` means to sort the data into descending order. When two outputs are requested from `sort`, the indexes are also returned. Thus, for

      [B,IX] = sort(A)
      [B,IX] = sort(A,dim)
      [B,IX] = sort(A,dim,mode)

an array `IX` of the same size as `A`, where `IX` records the indices of `A` (along the sorting dimension) corresponding to the output array `B`. Two additional issues worth noting. First, a cell array can be sorted if each cell contains a `string`, in which case the strings are sorted by lexical order. The second issue is that FreeMat uses the same method as MATLAB to sort complex numbers. In particular, a complex number `a` is less than another complex number `b` if `abs(a) < abs(b)`. If the magnitudes are the same then we test the angle of `a`, i.e. `angle(a) < angle(b)`, where `angle(a)` is the phase of `a` between `-pi,pi`.

### Example

Here are some examples of sorting on numerical arrays.

    --> A = int32(10*rand(4,3))

    A =
      8  9  3
      7  2  1
      3  0  3
      3 10  5

    --> [B,IX] = sort(A)
    B =
      3  0  1
      3  2  3
      7  9  3
      8 10  5

    IX =
     3 3 2
     4 2 1
     2 1 3
     1 4 4

    --> [B,IX] = sort(A,2)
    B =
      3  8  9
      1  2  7
      0  3  3
      3  5 10

    IX =
     3 1 2
     3 2 1
     2 1 3
     1 3 2

    --> [B,IX] = sort(A,1,'descend')
    B =
      8 10  5
      7  9  3
      3  2  3
      3  0  1

    IX =
     1 4 4
     2 1 1
     3 2 3
     4 3 2

Here we sort a cell array of strings.

    --> a = {'hello','abba','goodbye','jockey','cake'}

    a =
     [hello] [abba] [goodbye] [jockey] [cake]

    --> b = sort(a)

    b =
     [abba] [cake] [goodbye] [hello] [jockey]