STC

https://github.com/stclib/stc
Admin
STC is a comprehensive C99/C11 container and algorithm library offering templated data structures...
Tokens:57,797
Snippets:184
Trust Score:-
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Building and Installing STC Library (Bash)

Source: https://github.com/stclib/stc/blob/master/README.md

Shows the standard sequence of bash commands to configure the STC build process with meson, compile the project using ninja, and install the resulting library and headers. The example sets the installation prefix to ~/.local and configures a debug build type. The commands navigate into the created build directory before compiling and installing.

```bash
meson setup --buildtype debug build --prefix ~/.local
cd build
ninja
ninja install
```

--------------------------------

### Installing Meson and Ninja Build Tools (Bash)

Source: https://github.com/stclib/stc/blob/master/README.md

Provides bash commands to install the meson and ninja build system tools required for compiling STC using the Python package installer, pip. It also includes commands to export necessary environment variables (LIBRARY_PATH, CPATH, CC) which might be needed for the build process to locate installed libraries and headers, and set the C compiler.

```bash
pip install meson ninja
export LIBRARY_PATH=$LIBRARY_PATH:~/.local/lib
export CPATH=$CPATH:~/.local/include
export CC=gcc
```

--------------------------------

### Defining examples Build Option - Meson Build File

Source: https://github.com/stclib/stc/blob/master/meson_options.txt

Defines a build option named 'examples' of type 'feature'. This option controls whether project examples are built. Its value is automatically determined.

```Meson Build File
option(
'examples',
type: 'feature',
value: 'auto',
description: 'Build examples',
)
```

--------------------------------

### Defining Test Fixture Setup CTest C

Source: https://github.com/stclib/stc/blob/master/tests/mytests.c.txt

Defines an optional setup function for a test fixture using CTEST_SETUP. This function is called before each test in the fixture suite and receives a pointer to the fixture struct (`self`) for initialization.

```C
CTEST_SETUP(memtest) {
    CTEST_LOG("%s() data=%p buffer=%p", __func__, (void*)self, (void*)self->buffer);
    self->buffer = (unsigned char*)malloc(1024);
}
```

--------------------------------

### Basic STC Stack Usage Example (C)

Source: https://github.com/stclib/stc/blob/master/docs/stack_api.md

This example demonstrates how to define, initialize, populate, modify, and clean up an STC stack of integers. It shows the typical workflow of using the configuration macro, including the header, using the `_push` and `_pop` methods, accessing the top element with `_top`, and finally releasing resources with `_drop`.

```C
#define i_type IStack, int
#include "stc/stack.h"

#include <stdio.h>

int main(void) {
    IStack stk = {0};

    for (int i=0; i < 100; ++i)
        IStack_push(&stk, i*i);

    for (int i=0; i < 90; ++i)
        IStack_pop(&stk);

    printf("top: %d\n", *IStack_top(&stk));

    IStack_drop(&stk);
}
```

--------------------------------

### STC List Push, Sort Example C/C++

Source: https://github.com/stclib/stc/blob/master/docs/list_api.md

This example demonstrates initializing an STC list, adding elements using `push_front` and `push_back` in an interleaved fashion, sorting the list using `DList_sort` (which requires `i_use_cmp` to be defined, as done with `c_use_cmp`), printing the list before and after sorting, and finally releasing resources with `DList_drop`.

```c++
#define i_type DList, double, (c_use_cmp)
#include "stc/list.h"

#include <stdio.h>

int main(void) {
    DList list = c_make(DList, {10., 20., 30., 40., 50., 60., 70., 80., 90.});

    for (c_range(i, 1, 10)) {
        if (i & 1) DList_push_front(&list, (double) i);
        else       DList_push_back(&list, (double) i);
    }

    printf("initial: ");
    for (c_each(i, DList, list))
        printf(" %g", *i.ref);

    DList_sort(&list); // uses quicksort

    printf("\nsorted: ");
    for (c_each(i, DList, list))
        printf(" %g", *i.ref);

    DList_drop(&list);
}
```

--------------------------------

### Example Usage of STC Priority Queue

Source: https://github.com/stclib/stc/blob/master/docs/pqueue_api.md

This example demonstrates how to use the STC priority queue with `int32` elements configured as a min-heap (`i_cmp -c_default_cmp`). It shows initialization, pushing elements (including random numbers and specific negative values), extracting the smallest elements using `PriorityQ_top` and `PriorityQ_pop`, and finally dropping the queue.

```C++
#include <stdio.h>
#include "stc/random.h"

#define i_type PriorityQ, int32
#define i_cmp -c_default_cmp // min-heap
#include "stc/pqueue.h"

int main(void)
{
    isize N = 10000000;
    PriorityQ numbers = {0};

    // Push ten million random numbers to priority queue.
    for (c_range(N/2))
        PriorityQ_push(&numbers, (int32)(crand32_uint() >> 6));

    // Add some negative ones.
    int32 nums[] = {-231, -32, -873, -4, -343};
    for (c_range(i, c_arraylen(nums)))
        PriorityQ_push(&numbers, nums[i]);

    for (c_range(N/2))
        PriorityQ_push(&numbers, (int32)(crand32_uint() >> 6));

    // Extract and display the fifty smallest.
    for (c_range(50)) {
        printf("%d ", *PriorityQ_top(&numbers));
        PriorityQ_pop(&numbers);
    }
    PriorityQ_drop(&numbers);
}
```

