Table of Contents

Array sorting and shuffling

These functions will be added in ACSUtils 1.8.0

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.

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.

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.

Example: sorting a simple array of numbers:

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");
}

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

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");
}

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:

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");
}