📘 Guide

Table of Contents

• 🔨 Creating Dynarr
  • ⚙️ With default options
  • ⚙️ With custom options
  • ⿻ Clone an existing array
  • 🧨 Deallocating Dynarr
  • ⚙️ Allocate extended header
  • ⚙️ Without macro wrapper
  • ❌ Error handling
• ⬆️ Extending a dynarr

🔨 Creating Dynarr

In this section we'll discuss creation of the dynamic array.
Based on Example file.

⚙️ With default options

A standard way to create dynarr_t is to call a macro wrapper dynarr_create, it passes default option values, so you dont have to provide them yourself.

    dynarr_t *dynarr = dynarr_create(.element_size = sizeof(int));

• element_size is the only mandatory explicit option.
• Full list of default options: DYNARR_DEFAULT_ARGS
  

⚙️ With custom options

    dynarr_t *dynarr = dynarr_create
        (
            .element_size = sizeof(float),
            .initial_cap = 100,
            .grow_factor = 1.5f,
            .grow_threshold = 0.8,
            .shrink_threshold = 0.2
        );

⚙️ Without macro wrapper

You can avoid macro wrapper with default values if you know what you are doing.
Just create opts on stack and pass by reference into a dynarr_create_ function directly:

    dynarr_opts_t opts = {.element_size = sizeof(int)};
    dynarr_t *dynarr = dynarr_create_(&opts);

⚙️ Allocate extended header

This is important for derived classes that need to include their data
in a memory allocated by underlying vector.

Define a structure ext_t that will be peallocated right after dynarr_header_t :

    typedef struct
    {
        size_t meta;
        // ...
        // ...
        // ...
    }
    ext_t;

Create dynarr specifying dynarr_opts_t::ext_header_size to reserve space for ext_t.

    dynarr_t *dynarr = dynarr_create
        (
            .ext_header_size = sizeof(ext_t),
            .element_size = sizeof(long)
        );

Initialize extended header:

    ext_t *header = dynarr_get_ext_header(dynarr);
    *header = (ext_t) {0};

⿻ Clone an existing array

With dynarr_clone you are able to produce exact copy of an existing array.

    dynarr_t *clone = dynarr_clone(dynarr);

❌ Error handling

Default implementation uses heap as allocation memory source. Depending on system architecture heap allocation is not fail proof, take it into your considerations.

Check that dynarr value is NULL, then resolve allocation error. If you got none resolution choises, perform gracefull program termination. See following example, print error and exit abnormally.

    if (!dynarr)
    {
        perror("dynarr_create");
        abort();
    }

Other option is to just use an assert. If allocation error is unlikely to happen, but you still need to indicate if it occures.

    assert(dynarr && "Buy more RAM!");

Advantage of asserts if that they can be disabled by providing -DNDEBUG compilation flag.

🧨 Deallocating Dynarr

Prevent memory leaks by deallocation resources, when they not needed anymore!

    dynarr_destroy(dynarr);

Attention

Always remember to deallocate dynarr created with dynarr_create or dynarr_clone !

---

⬆️ Extending a dynarr

Follow same guidelines as for the Vector

Extending a vector