--------------------------------

### Asserting Failure In Setup CTest C

Source: https://github.com/stclib/stc/blob/master/tests/mytests.c.txt

Defines a setup function for a fixture and uses the ASSERT_FAIL macro. Assertions can be used in setup/teardown; failing an assertion in setup causes the setup to fail, preventing subsequent tests in that fixture from running.

```C
CTEST_SETUP(fail) {
    (void)self;
    ASSERT_FAIL();
}
```

--------------------------------

### Example Usage of STC Deque C++

Source: https://github.com/stclib/stc/blob/master/docs/deque_api.md

This snippet provides a practical example of using the STC deque (`Deque`) configured for `int32_t`. It shows initialization, pushing elements to the front and back, iterating through the deque using `c_each`, printing elements, and finally dropping the deque to release resources. It illustrates the basic push and iteration operations.

```C++
#define i_type Deque, int32_t
#include "stc/deque.h"
#include <stdio.h>

int main(void) {
    Deque q = {0};
    Deque_push_front(&q, 10);
    for (c_each(i, Deque, q))
        printf(" %d", *i.ref);
    puts("");

    for (c_items(i, int, {1, 4, 5, 22, 33, 2}))
        Deque_push_back(&q, *i.ref);

    for (c_each(i, Deque, q))
        printf(" %d", *i.ref);
    puts("");

    Deque_push_front(&q, 9);
    Deque_push_front(&q, 20);
    Deque_push_back(&q, 11);
    Deque_push_front(&q, 8);

    for (c_each(i, Deque, q))
        printf(" %d", *i.ref);
    puts("");
    Deque_drop(&q);
}
```

--------------------------------

### Using Multiple Different Container Types (C++)

Source: https://github.com/stclib/stc/blob/master/README.md

Provides a comprehensive example showcasing the usage of four distinct STC container types: `hset_int` (hash set), `vec_pnt` (vector of struct Point), `list_int` (singly linked list), and `smap_int` (sorted map). It demonstrates defining types with custom equality (`i_eq`) and comparison (`c_use_cmp`), initializing, inserting elements, finding specific elements, erasing found elements, iterating through each container, and using `c_defer` for convenient resource cleanup.

```c++
#include <stdio.h>

#define i_type hset_int, int
#include "stc/hashset.h"   // unordered/hash set (assume i_key is basic type, uses `==` operator)

struct Point { float x, y; };
// Define cvec_pnt and enable linear search by defining i_eq
#define i_type vec_pnt, struct Point
#define i_eq(a, b) (a->x == b->x && a->y == b->y)
#include "stc/vec.h"    // vector of struct Point

// enable sort/search. Use native `<` and `==` operators
#define i_type list_int, int, (c_use_cmp)
#include "stc/list.h"   // singly linked list

#define i_type smap_int, int, int
#include "stc/sortedmap.h"  // sorted map int => int

int main(void)
{
    // Define four empty containers
    hset_int set = {0};
    vec_pnt vec = {0};
    list_int lst = {0};
    smap_int map = {0};
    c_defer( // Drop the containers at scope exit
        hset_int_drop(&set),
        vec_pnt_drop(&vec),
        list_int_drop(&lst),
        smap_int_drop(&map)
    ){
        enum{N = 5};
        int nums[N] = {10, 20, 30, 40, 50};
        struct Point pts[N] = {{10, 1}, {20, 2}, {30, 3}, {40, 4}, {50, 5}};
        int pairs[N][2] = {{20, 2}, {10, 1}, {30, 3}, {40, 4}, {50, 5}};

        // Add some elements to each container
        for (int i = 0; i < N; ++i) {
            hset_int_insert(&set, nums[i]);
            vec_pnt_push(&vec, pts[i]);
            list_int_push_back(&lst, nums[i]);
            smap_int_insert(&map, pairs[i][0], pairs[i][1]);
        }

        // Find an element in each container
        hset_int_iter i1 = hset_int_find(&set, 20);
        vec_pnt_iter i2 = vec_pnt_find(&vec, (struct Point){20, 2});
        list_int_iter i3 = list_int_find(&lst, 20);
        smap_int_iter i4 = smap_int_find(&map, 20);

        printf("\nFound: %d, (%g, %g), %d, [%d: %d]\n",
                *i1.ref, i2.ref->x, i2.ref->y, *i3.ref,
                i4.ref->first, i4.ref->second);

        // Erase all the elements found
        hset_int_erase_at(&set, i1);
        vec_pnt_erase_at(&vec, i2);
        list_int_erase_at(&lst, i3);
        smap_int_erase_at(&map, i4);

        printf("After erasing the elements found:");
        printf("\n set:");
        for (c_each(i, hset_int, set))
            printf(" %d", *i.ref);

        printf("\n vec:");
        for (c_each(i, vec_pnt, vec))
            printf(" (%g, %g)", i.ref->x, i.ref->y);

        printf("\n lst:");
        for (c_each(i, list_int, lst))
            printf(" %d", *i.ref);

        printf("\n map:");
        for (c_each(i, smap_int, map))
            printf(" [%d: %d]", i.ref->first, i.ref->second);
    }
}
```

--------------------------------

### Demonstrating STC hset with cstr Example (C)

