Vector.h file

This module provides a dynamic-array type comparable to C++'s std::vector and Rust's std::vec::Vec for Cnx.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Defines

#define VECTOR_STATIC

Define documentation

#define VECTOR_STATIC

You can provide user-defined default-constructor, copy-constructor, and destructor for elements of your type, and custom allocator for all memory allocation:

YourType your_type_constructor(CnxAllocator allocator) {
    let_mut t = (YourType){0};
    // whatever you need to do to init your type
    return t;
}

YourType your_type_copy_constructor(const YourType* restrict elem, CnxAllocator allocator) {
    let_mut t = (YourType){0};
    // whatever you need to do to copy `elem` to `t`
    return t;
}

void your_type_destructor(YourType* restrict t, CnxAllocator allocator) {
    // whatever you need to do to cleanup `t`
}

CnxVector(YourType) create_and_fill_your_type_vec(usize num_elements) {
    // init a vec with num_elements capacity (zero size) and our custom collection data
    let_mut vec = cnx_vector_new_with_capacity_allocator_and_collection_data(YourType,
                        capacity,
                        // This `CnxAllocator` will only be associated with this specific array,
                        // not all `CnxArray(YourType, YourN)`s
                        cnx_allocator_from_custom_stateless_allocator(your_malloc,
                                                                      your_realloc,
                                                                      your_free),
                        // This `CnxCollectionData(CollectionType)` will only be
                        // associated with this specific vector, not all `CnxVector(YourType)`s
                        ((CnxCollectionData(CnxVector(YourType))) {
                            // can be left NULL, will be defaulted
                            .m_constructor = your_type_constructor,
                            // can be left NULL, will disable `cnx_vector_clone(self)` for
                            // this vector
                            .m_copy_constructor = your_type_copy_constructor,
                            // can be left NULL, will be defaulted
                            .m_destructor = your_type_destructor
                        })
                    );

    // fill the vec with default constructed elements
    cnx_vector_resize(vec, num_elements);

    return vec;
}

CnxVector(T) also provides Cnx random access iterators and optional scoped destruction:

void example(void) {
    let_mut cnx_vector_scoped(u32) vec = cnx_vector_new_with_capacity(u32, 10);
    ranged_for(i, 0, 9) {
        cnx_vector_push_back(vec, i);
    }

    // loop over the elements in the vector by value, as an iteration
    foreach(elem, vec) {
        println("{}", elem);
    }
    // vec goes out of scope here and `cnx_vector_free(vec)` is called on it
    // because we declared it as scoped
}

Like other Cnx collections, CnxVector(T) provides its type-agnostic usage through a vtable pointer contained in the struct, and provides macros which wrap the usage of the vtable, making access simpler. If you prefer to not use this method of access, you can call the typed functions directly by in-fixing the contained type in the associated function name. IE: for CnxVector(i32), vec, the equivalent function call for cnx_vector_push_back(vec, element) would be cnx_vector_i32_push_back(&vec, element)