The SDL Component Suite is an industry leading collection of components supporting scientific and engineering computing. Please visit the SDL Web site for more information....


Declaration: [1] function SortIntoArray (ArrayAdr: pointer; LengArray: longint; TypArray: TVarKind; value: pointer; Ascending: boolean; duplicates: boolean): longint;
[2] function SortIntoArray (SArray: array of integer; value: integer; Ascending: boolean; Duplicates: boolean): longint;
[3] function SortIntoArray (SArray: array of single; value: single; Ascending: boolean; Duplicates: boolean): longint;
[4] function SortIntoArray (SArray: array of double; value: double; Ascending: boolean; Duplicates: boolean): longint;{Pascal}
[2] int __fastcall SortIntoArray(double * SArray, const int SArray_Size, double value, bool Ascending, bool Duplicates);
[3] int __fastcall SortIntoArray(float * SArray, const int SArray_Size, float value, bool Ascending, bool Duplicates);
[4] int __fastcall SortIntoArray(int * SArray, const int SArray_Size, int value, bool Ascending, bool Duplicates); {C++}

Sometimes it is necessary to insert new values into an already sorted numeric array. The routine SortIntoArray offers this type of processing. First, it calculates the would-be position of the new element within the sorted array. If this position is within the limits of the sorted array, the routine shifts all values after the calculated position back and inserts the new value there. The following parameters are needed for a call to SortIntoArray.

ArrayAdr is a pointer to the sorted array. This array must be declared as a one-dimensional numeric array. The array elements may be of type integer, longint, or real.

LengArray determines the length of the sorted array (the number of elements of this array). If only part of the array is to be sorted, LengArray can be reduced appropriate. ATTENTION ! If LengArray is set to a value beyond the declared size of the array this will lead to unpredictable errors, since neighboring variables will be overwritten.

The parameter TypArray specifies the type of the elements of the arrays well as the type of the values to be sorted into the array. The user should be aware that a wrong designation of the type of the array elements leads to severe errors and can cause a system crash. The following types are valid: inum (integer), lnum (longint), snum (single), dnum (double), and rnum (real), the types strg (string) and bool (boolean) are not supported.

As an alternative to version [1] you may use the simpler versions [2], [3], and [4] for integer, single, or double precision arrays, respectively. Version [1] is only available for the Win32 environment, but not for .NET. The parameter SArray is an open array of integer, single, or double precision values.

In version [1] the pointer value holds the address of the variable whose value should be inserted. This variable has to be of the same type as the elements of the array. For versions [2]..[4] the parameter value contains the value to be sorted into the array.

The parameter Ascending specifies whether the array should be sorted by ascending (TRUE) or descending (FALSE) values.

If the parameter duplicates is set TRUE values will be inserted, even if the same value is already stored in the array.

The function SortIntoArray returns the index of the inserted value (1..LengArray for version [1], 0..High(SArray) for versions[2]..[4]). If the number could not be inserted SortIntoArray returns a zero value for version [1] and a value of -1 for the other versions.

Hint 1: The should take notice of the fact that the routine SortIntoArray can insert the new value only if the first value of the array is below (Ascending = TRUE) or above (Ascending = FALSE) the new value. This is especially important for the correct initialization of an array.

Hint 2: The function SortIntoArray can be used to create an ordered list of minimum or maximum values of a larger list of values.

Hint 3: The declaration of the versions [2]..[4] of SortIntoArray in C++ slightly differs from the Pascal declaration (note the extra parameter SArray_Size which specifies the highest index of the SArray array).

Hint 4: Due to a compiler bug, overloading with variable dynamic arrays does not function correctly under Delphi 5. In order to cope with this situation, the four overloaded versions have been assigned individual names under Delphi 5: [1] = SortIntoArray, [2] = SortIntoArrayInteger, [3] = SortIntoArraySingle, [4] = SortIntoArrayDouble.


Last Update: 2012-Okt-20