Source: https://github.com/stclib/stc/blob/master/docs/hset_api.md

This example code demonstrates defining an STC hset to hold 'cstr' (STC string) keys using the i_type and c_keypro macros. It shows how to initialize hsets, insert elements using both initializer lists and loop-based insertion with 'emplace' and 'insert', iterate through the set elements, and properly clean up allocated memory with 'c_drop'.

```c
#include "stc/cstr.h"

#define i_type Strings, cstr, (c_keypro)
#include "stc/hashset.h"

int main(void)
{
    Strings first = c_make(Strings, {"red", "green", "blue"});
    Strings second={0}, third={0}, fourth={0}, fifth={0};

    for (c_items(i, const char*, {"orange", "pink", "yellow"}))
        Strings_emplace(&third, *i.ref);

    for (c_each(i, Strings, third))
        Strings_insert(&fifth, cstr_clone(*i.ref));

    Strings_emplace(&fourth, "potatoes");
    Strings_emplace(&fourth, "milk");
    Strings_emplace(&fourth, "flour");

    for (c_each(i, Strings, fourth))
        Strings_emplace(&fifth, cstr_str(i.ref));

    printf("fifth contains:\n\n");
    for (c_each(i, Strings, fifth))
        printf("%s\n", cstr_str(i.ref));

    c_drop(Strings, &first, &second, &third, &fourth, &fifth);
}
```

--------------------------------

### Defining docdir Build Option - Meson Build File

Source: https://github.com/stclib/stc/blob/master/meson_options.txt

Defines a build option named 'docdir' of type 'string'. This option specifies the directory where documentation should be built or installed. It requires a string value.

```Meson Build File
option('docdir', type: 'string', description: 'documentation directory')
```

--------------------------------

### Example Using STC sset with cstr - C++

Source: https://github.com/stclib/stc/blob/master/docs/sset_api.md

This C++ code provides a complete example demonstrating the usage of the STC sset container specialized for STC cstr (C-string) type. It shows initializing sets using initializer lists and iteration, inserting elements with sset_emplace, cloning one set, iterating through sets to add elements to another, iterating and printing elements of the final set, and properly releasing resources using c_drop.

```C++
#include "stc/cstr.h"

#define i_type SSet, cstr, (c_keypro)
#include "stc/sortedset.h"

int main(void)
{
    SSet second = c_make(SSet, {"red", "green", "blue"});
    SSet third={0}, fourth={0}, fifth={0};

    for (c_items(i, const char*, {"orange", "pink", "yellow"}))
        SSet_emplace(&third, *i.ref);

    SSet_emplace(&fourth, "potatoes");
    SSet_emplace(&fourth, "milk");
    SSet_emplace(&fourth, "flour");

    // Copy all to fifth:

    fifth = SSet_clone(second);

    for (c_each(i, SSet, third))
        SSet_emplace(&fifth, cstr_str(i.ref));

    for (c_each(i, SSet, fourth))
        SSet_emplace(&fifth, cstr_str(i.ref));

    printf("fifth contains:\n\n");
    for (c_each(i, SSet, fifth))
        printf("%s\n", cstr_str(i.ref));

    c_drop(SSet, &second, &third, &fourth, &fifth);
}
```

--------------------------------

### Example: Generating Normal Distribution & Histogram - C++

Source: https://github.com/stclib/stc/blob/master/docs/random_api.md

This example C++ program demonstrates how to use the STC `crand64` generator with a normal distribution. It seeds the global generator using the current time, defines a normal distribution with a mean and standard deviation, generates millions of samples, stores their frequency in a `SortedMap` (requiring `stc/sortedmap.h`), and then prints a simple bar chart visualization of the histogram. Dependencies include `stc/random.h`, `stc/sortedmap.h`, `stdio.h`, `time.h`, and `math.h`. The `c_range` and `c_each` macros are specific to STC containers/loops.

```C++
#include <stdio.h>
#include <time.h>
#include <math.h>
#include "stc/random.h"

#define i_type SortedMap, int, long
#include "stc/sortedmap.h" // sorted map.

int main(void)
{
    enum {N = 5000000};
    printf("Demo of gaussian / normal distribution of %d random samples\n", N);

    // Setup a reentrant random number engine with normal distribution.
    crand64_seed((uint64_t)time(NULL));
    crand64_normal_dist dist = {.mean=-12.0, .stddev=4.0};

    // Create histogram map
    SortedMap mhist = {0};
    for (c_range(N)) {
        int index = (int)round(crand64_normal(&dist));
        SortedMap_insert(&mhist, index, 0).ref->second += 1;
    }

    // Print the gaussian bar chart
    const double scale = 50;
    for (c_each(i, SortedMap, mhist)) {
        int n = (int)((double)i.ref->second * dist.stddev * scale * 2.5 / N);
        if (n > 0) {
            printf("%4d ", i.ref->first);
            for (c_range(n)) printf("*");
            puts("");
        }
    }
    SortedMap_drop(&mhist);
}
```

--------------------------------

### Demonstrating String Operations using stc/cstr.h C++

Source: https://github.com/stclib/stc/blob/master/docs/cstr_api.md

This C++ example demonstrates common string operations using the stc/cstr.h library. It shows variable declaration (cstr), deferred resource cleanup (c_defer, cstr_drop), initialization with literals (cstr_lit), accessing string data (cstr_str) and size (cstr_size), modifying strings (insert, erase, replace, assign, append), and creating formatted strings (cstr_from_fmt). The example highlights the library's functions for string manipulation.

