Topic       : The GFA-Basic Compendium
Author      : GFA Systemtechnik GmbH
Version     : GFABasic.HYP v2.98 (12/31/2023)
Subject     : Documentation/Programming
Nodes       : 899
Index Size  : 28056
HCP-Version : 3
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Document not found
@help       : Help
@options    : +g -i -s +z
@width      : 75
@hostname   : STRNGSRV
@hostname   : CAB     
@hostname   : HIGHWIRE
@hostname   : THING   
View Ref-FileQSORT a([s]) [,n[,j%()]]
QSORT s$([s]) [OFFSET o] [WITH i()] [,n[,j%()]]
SSORT a([s]) [,n[,j%()]]
SSORT s$([s]) [OFFSET o] [WITH i()] [,n[,j%()]]

a(): arbitrary array, or string array
i(): integer-array (|, & or %) with at least 256 entries
j%(): 4-byte integer array
s$(): string array
n: iexp
o: iexp
s: +, -, or no sign

You can xSORT string fields with an OFFSET only from version 3.02 on wards.
The OFFSET determines how many characters off the beginning shall not be
considered; e.g.

    DIM a$(256)
    FILES "*.*" TO "LISTE"
    OPEN "I",#1,"LISTE"
    RECALL #1,a$(),-1,x%
    CLOSE #1
    QSORT a$() OFFSET 13,x%
    OPEN "O",#1,"CON:"
    STORE #1,a$(),x%
    CLOSE #1

This program gives the directory as a file "LISTE", with RECALL the array a$()
gets the contents, then the directory is sorted and STOREd to "CON:". By giving
the OFFSET 13 it is not sorted by name but by the length of the files. " " and
"*" and "12345678.123" is skipped.

The instructions SSORT and QSORT allow the elements of an array to be sorted
according to their size. SSORT utilizes the Shellsort and QSORT the Ouicksort.
In the brackets of the array name a plus or minus sign may be inserted, meaning
that the sort is to be done in ascending or descending order respectively. If
neither is specified, the sort by default will be done in ascending order, as
with "+".

The parameter "n" specifies that only the first "n" elements of the array are
to be sorted. If OPTION BASE 0 is active (the default) these are the elements
from 0 to n-1; if OPTION BASE 1 is active then elements from 1 to n are sorted.
If n=-1 then the whole array will be sorted.

When a further integer array is specified as the third parameter, that array
will be sorted along with the first array. Each exchange of elements in the
first array is also carried out in the second. This facility can be used, for
example, if one array contains a sort code, e.g. a post code, and another array
contains related information.

During the sorting of string arrays a sorting criterion can be specified in
form of an array with at least 256 elements by means of WITH. Without
indication of WITH the normal ASCII order is used as a sorting criterion (see
second example).

Examples:

    DIM x%(20)
    PRINT "Unsorted: ";
    FOR i%=0 TO 10
      x%(i%)=RAND(9)+1
      PRINT x%(i%);" ";
    NEXT i%
    PRINT
    '
    QSORT x%(),11
    DIM index%(210)
    PRINT "Descending sort: ";
    FOR i%=0 TO 10
      PRINT x%(i%);" ";
      index%(i%)=i%
    NEXT i%
    PRINT
    '
    SSORT x%(-),11,index%()
    PRINT "Ascending sort: ";
    FOR i%=0 TO 10
      PRINT x%(i%);" ";
    NEXT i%
    PRINT
    PRINT "Sort WITH array: ";
      FOR i%=0 TO 10
      PRINT index%(i%);" ";
    NEXT i%

--> Gives an unsorted field and two sorted series from random numbers. In a
    fourth row the values of a second field that was sorted alongside the first
    one displayed.

Memo: These commands use self modifying code internally and may not work
      correctly on CPUs with caches, such as an 060.