====== Array sorting and shuffling ======

<note warning>These functions will be added in ACSUtils 1.8.0</note>

Array sorting and shuffling functions use script names as callbacks.

===== SortArray =====

''void SortArray(int begin, int end, str lt, str swap)''

Sorts an array with indices in range [begin, end). ''lt'' and ''swap'' are names of scripts that the function will call.

  * ''script "lt" (int a, int b)'' must return the result of ''array[a] < array[b]'' using [[zdoom>SetReturnValue]]. If you return ''array[a] > array[b]'', sorting order is reversed.
  * ''script "swap" (int a, int b)'' must swap ''array[a]'' with ''array[b]''.

The sorted array may actually be an array of objects with multiple fields. ''lt'' can implement multi-field sorting. ''swap'' can swap all fields in the two array cells.

<note important>''SortArray'' can sort up to ~2000 elements before hitting ZDoom's 2 million instructions per tic runaway limit. Maximum element count may depend on callback complexity and the initial state of the array.</note>

Example: sorting a simple array of numbers:

<code>
int array[10];

script "compare_two_elements" (int a, int b)
{
    SetResultValue(array[a] < array[b]);
}

script "swap_two_elements" (int a, int b)
{
    int temp = array[a];
    array[a] = array[b];
    array[b] = temp;
}

function void SortTheArray(void)
{
    SortArray(0, 10, "compare_two_elements", "swap_two_elements");
    
    // You can also sort sub-arrays:
    SortArray(3, 8, "compare_two_elements", "swap_two_elements");
}
</code>

Example: making a scoreboard sorted by score (uses [[swap|swap()]] for readability):

<code>
int PlayerNumbers[MAX_PLAYERS];
int PlayerScores[MAX_PLAYERS];
int NumPlayers;

script "lt" (int a, int b)
{
    if (PlayerScores[a] == PlayerScores[b])
    {
        // Scores are same, sort by name then
        if (StrCmp(PlayerName(PlayerNumbers[a]), PlayerName(PlayerNumbers[b]) == -1);
            return true;
    }
        
    // Using > instead of < reverses sorting by score
    return PlayerScores[a] > PlayerScores[b];
}

script "swap" (int a, int b)
{
    swap(PlayerNumbers[a], PlayerNumbers[b]);
    Players[a] = r1;
    Players[b] = r2;
    
    swap(PlayerScores[a], PlayerScores[b]);
    PlayerScores[a] = r1;
    PlayerScores[b] = r2;
}

function void BuildScoreboard(void)
{
    // Clear scoreboard
    NumPlayers = 0;

    // Fill scoreboard without sorting
    for (int player = 0; player < MAX_PLAYERS; player++)
    {
        if (PlayerInGame(player))
            continue;
        PlayerNumbers[NumPlayers] = player;
        PlayerScores[NumPlayers] = GET_PLAYER_SCORE(player);
        NumPlayers++;
    }
    
    // Sort it by score
    SortArray(0, NumPlayers, "lt", "swap");
}
</code>

===== ShuffleArray =====

''void ShuffleArray(int begin, int end, str swap)''

Randomly reorders elements of an array with indices in range [begin, end). ''swap'' is the name of a script ''script (int a, int b)'' that must swap ''array[a]'' with ''array[b]''.

Example:

<code>
int array[10];

script "swap" (int a, int b)
{
    int temp = array[a];
    array[a] = array[b];
    array[b] = temp;
}

function void ShuffleTheArray(void)
{
    ShuffleArray(0, 10, "swap");
}
</code>