```C++
#include "stc/cstr.h"

int main(void) {
    cstr s0, s1, full_path;
    c_defer(
        cstr_drop(&s0), cstr_drop(&s1), cstr_drop(&full_path)
    ){
        s0 = cstr_lit("Initialization without using strlen().");
        printf("%s\nLength: %" c_ZI "\n\n", cstr_str(&s0), cstr_size(&s0));

        s1 = cstr_lit("one-nine-three-seven-five.");
        printf("%s\n", cstr_str(&s1));

        cstr_insert(&s1, 3, "-two");
        printf("%s\n", cstr_str(&s1));

        cstr_erase(&s1, 7, 5); // -nine
        printf("%s\n", cstr_str(&s1));

        cstr_replace_nfirst(&s1, "seven", "four", 1);
        printf("%s\n", cstr_str(&s1));

        // reassign:
        cstr_assign(&s1, "one two three four five six seven");
        cstr_append(&s1, " eight");
        printf("append: %s\n", cstr_str(&s1));

        full_path = cstr_from_fmt("%s/%s.%s", "directory", "filename", "ext");
        printf("%s\n", cstr_str(&full_path));
    }
}
```

--------------------------------

### Defining Test Fixture Struct CTest C

Source: https://github.com/stclib/stc/blob/master/tests/mytests.c.txt

Defines a struct using CTEST_FIXTURE to hold data shared among tests in a suite. An instance of this struct is passed to setup, teardown, and test functions for this fixture.

```C
CTEST_FIXTURE(memtest) {
    unsigned char* buffer;
};
```

```C
CTEST_FIXTURE(fail) {
    int unused;
};
```

```C
CTEST_FIXTURE(weaklinkage) {
    int number;
};
```

```C
CTEST_FIXTURE(nosetup) {
    int value;
};
```

--------------------------------

### Defining Fixture Test CTest C

Source: https://github.com/stclib/stc/blob/master/tests/mytests.c.txt

Defines a test case that uses a specific fixture using the CTEST_F macro. The test function receives a pointer to the fixture struct (`self`) allowing access to data initialized in the setup function.

```C
CTEST_F(memtest, test1) {
    CTEST_LOG("%s()  data=%p  buffer=%p", __func__, (void*)self, (void*)self->buffer);
}
```

```C
CTEST_F(memtest, test2) {
    CTEST_LOG("%s()  data=%p  buffer=%p", __func__, (void*)self, (void*)self->buffer);
    ASSERT_FAIL();
}
```

```C
CTEST_F(fail, test1) {
    (void)self;
}
```

```C
CTEST_F(weaklinkage, test1) {
    (void)self;
    CTEST_LOG("%s()", __func__);
}
```

```C
CTEST_F(weaklinkage, test2) {
    (void)self;
    CTEST_LOG("%s()", __func__);
}
```

```C
CTEST_F(nosetup, test1) {
    (void)self;
    CTEST_LOG("%s()", __func__);
}
```

--------------------------------

### Using Timers and Time Functions C++

Source: https://github.com/stclib/stc/blob/master/docs/coroutine_api.md

This snippet provides functions for managing timers and accessing time within coroutines, including starting timers with specific durations, restarting them, checking expiration status, calculating elapsed or remaining time, awaiting timer expiration, getting current time, and sleeping for a specified duration.

```C++
                cco_start_timer_sec(cco_timer* tm, double sec);     // Start timer with seconds duration.
                cco_restart_timer(cco_timer* tm);                   // Restart timer with previous duration.
bool            cco_timer_expired(cco_timer* tm);                   // Return true if timer is expired.
double          cco_timer_elapsed_sec(cco_timer* tm);               // Return elapsed seconds.
double          cco_timer_remaining_sec(cco_timer* tm);             // Return remaining seconds.
                cco_await_timer_sec(cco_timer* tm, double sec);     // Start timer with duration and await for it to expire.

double          cco_time(void);                                     // Return seconds (with usec precision) since Epoch.
                cco_sleep_sec(double sec);                          // Sleep for seconds (msec or usec precision).
```

--------------------------------

### Implementing Entry Point Task (C++)

Source: https://github.com/stclib/stc/blob/master/docs/coroutine_api.md

This snippet defines the `start` task function, which serves as the initial entry point for the nested coroutine example. It simply awaits the `TaskA` coroutine using `cco_await_task`, thereby initiating the execution flow of the nested task chain. It also includes a basic `cco_finally` block for completion messaging.

```C++
int start(cco_task* self, cco_fiber* fb) {
    cco_routine (self) {
        puts("start");
        Subtasks* sub = fb->env;
        cco_await_task(&sub->A, fb);

        cco_finally:
        puts("done");
    }
    return 0;
}
```

--------------------------------

### Basic Vector Usage with Float (C++)

Source: https://github.com/stclib/stc/blob/master/README.md

Provides a simple C++ program demonstrating fundamental operations with a STC vector container (`Floats`) specialized for floating-point numbers. It shows initialization with `{0}`, adding elements using `Floats_push`, iterating using both index-based and the recommended `c_each` loop, and releasing memory with `Floats_drop`.

