Fossil Logic

Sort Algorithm

Table Of Contents

The Fossil Algorithm Sort module provides a runtime-configurable interface for sorting arrays of arbitrary data types using string-identified algorithms, order modes, and type definitions. It supports a wide range of algorithms—including merge, heap, insertion, shell, bubble, counting, and radix—automatically selecting compactors based on the given type identifier. Sorting is performed in-place, with configurable ascending or descending order, and the "auto" algorithm defaults to merge sort. Error codes clearly indicate invalid inputs, unsupported types, or unknown algorithm requests. Additional utility functions allow callers to query type support and retrieve element sizes, while the accompanying C++ wrapper presents a modern, minimal API built around std::string and static helper methods.

Code reference for C and C++ APIs for the respective Fossil Logic library.

HEADER REFERENCE #

#ifndef FOSSIL_ALGORITHM_SORT_H
#define FOSSIL_ALGORITHM_SORT_H

#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

// ======================================================
// Fossil Algorithm Sort — Exec Interface
// ======================================================

/**
 * @brief Executes a sorting operation using string-based configuration.
 *
 * This function provides a flexible runtime interface for sorting arrays of
 * various types, using the algorithm, order, and type specified by string
 * identifiers. It supports multiple algorithms (merge, heap, insertion, shell,
 * bubble, counting, radix) and both ascending and descending order.
 *
 * Internally, the function dispatches to the appropriate algorithm stub based
 * on the algorithm_id string. Type safety is managed via type_id and a
 * comparator function. For unsupported types or algorithms, error codes are
 * returned.
 *
 * Notes:
 *   - "auto" algorithm_id defaults to merge sort.
 *   - Counting sort only supports "u8" type; radix sort only supports "u32".
 *   - Returns negative error codes for invalid input, unknown type, or unknown algorithm.
 *   - Sorting is performed in-place.
 *
 * Example:
 * @code
 * float values[] = { 3.2f, 1.5f, 9.1f };
 * fossil_algorithm_sort_exec(values, 3, "f32", "merge", "asc");
 * @endcode
 *
 * @param base Pointer to the array to sort.
 * @param count Number of elements in the array.
 * @param type_id String identifier for data type (e.g., "i32", "f64", "cstr").
 * @param algorithm_id String identifier for sorting algorithm ("auto", "merge", etc.).
 * @param order_id String identifier for sort order ("asc", "desc").
 * @return int Status code:
 *   - `0` on success
 *   - `-1` for invalid input
 *   - `-2` for unknown type or comparator
 *   - `-3` for unknown algorithm
 *   - Other negative values for algorithm-specific errors
 */
int fossil_algorithm_sort_exec(
    void *base,
    size_t count,
    const char *type_id,
    const char *algorithm_id,
    const char *order_id
);

// ======================================================
// Extended Utility API (optional future additions)
// ======================================================

/**
 * @brief Returns the byte size of a type based on its string identifier.
 *
 * @param type_id Type identifier (e.g., "i32", "f64", "cstr").
 * @return size_t Size of the type in bytes, or 0 if unknown.
 */
size_t fossil_algorithm_sort_type_sizeof(const char *type_id);

/**
 * @brief Checks whether the given type identifier is supported.
 *
 * @param type_id Type identifier string.
 * @return bool True if supported, false otherwise.
 */
bool fossil_algorithm_sort_type_supported(const char *type_id);

#ifdef __cplusplus
}

#include <string>

namespace fossil {

    namespace algorithm {

        /**
         * @brief RAII-friendly C++ wrapper for Fossil sorting algorithms.
         *
         * Provides static methods to sort arrays using various algorithms.
         * All methods are thin wrappers around the C API, accepting raw pointers
         * and sorting options. Default options are used if none are provided.
         *
         * Usage:
         *   - Pass a pointer to the array, element count, element size, comparator, and options.
         *   - Sorting is performed in-place.
         *   - Returns 0 on success, non-zero on error.
         */
        class Sort
        {
        public:
            /**
             * @brief Sorts an array using the Fossil C API.
             *
             * @param base Pointer to the array to sort.
             * @param count Number of elements in the array.
             * @param type_id String identifier for data type (e.g., "i32", "f64", "cstr").
             * @param algorithm_id String identifier for sorting algorithm ("auto", "quick", "merge", etc.).
             * @param order_id String identifier for sort order ("asc", "desc").
             * @return int Status code (0 on success, negative on error).
             */
            static int exec(
            void *base,
            size_t count,
            const std::string &type_id,
            const std::string &algorithm_id = "auto",
            const std::string &order_id = "asc"
            )
            {
            return fossil_algorithm_sort_exec(
                base,
                count,
                type_id.c_str(),
                algorithm_id.c_str(),
                order_id.c_str()
            );
            }

            /**
             * @brief Returns the byte size of a type based on its string identifier.
             *
             * @param type_id Type identifier (e.g., "i32", "f64", "cstr").
             * @return size_t Size of the type in bytes, or 0 if unknown.
             */
            static size_t type_sizeof(const std::string &type_id)
            {
            return fossil_algorithm_sort_type_sizeof(type_id.c_str());
            }

            /**
             * @brief Checks whether the given type identifier is supported.
             *
             * @param type_id Type identifier string.
             * @return bool True if supported, false otherwise.
             */
            static bool type_supported(const std::string &type_id)
            {
            return fossil_algorithm_sort_type_supported(type_id.c_str());
            }
        };

    } // namespace bluecrab

} // namespace fossil

#endif

#endif

SAMPLE CODE C #

#include "fossil/algorithm/sort.h"
#include <stdio.h>

int main(void) {
    float values[] = { 3.2f, 1.5f, 9.1f };

    int status = fossil_algorithm_sort_exec(
        values,
        3,
        "f32",      // type
        "merge",    // algorithm
        "asc"       // order
    );

    if (status == 0) {
        printf("Sorted: ");
        for (size_t i = 0; i < 3; ++i)
            printf("%.2f ", values[i]);
        printf("\n");
    } else {
        printf("Sort error %d\n", status);
    }

    printf("f32 size = %zu\n", fossil_algorithm_sort_type_sizeof("f32"));
    printf("supports u8? %s\n",
           fossil_algorithm_sort_type_supported("u8") ? "yes" : "no");

    return 0;
}

SAMPLE CODE C++ #

#include "fossil/algorithm/sort.h"
#include <iostream>
#include <vector>

using fossil::algorithm::Sort;

int main() {
    std::vector<int32_t> data = { 42, 7, 29, 3, 18 };

    int status = Sort::exec(
        data.data(),
        data.size(),
        "i32",
        "heap",
        "desc"
    );

    if (status == 0) {
        std::cout << "Sorted: ";
        for (int v : data)
            std::cout << v << " ";
        std::cout << "\n";
    } else {
        std::cout << "Sort error " << status << "\n";
    }

    std::cout << "i32 size = " << Sort::type_sizeof("i32") << "\n";
    std::cout << "supports cstr? "
              << (Sort::type_supported("cstr") ? "yes" : "no") << "\n";

    return 0;
}

What are your feelings

Updated on December 12, 2025