## 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 =
      <int32>  - size: [4 3]

    Columns 1 to 3
     8  3  7
     5  3  8
     6  5  1
     7  3  5
    --> [B,IX] = sort(A)
    B =
      <int32>  - size: [4 3]

    Columns 1 to 3
     5  3  1
     6  3  5
     7  3  7
     8  5  8
    IX =
      <int32>  - size: [4 3]

    Columns 1 to 3
     2  1  3
     3  2  4
     4  4  1
     1  3  2
    --> [B,IX] = sort(A,2)
    B =
      <int32>  - size: [4 3]

    Columns 1 to 3
     3  7  8
     3  5  8
     1  5  6
     3  5  7
    IX =
      <int32>  - size: [4 3]

    Columns 1 to 3
     2  3  1
     2  1  3
     3  2  1
     2  3  1
    --> [B,IX] = sort(A,1,'descend')
    B =
      <int32>  - size: [4 3]

    Columns 1 to 3
     8  5  8
     7  3  7
     6  3  5
     5  3  1
    IX =
      <int32>  - size: [4 3]

    Columns 1 to 3
     1  3  2
     4  1  1
     3  2  4
     2  4  3

Here we sort a cell array of strings.

    --> a = {'hello','abba','goodbye','jockey','cake'}
    a =
      <cell array> - size: [1 5]

    Columns 1 to 3
     hello    abba    goodbye

    Columns 4 to 5
     jockey    cake
    --> b = sort(a)
    b =
      <cell array> - size: [1 5]

    Columns 1 to 3
     abba    cake    goodbye

    Columns 4 to 5
     hello    jockey