```c++
#define i_type Floats, float // Container type (name, element type)
#include "stc/vec.h"         // "instantiate" the desired container type
#include <stdio.h>

int main(void)
{
    Floats nums = {0};
    Floats_push(&nums, 30.f);
    Floats_push(&nums, 10.f);
    Floats_push(&nums, 20.f);

    for (int i = 0; i < Floats_size(&nums); ++i)
        printf(" %g", nums.data[i]);

    for (c_each(i, Floats, nums))     // Alternative and recommended way to iterate.
        printf(" %g", *i.ref);      // i.ref is a pointer to the current element.

    Floats_drop(&nums); // cleanup memory
}
```

--------------------------------

### Demonstrating Basic STC Integer Queue Usage - C

Source: https://github.com/stclib/stc/blob/master/docs/queue_api.md

This example illustrates the fundamental usage of the STC queue container storing integer types. It defines the queue type using `i_type`, includes the header, initializes a queue, pushes numbers 0-19, pops the first 5 elements, iterates through the remaining elements printing them, and finally drops the queue to free resources.

```C
#define i_type queue, int
#include "stc/queue.h"

#include <stdio.h>

int main(void) {
    queue Q = {0};

    // push() and pop() a few.
    for (c_range(i, 20))
        queue_push(&Q, i);

    for (c_range(5))
        queue_pop(&Q);

    for (c_each(i, queue, Q))
        printf(" %d", *i.ref);

    queue_drop(&Q);
}
```

--------------------------------

### Running Nested Tasks with Error Handling (C++)

Source: https://github.com/stclib/stc/blob/master/docs/coroutine_api.md

This is the main function that initializes the environment and runs the nested task example demonstrating error handling. It creates an instance of the `Subtasks` struct to hold the state of the sub-coroutines, initializes the main `cco_task` with the `start` function, and then repeatedly calls `cco_run_task` until the task completes, also tracking the number of times the coroutine yields or awaits.

```C++
int main(void)
{
    Subtasks env = {
        {{TaskA}, 42},
        {{TaskB}, 3.1415},
        {{TaskC}, 1.2f, 3.4f},
    };
    cco_task task = {{start}};

    int count = 0;
    cco_run_task(&task, &env) { ++count; }
    printf("resumes: %d\n", count);
}
```

--------------------------------

### Implementing Producer-Consumer with Symmetric Coroutines (cco_yield_to) in C/C++

Source: https://github.com/stclib/stc/blob/master/docs/coroutine_api.md

This example demonstrates a producer-consumer pattern using symmetric coroutines (`produce` and `consume`) that transfer control directly to each other using `cco_yield_to`. The `produce` coroutine adds items to a shared `Inventory` queue, while the `consume` coroutine removes them. The `main` function sets up the producer and consumer structures, links them, and starts the execution using `cco_run_task` on the producer.

```C++
#include <time.h>
#include <stdio.h>
#include "stc/coroutine.h"
#define i_type Inventory, int
#include "stc/queue.h"

// Example shows symmetric coroutines producer/consumer style.

cco_task_struct (produce) {
    produce_state cco; // must be first (compile-time checked)
    struct consume* consumer;
    Inventory inventory;
    int limit, batch, serial, total;
};

cco_task_struct (consume) {
    consume_state cco; // must be first
    struct produce* producer;
};


int produce(struct produce* self, cco_fiber* fb) {
    cco_routine (self) {
        while (1) {
            if (self->serial > self->total) {
                if (Inventory_is_empty(&self->inventory))
                    cco_return; // cleanup and finish
            }
            else if (Inventory_size(&self->inventory) < self->limit) {
                for (c_range(self->batch))
                    Inventory_push(&self->inventory, ++self->serial);

                printf("produced %d items, Inventory has now %d items:\n",
                       self->batch, (int)Inventory_size(&self->inventory));

                for (c_each(i, Inventory, self->inventory))
                    printf(" %2d", *i.ref);
                puts("");
            }

            cco_yield_to(self->consumer, fb); // symmetric transfer
        }

        cco_finally:
        cco_cancel_task(self->consumer, fb);
        Inventory_drop(&self->inventory);
        puts("cleanup producer");
    }
    return 0;
}

int consume(struct consume* self, cco_fiber* fb) {
    cco_routine (self) {
        int n, sz;
        while (1) {
            n = rand() % 10;
            sz = (int)Inventory_size(&self->producer->inventory);
            if (n > sz) n = sz;

            for (c_range(n))
                Inventory_pop(&self->producer->inventory);
            printf("consumed %d items\n", n);

            cco_yield_to(self->producer, fb); // symmetric transfer
        }

        cco_finally:
        puts("cleanup consumer");
    }
    return 0;
}

int main(void)
{
    srand((unsigned)time(0));
    struct produce producer = {
        .cco = {produce},
        .inventory = {0},
        .limit = 12,
        .batch = 8,
        .total = 50,
    };
    struct consume consumer = {
        .cco = {consume},
        .producer = &producer,
    };
    producer.consumer = &consumer;

    cco_run_task(&producer);
}
```

--------------------------------

### Listing STC vec_X Container Methods (C++)

Source: https://github.com/stclib/stc/blob/master/docs/vec_api.md

