S3L_sort, S3L_sort_up, S3L_sort_down, S3L_sort_detailed_up, S3L_sort_detailed_down

Description

The S3L_sort function sorts the elements of a one-dimensional array in ascending order.

S3L_sort_up and S3L_sort_down sort the elements of one-dimensional or multidimensional array in ascending and descending order, respectively.

S3L_sort is a special case of S3L_sort_up.

When A is one-dimensional, the result is a vector that contains the same elements as A, but arranged in ascending order (S3L_sort or S3L_sort_up) or descending order. For example, if A contains

Example 8-113

   _                                 _
  | 7   2   4   3   1   8   6   9   5 |
   -                                 -

calling S3L_sort or S3L_sort_up would produce the result

Example 8-114

   _                                 _
  | 1   2   3   4   5   6   7   8   9 |
   -                                 -

If A is multidimensional, the elements are sorted into an index-based sequence, starting with the first row-column index and progressing through the row indices first before advancing to the next column index position.

For example if A contains

Example 8-115

   _         _
  | 6   2   7 |
  |           |
  | 1   4   3 |
  |           |
  | 9   5   8 |
   -         -

S3L_sort_up would produce the result

Example 8-116

   _         _
  | 1   4   7 |
  |           |
  | 2   5   8 |
  |           |
  | 3   6   9 |
   -         -

and S3L_sort_down would produce the result

Example 8-117

   _         _
  | 9   6   3 |
  |           |
  | 8   5   2 |
  |           |
  | 7   4   1 |
   -         -

S3L_sort_detailed_up and S3L_sort_detailed_down sort the elements of one-dimensional or multidimensional arrays in ascending and descending order along the axis specified by the axis argument.

The value of the axis argument is language dependent. For C/C++ applications, it must be zero-based and for F77/F90 applications, it must be one-based.

If the array referenced by A contains

Example 8-118

   _         _
  | 6   2   7 |
  |           |
  | 1   4   3 |
  |           |
  | 9   5   8 |
   -         -

and a C program calls S3L_sort_detailed_up with axis = 0, upon completion, A will contain

Example 8-119

   _         _
  | 1   2   3 |
  |           |
  | 6   4   7 |
  |           |
  | 9   5   8 |
   -         -

Or, if a C program calls S3L_sort_detailed_up with axis = 1, upon completion, A will contain

   _         _
  | 2   6   7 |
  |           |
  | 1   3   4 |
  |           |
  | 5   8   9 |
   -         -

If these calls were made from an F77 or F90 program, the axis values would need to be one greater (that is, 1 and 2, respectively) to achieve the same results.

Syntax

The C and Fortran syntax for these functions are shown below.

C/C++ Syntax

Example 8-120

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_sort(A)
S3L_sort_up(A)
S3L_sort_down(A)
S3L_sort_detailed_up(A, axis)
S3L_sort_detailed_down(A, axis)
    S3L_array_t       A
    int               axis

F77/F90 Syntax

Example 8-121

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_sort(A, ier)
S3L_sort_up(A, ier)
S3L_sort_down(A, ier)
S3L_sort_detailed_up(A, axis, ier)
S3L_sort_detailed_down(A, axis, ier)
    integer*8         A
    integer*4         axis
    integer*4         ier

where <type> is real*4 or real*8 for both C/C++ and F77/F90.

Input

• A - For S3L_sort, A must be a one-dimensional array. For S3L_sort_up, S3L_sort_down, S3L_sort_detailed_up, and S3L_sort_detailed_down, A can be one-dimensional or multidimensional.

• axis - Used with S3L_sort_detailed_up and S3L_sort_detailed_down to specify which axis of A is to be sorted. If A is one-dimensional, axis must be zero (for C/C++) or 1 (for F77/F90). It may not be used in S3L_sort, S3L_sort_up, or S3L_sort_down calls.

Output

These functions use the following arguments for output:

• A - On output, A contains the sorted array.

• ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, these functions return S3L_SUCCESS.

These functions all check the arrays they accept as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following condition will cause the functions to terminate and return the associated code:

• S3L_ERR_ARG_DTYPE - The type of the array is invalid. It must be one of: S3L_integer, S3L_long_integer, S3L_float or S3L_double.

• S3L_ERR_ARG_AXISNUM - The axis argument has an invalid value. The correct values for axis are

  • 0 <= axis < rank of a (C/C++)

  • 0 < axis <= rank of a (F77/F90)

Examples

../examples/s3l/sort/sort1.c
../examples/s3l/sort/ex_sort2.c
../examples/s3l/sort-f/sort1.f

Related Functions

S3L_grade_up(3)
S3L_grade_detailed_down(3)
S3L_grade_detailed_up(3)