This snippet enumerates the functions provided by the STC `vec_X` container. It covers initialization (`vec_X_init`, `_with_size`, `_with_capacity`), copying/moving/dropping (`_clone`, `_copy`, `_move`, `_take`, `_drop`), capacity/size management (`_clear`, `_reserve`, `_resize`, `_shrink_to_fit`, `_size`, `_capacity`), element access (`_at`, `_front`, `_back`, `_at_mut`), searching/sorting (`_find`, `_sort`, `_lower_bound`, `_binary_search`), element modification (`_push`, `_emplace`, `_pop`, `_pull`, `_insert`, `_emplace_n`, `_erase`), iteration (`_begin`, `_end`, `_next`, `_advance`), and comparison (`_eq`). Dependencies like `i_use_cmp` are noted for specific functions.

```C++
vec_X           vec_X_init(void);
vec_X           vec_X_with_size(isize size, i_key null);
vec_X           vec_X_with_capacity(isize size);
vec_X           vec_X_clone(vec_X vec);

void            vec_X_copy(vec_X* self, const vec_X* other);
vec_X_iter      vec_X_copy_to(vec_X* self, isize idx, const i_key* arr, isize n);
vec_X           vec_X_move(vec_X* self);                                    // move
void            vec_X_take(vec_X* self, vec_X unowned);                     // take ownership of unowned
void            vec_X_drop(vec_X* self);                                    // destructor

void            vec_X_clear(vec_X* self);
bool            vec_X_reserve(vec_X* self, isize cap);
bool            vec_X_resize(vec_X* self, isize size, i_key null);
void            vec_X_shrink_to_fit(vec_X* self);

bool            vec_X_is_empty(const vec_X* self);
isize           vec_X_size(const vec_X* self);
isize           vec_X_capacity(const vec_X* self);

vec_X_iter      vec_X_find(const vec_X* self, i_keyraw raw);
vec_X_iter      vec_X_find_in(vec_X_iter i1, vec_X_iter i2, i_keyraw raw);  // return vec_X_end() if not found

const i_key*    vec_X_at(const vec_X* self, isize idx);
const i_key*    vec_X_front(const vec_X* self);
const i_key*    vec_X_back(const vec_X* self);

i_key*          vec_X_at_mut(vec_X* self, isize idx);                       // return mutable at idx
i_key*          vec_X_front_mut(vec_X* self);
i_key*          vec_X_back_mut(vec_X* self);

                // Requires either i_use_cmp, i_cmp or i_less defined:
void            vec_X_sort(vec_X* self);                                    // quicksort from sort.h
isize           vec_X_lower_bound(const vec_X* self, const i_keyraw raw);   // return c_NPOS if not found
isize           vec_X_binary_search(const vec_X* self, const i_keyraw raw); // return c_NPOS if not found

i_key*          vec_X_push(vec_X* self, i_key value);
i_key*          vec_X_push_back(vec_X* self, i_key value);                  // alias for push
i_key*          vec_X_emplace(vec_X* self, i_keyraw raw);
i_key*          vec_X_emplace_back(vec_X* self, i_keyraw raw);              // alias for emplace

void            vec_X_pop(vec_X* self);                                     // destroy last element
void            vec_X_pop_back(vec_X* self);                                // alias for pop
i_key           vec_X_pull(vec_X* self);                                    // move out last element

vec_X_iter      vec_X_insert_n(vec_X* self, isize idx, const i_key arr[], isize n); // move values
vec_X_iter      vec_X_insert_at(vec_X* self, vec_X_iter it, i_key value);   // move value
vec_X_iter      vec_X_insert_uninit(vec_X* self, isize idx, isize n);       // return iter at idx

vec_X_iter      vec_X_emplace_n(vec_X* self, isize idx, const i_keyraw raw[], isize n);
vec_X_iter      vec_X_emplace_at(vec_X* self, vec_X_iter it, i_keyraw raw);

vec_X_iter      vec_X_erase_n(vec_X* self, isize idx, isize n);
vec_X_iter      vec_X_erase_at(vec_X* self, vec_X_iter it);
vec_X_iter      vec_X_erase_range(vec_X* self, vec_X_iter it1, vec_X_iter it2);


vec_X_iter      vec_X_begin(const vec_X* self);
vec_X_iter      vec_X_end(const vec_X* self);
void            vec_X_next(vec_X_iter* iter);
vec_X_iter      vec_X_advance(vec_X_iter it, size_t n);

bool            vec_X_eq(const vec_X* c1, const vec_X* c2); // equality comp.
vec_X_value     vec_X_value_clone(vec_X_value val);
vec_X_raw       vec_X_value_toraw(const vec_X_value* pval);
vec_X_raw       vec_X_value_drop(vec_X_value* pval);
```

--------------------------------

### Implementing Sieve of Eratosthenes using cbits - C++

Source: https://github.com/stclib/stc/blob/master/docs/cbits_api.md

Provides a complete example program demonstrating the usage of the `cbits` library to compute prime numbers up to a given limit using the Sieve of Eratosthenes algorithm. It shows initializing a bitset, testing and resetting bits, counting set bits, and measuring execution time. Requires the `stc/cbits.h`, `stdio.h`, `math.h`, and `time.h` headers.

```C++
#include "stc/cbits.h"
#include <stdio.h>
#include <math.h>
#include <time.h>

cbits sieveOfEratosthenes(isize n)
{
    cbits bits = cbits_with_size(n/2, true);
    isize q = (isize)sqrt(n);

    for (isize i = 3; i <= q; i += 2) {
        for (isize j = i; j < n; j += 2) {
            if (cbits_test(&bits, j/2)) {
                i = j;
                break;
            }
        }
        for (isize j = i*i; j < n; j += i*2)
            cbits_reset(&bits, j/2);
    }
    return bits;
}

int main(void)
{
    isize n = 100000000;
    printf("computing prime numbers up to %" c_ZI "\n", n);

    clock_t t1 = clock();
    cbits primes = sieveOfEratosthenes(n + 1);
    isize nprimes = cbits_count(&primes);
    t1 = clock() - t1;

    printf("number of primes: %" c_ZI ", time: %f\n", nprimes, (float)t1/CLOCKS_PER_SEC);

    printf(" 2");
    for (isize i = 3; i < 1000; i += 2)
       if (cbits_test(&primes, i/2)) printf(" %" c_ZI, i);
    puts("");

    cbits_drop(&primes);
}
```

--------------------------------

### Example: UTF8 Iteration and Case Conversion - C++

Source: https://github.com/stclib/stc/blob/master/docs/zsview_api.md

This C++ example demonstrates how to create a `zsview` from a string literal, iterate over its UTF8 runes using `c_each`, and convert the entire view to uppercase using `cstr_toupper_sv`.

```C++
#include "stc/cstr.h"
#include "stc/zsview.h"

int main(void)
{
    zsview say = c_zv("Liberté, égalité, fraternité.");
    printf("%s\n", say.str);

    for (c_each(i, zsview, say))
        printf(c_svfmt " ", c_svarg(i.chr));
    puts("");

    cstr upper = cstr_toupper_sv(zsview_sv(say));
    printf("%s\n", cstr_str(&upper));
    cstr_drop(&upper);
}
```

--------------------------------

### STC vec with Custom Struct Example (C++)

Source: https://github.com/stclib/stc/blob/master/docs/vec_api.md

This example shows how to use the STC `vec` container with a custom `User` struct that contains a dynamic string (`cstr`). It defines `User_cmp`, `User_clone`, and `User_drop` functions required for managing the struct's resources and enabling sorting. The container is defined using `#define i_type Users, User, (c_keyclass | c_use_cmp)`, binding these custom functions. The example then creates and populates a `Users` vector, clones it, sorts the clone, iterates through the sorted vector, and uses `c_drop` for cleanup.

```C++
#include <stdio.h>
#include "stc/cstr.h"

typedef struct {
    cstr name; // dynamic string
    int id;
} User;

int User_cmp(const User* a, const User* b) {
    int c = strcmp(cstr_str(&a->name), cstr_str(&b->name));
    return c ? c : a->id - b->id;
}

User User_clone(User user) {
    user.name = cstr_clone(user.name);
    return user;
}

void User_drop(User* self) {
    cstr_drop(&self->name);
}

// Declare a managed, clonable vector of users.
// c_keyclass: User is a "class" and binds the _clone(), _drop(), and _cmp() functions.
// c_use_cmp:  Sorting/searching a vec is only enabled by either directly specifying an
//             i_cmp function or by specifying c_use_cmp. In this case i_cmp is indirectly
//             bound to User_cmp because c_keyclass was specified, otherwise it is assumed that
//             i_key is a built-in type that works with < and == operators).
#define i_type Users, User, (c_keyclass | c_use_cmp)
#include "stc/vec.h"

int main(void) {
    Users users = {0};
    Users_push(&users, (User){cstr_lit("mary"), 0});
    Users_push(&users, (User){cstr_lit("joe"), 1});
    Users_push(&users, (User){cstr_lit("admin"), 2});

    Users users2 = Users_clone(users);
    Users_sort(&users2);

    for (c_each(i, Users, users2))
        printf("%s: %d\n", cstr_str(&i.ref->name), i.ref->id);

    c_drop(Users, &users, &users2); // cleanup
}
```

--------------------------------

### Iterating STC List Elements (C++)

Source: https://github.com/stclib/stc/blob/master/README.md

Demonstrates how to define a STC list type, initialize it with elements, and iterate through its elements using the `c_each` macro. It shows accessing the element reference via `it.ref` and modifying the value. Requires including the `stc/list.h` header after defining the container type.

```C++
#define i_type MyInts, int
#include "stc/list.h"
...
MyInts ints = c_make(MyInts, {3, 5, 9, 7, 2});
for (c_each(it, MyInts, ints)) *it.ref += 42;
```

--------------------------------

### Example: Iterating and Converting UTF8 Strings (C++)

Source: https://github.com/stclib/stc/blob/master/docs/utf8_api.md

Provides a C++ example demonstrating the use of `zsview` for handling zero-terminated UTF8 strings, iterating through runes using `c_each`, printing individual runes, and converting the entire string to uppercase using `cstr_toupper_sv`. Requires `cstr` and `zsview`.

```c++
#include "stc/cstr.h"
#include "stc/zsview.h"

int main(void)
{
    zsview say = c_zv("Liberté, égalité, fraternité.");
    printf("%s\n", say.str);

    for (c_each(i, zsview, say))
        printf(c_svfmt " ", c_svarg(i.chr));
    puts("");

    cstr upper = cstr_toupper_sv(zsview_sv(say));
    printf("%s\n", cstr_str(&upper));
    cstr_drop(&upper);
}
```

--------------------------------

### Example Usage of coption_get in C++

Source: https://github.com/stclib/stc/blob/master/docs/coption_api.md

Demonstrates how to use `coption_init` and `coption_get` to parse command-line arguments. It defines both short options ("xy:z::123") and long options (like "--foo", "--bar", "--opt") with varying argument requirements. The code iterates using `coption_get` in a `while` loop, processes found options, handles errors ('?' and ':'), and prints both options and non-option arguments.

```C++
#include <stdio.h>
#include "stc/coption.h"

int main(int argc, char *argv[]) {
    coption_long longopts[] = {
        {"foo", coption_no_argument,       'f'},
        {"bar", coption_required_argument, 'b'},
        {"opt", coption_optional_argument, 'o'},
        {0}
    };
    const char* shortopts = "xy:z::123";
    if (argc == 1)
        printf("Usage: program -x -y ARG -z [ARG] -1 -2 -3 --foo --bar ARG --opt [ARG] [ARGUMENTS]\n", argv[0]);
    coption opt = coption_init();
    int c;
    while ((c = coption_get(&opt, argc, argv, shortopts, longopts)) != -1) {
        switch (c) {
            case '?': printf("error: unknown option: %s\n", opt.optstr); break;
            case ':': printf("error: missing argument for %s\n", opt.optstr); break;
            default:  printf("option: %c [%s]\n", opt.opt, opt.arg ? opt.arg : ""); break;
        }
    }
    printf("\nNon-option arguments:");
    for (int i = opt.ind; i < argc; ++i)
        printf(" %s", argv[i]);
    putchar('\n');
}
```

--------------------------------

### Example 2: STC HashMap with int Keys and POD Struct Values

Source: https://github.com/stclib/stc/blob/master/docs/hmap_api.md

This example demonstrates defining, inserting elements into, iterating through, and dropping an STC hmap where keys are integers (POD) and values are a simple POD struct `Vec3i`. It shows how to use `hmap_X_insert` with struct initialization and iterate using `c_each_kv`.

```C++
#include <stdio.h>
typedef struct { int x, y, z; } Vec3i;

#define i_type hmap_iv, int, Vec3i
#include "stc/hashmap.h"

int main(void)
{
    hmap_iv vecs = {0};

    hmap_iv_insert(&vecs, 1, (Vec3i){100,   0,   0});
    hmap_iv_insert(&vecs, 2, (Vec3i){  0, 100,   0});
    hmap_iv_insert(&vecs, 3, (Vec3i){  0,   0, 100});
    hmap_iv_insert(&vecs, 4, (Vec3i){100, 100, 100});

    for (c_each_kv(num, v3, hmap_iv, vecs))
        printf("%d: { %3d, %3d, %3d }\n", *num, v3->x, v3->y, v3->z);

    hmap_iv_drop(&vecs);
}
```

--------------------------------

### Using Custom Allocator with STC Sorted Map (C++)

Source: https://github.com/stclib/stc/blob/master/README.md

Demonstrates using an STC sortedmap (IMap) configured with the PostgreSQL allocator defined by stcpgs.h. It shows defining the type with i_type, initializing with c_make using CurrentMemoryContext in aux, inserting elements, iterating, and dropping the map.

```C++
#define i_type IMap, int, int
#include "stcpgs.h"
#include "stc/sortedmap.h"

void maptest()
{
    IMap map = {.aux={CurrentMemoryContext}};
    for (c_range(i, 1, 16))
        IMap_insert(&map, i*i, i); // uses pgs_malloc

    for (c_each(i, IMap, map))
        printf("%d:%d ", i.ref->first, i.ref->second);

    IMap_drop(&map);
}
```

--------------------------------

### Example 1: STC HashMap with cstr Keys and Values

Source: https://github.com/stclib/stc/blob/master/docs/hmap_api.md

This example demonstrates how to define, initialize, iterate through, insert elements into, access elements by key, and drop an STC hmap where both keys and values are STC cstr (C string) types. It uses the c_keypro and c_valpro options for automatic string handling.

```C++
#include "stc/cstr.h"

#define i_type hmap_cstr, cstr, cstr, (c_keypro | c_valpro)
#include "stc/hashmap.h"

int main(void)
{
    // Create an unordered_map of three strings (that map to strings)
    hmap_cstr umap = c_make(hmap_cstr, {
        {"RED", "#FF0000"},
        {"GREEN", "#00FF00"},
        {"BLUE", "#0000FF"}
    });

    // Iterate and print keys and values of unordered map
    for (c_each(n, hmap_cstr, umap)) {
        hmap_cstr_raw v = hmap_cstr_value_toraw(n.ref);
        printf("Key:[%s] Value:[%s]\n", v.first, v.second);
    }

    // Add two new entries to the unordered map
    hmap_cstr_emplace(&umap, "BLACK", "#000000");
hmap_cstr_emplace(&umap, "WHITE", "#FFFFFF");

    // Output values by key
    printf("The HEX of color RED is:[%s]\n", cstr_str(hmap_cstr_at(&umap, "RED")));
    printf("The HEX of color BLACK is:[%s]\n", cstr_str(hmap_cstr_at(&umap, "BLACK")));

    hmap_cstr_drop(&umap);
}
```
Tokens:
Raw