Collections » CnxVector module

CnxVector(T) is a struct template for a type-safe dynamic-capacity array. It's allocator aware, provides Cnx compatible random access iterators, and supports user-defined default constructors, copy-constructors, and destructors for its elements. It's design is similar to both C++'s std::vector and Rust's std::vec::Vec, but with slightly expanded functionality and semantics.

CnxVector(T) has a small size optimization (SSO) that is user configurable. This allows for a compile-time configurable number of elements to be stored on the stack, before resorting to heap allocation, at the cost of sizeof(CnxVector(T)) being larger than otherwise necessary. By default, this optimization allows for up to 8 elements to be stored on the stack. For information on how to configure this, see "Template Parameters" below.

Instantiations of CnxVector(T) are already provided for builtin types like i32 and some Cnx types, like CnxString. Instantiating it for your own types is simple and requires minimal boiler-plate.

Instantiation requirements:

  1. a typedef of your type to provide an alphanumeric name for it. (for template and macro parameters)
  2. a typedef for pointer to your type as Ref(YourType), for use with the iterators.
  3. a typedef for pointer to const your type as ConstRef(YourType), for use with the iterators
  4. Instantiations for Cnx iterators for the typedefs provided in (2) and (3)
  5. Instantiation of CnxOption(T) for your type

We recommend two routes for providing instantiations for user-defined types, either:

  1. Provide the instantiation together with your type's public interface and implementation OR
  2. Provide it as a separate "template instantiation" .h/.c file pair

Parameters

CnxVector(T) takes several instantiation-time macro parameters, in addition to the instantiation-mode macro parameters required of all Cnx templates.

Instantiation-Mode Parameters

These signal to the implementation to instantiate the declarations, definitions, or both, for the template.

  1. VECTOR_DECL (Optional) - Defining this to true signals to the implementation to declare the template instantiation when you include <Cnx/Vector.h>. This will instantiate any required type declarations and definitions and any required function declarations. No functions will be defined. This is optional (but signals intent explicitly) - If required template parameters are defined and VECTOR_IMPL is not, then this will be inferred as true (1) by default.
  2. VECTOR_IMPL - Defining this to true signals to the implementation to define the template instantiation when you include <Cnx/Vector.h>. This will instantiate any required function definitions. This is not required to be paired with VECTOR_DECL (you can declare the template without defining it), but it is eventually required to provide the definitions for the functions. If this instantiation-mode hasn't been included in exactly one translation unit in your build, you will get linking errors due to the missing function definitions.

Template Parameters

These provide the type or value parameters that the template is parameterized on to the template implementation. These should be #defined to their appropriate values.

  1. VECTOR_T - The type to be stored in the vector (e.g. u32 or CnxString). This is required.
  2. VECTOR_SMALL_OPT_CAPACITY - This is the small-optimization capacity to be stored in the vector directly when the size is at or below this, instead of resorting to heap allocation. 0 is a valid value for this. This is optional, and if not provided will default to CNX_VECTOR_DEFAULT_SHORT_OPT_CAPACITY (which is defined as 8). Heap allocations occurring after size exceeds VECTOR_SMALL_OPT_CAPACITY will follow the growth strategy of the collection.
  3. VECTOR_DEFAULT_LONG_CAPACITY - This is the initial capacity to be stored in the vector if VECTOR_SMALL_OPT_CAPACITY is defined as 0. This is optional. If not provided and VECTOR_SMALL_OPT_CAPACITY is provided as 0, this will default to CNX_VECTOR_VECTOR_DEFAULT_LONG_CAPACITY (which is defined as 16). If VECTOR_SMALL_OPT_CAPACITY is defaulted or provided as greater than 0, this will not be used. Heap allocations occurring after size exceeds whichever of the two possible initial storage strategies are used will follow the growth strategy of the collection.

Example of (1).

// in `YourType.h`
typedef struct YourType {
 // members
} YourType;

typedef YourType* Ref(YourType);
typedef const YourType* ConstRef(YourType);

DeclCnxIterators(Ref(YourType));
DeclCnxIterators(ConstRef(YourType));

#define OPTION_T YourType
#define OPTION_DECL TRUE
#include <Cnx/Option.h>
#undef OPTION_T
#undef OPTION_DECL

// define the template parameter, `VECTOR_T`
#define VECTOR_T YourType
// tell the template to instantiate the declarations
#define VECTOR_DECL TRUE
// `#undef`s all macro parameters after instantiating the template,
// so they don't propagate around
#define VECTOR_UNDEF_PARAMS TRUE
#include <Cnx/Vector.h>

// the rest of your public interface...

// in `YourType.c`
#define OPTION_T YourType
#define OPTION_IMPL TRUE
#include <Cnx/Option.h>
#undef OPTION_T
#undef OPTION_IMPL

// define the template parameter, `VECTOR_T`
#define VECTOR_T YourType
// tell the template to instantiate the implementations
#define VECTOR_IMPL TRUE
// `#undef`s all macro parameters after instantiating the template,
// so they don't propagate around
#define VECTOR_UNDEF_PARAMS TRUE
#include <Cnx/Vector.h>

// the rest of your implementation

Example of (2):

// in `YourType.h`
typedef struct YourType {
    // members
} YourType;

typedef YourType* Ref(YourType);
typedef const YourType* ConstRef(YourType);

DeclCnxIterators(Ref(YourType));
DeclCnxIterators(ConstRef(YourType));
// the rest of your public interface

// in `CnxOptionYourType.h`
#include "YourType.h"
#define OPTION_T YourType
#define OPTION_DECL TRUE
#include <Cnx/Option.h>
#undef OPTION_T
#undef OPTION_DECL

// in `CnxOptionYourType.c`
#include "CnxOptionYourType.h"

#define OPTION_T YourType
#define OPTION_IMPL TRUE
#include <Cnx/Option.h>
#undef OPTION_T
#undef OPTION_IMPL

// in `CnxVectorYourType.h`
#include "YourType.h"
#include "CnxOptionYourType.h"

// define the template parameter, `VECTOR_T`
#define VECTOR_T YourType
// tell the template to instantiate the declarations
#define VECTOR_DECL TRUE
// `#undef`s all macro parameters after instantiating the template,
// so they don't propagate around
#define VECTOR_UNDEF_PARAMS TRUE
#include <Cnx/Vector.h>

// in `CnxVectorYourType.c`
#include "CnxVectorYourType.h"

// define the template parameter, `VECTOR_T`
#define VECTOR_T YourType
// tell the template to instantiate the implementations
#define VECTOR_IMPL TRUE
// `#undef`s all macro parameters after instantiating the template,
// so they don't propagate around
#define VECTOR_UNDEF_PARAMS TRUE
#include <Cnx/Vector.h>

Then, somewhere else in your codebase, you can easily use the instantiation:

#include "YourType.h"
// if instantiation method (2)
#include "CnxVectorYourType.h"

CnxVector(YourType) create_and_fill_your_type_vec(usize num_elements) {
    let_mut vec = cnx_vector_new_with_capacity(YourType, num_elements);

    cnx_vector_resize(vec, num_elements);

    return vec;
}

CnxVector(T) implements CnxFormat, but because of its generic type, can't be automatically converted to its CnxFormat implementation, so we have to cast it explicitly:

#include "Cnx/IO.h"
void print_vec(const CnxVector(YourType)* vec) {
    println("{}", as_format_t(CnxVector(YourType), *vec));
}

Defines

#define CnxVector(T)
macro alias for a CnxVector(T) containing Ts
#define CNX_VECTOR_DEFAULT_SHORT_OPT_CAPACITY
The default small-vector optimization capacity if not given as a template parameter.
#define CNX_VECTOR_DEFAULT_LONG_CAPACITY
The default heap-allocated capacity if not given as a template parameter.
#define cnx_vector_new(T)
Creates a new CnxVector(T) with defaulted associated functions and initial capacity.
#define cnx_vector_new_with_allocator(T, allocator)
Creates a new CnxVector(T) with defaulted capacity and associated functions and provided memory allocator.
#define cnx_vector_new_with_collection_data(T, collection_data_ptr)
Creates a new CnxVector(T) with defaulted capacity and provided associated functions.
#define cnx_vector_new_with_allocator_and_collection_data(T, allocator, collection_data_ptr)
Creates a new CnxVector(T) with defaulted capacity and provided associated functions and memory allocator.
#define cnx_vector_new_with_capacity(T, capacity)
Creates a new CnxVector(T) with at least the given capacity and defaulted associated functions.
#define cnx_vector_new_with_capacity_and_allocator(T, capacity, allocator)
Creates a new CnxVector(T) with at least the given capacity, defaulted associated functions, and provided memory allocator.
#define cnx_vector_new_with_capacity_and_collection_data(T, capacity, collection_data_ptr)
Creates a new CnxVector(T) with at least the given capacity and provided associated functions.
#define cnx_vector_new_with_capacity_allocator_and_collection_data(T, capacity, allocator, collection_data_ptr)
Creates a new CnxVector(T) with at least the given capacity and provided associated functions and memory allocator.
#define cnx_vector_clone(self)
Clones the given CnxVector(T)
#define cnx_vector_at_mut(self, index)
Returns a mutable reference to the element at the given index into the given CnxVector(T)
#define cnx_vector_at(self, index)
Returns a const reference to the element at the given index into the given CnxVector(T)
#define cnx_vector_front_mut(self)
Returns a mutable reference to the first element in the given CnxVector(T)
#define cnx_vector_front(self)
Returns a const reference to the first element in the given CnxVector(T)
#define cnx_vector_back_mut(self)
Returns a mutable reference to the last element in the given CnxVector(T)
#define cnx_vector_back(self)
Returns a const reference to the last element in the given CnxVector(T)
#define cnx_vector_data_mut(self)
Returns a pointer to the mutable raw array containing the given CnxVector(T)'s elements.
#define cnx_vector_data(self)
Returns a pointer to the const raw array containing the given CnxVector(T)'s elements.
#define cnx_vector_is_empty(self)
Returns whether the given CnxVector(T)is empty.
#define cnx_vector_is_full(self)
Returns whether the given CnxVector(T) is full (size equals capacity)
#define cnx_vector_size(self)
Returns the current size of the given CnxVector(T)
#define cnx_vector_max_size(T)
Returns the maximum possible size of a CnxVector(T) containing type T
#define cnx_vector_capacity(self)
Returns the current capacity of the given CnxVector(T)
#define cnx_vector_reserve(self, new_capacity)
Ensures enough memory to store at least new_capacity number of elements in the given CnxVector(T), reallocating if necessary.
#define cnx_vector_resize(self, new_size)
Resizes the given CnxVector(T) to new_size number of elements. If new_size is greater than the current size, this will allocate memory if necessary and default-construct new elements. If new_size is less than the current size, this will destruct size - new_size number of elements and, if new_size is less than the SSO capacity, deallocate memory.
#define cnx_vector_shrink_to_fit(self)
Shrinks the memory allocation for the given CnxVector(T) to match its current size.
#define cnx_vector_clear(self)
Clears the contents of the given CnxVector(T), destructing all of its elements.
#define cnx_vector_push_back(self, element)
Appends the given element to the end of the given CnxVector(T), reallocating memory if necessary.
#define cnx_vector_pop_back(self)
Returns the last element in the given CnxVector(T) and removes it, if the size is greater than zero.
#define cnx_vector_pop_front(self)
Returns the first element in the given CnxVector(T) and removes it, if the size is greater than zero.
#define cnx_vector_insert(self, element, index)
Inserts the given element at the given index in the given CnxVector(T), moving elements backward in the vector if necessary.
#define cnx_vector_erase(self, index)
Removes the element at the given index from the given CnxVector(T), moving elements forward in the vector if necessary.
#define cnx_vector_erase_n(self, index, num_elements)
Removes num_elements elements from the given CnxVector(T), starting with the element at index, and moving elements forward in the vector afterward, if necessary.
#define cnx_vector_free(self)
Frees the given CnxVector(T), calling the element destructor on each element and freeing any allocated memory.
#define cnx_vector_begin(self)
Returns a CnxRandomAccessIterator into the mutable iteration of the given CnxVector(T), starting at the beginning of the iteration (pointing at the beginning of the vector)
#define cnx_vector_end(self)
Returns a CnxRandomAccessIterator into the mutable iteration of the given CnxVector(T), starting at the end of the iteration (pointing at the end of the vector)
#define cnx_vector_rbegin(self)
Returns a CnxRandomAccessIterator into the mutable iteration of the given CnxVector(T), starting at the beginning of the reversed iteration (pointing at the end of the vector)
#define cnx_vector_rend(self)
Returns a CnxRandomAccessIterator into the mutable iteration of the given CnxVector(T), starting at the end of the reversed iteration (pointing at the beginning of the vector)
#define cnx_vector_iterator_equals(first, second)
Returns whether the given pair of iterators are equal (they belong to the same collection and point to the same element), IE: if first == second
#define cnx_vector_cbegin(self)
Returns a CnxRandomAccessIterator into the const iteration of the given CnxVector(T), starting at the beginning of the iteration (pointing at the beginning of the vector)
#define cnx_vector_cend(self)
Returns a CnxRandomAccessIterator into the const iteration of the given CnxVector(T), starting at the end of the iteration (pointing at the end of the vector)
#define cnx_vector_crbegin(self)
Returns a CnxRandomAccessIterator into the const iteration of the given CnxVector(T), starting at the beginning of the reversed iteration (pointing at the end of the vector)
#define cnx_vector_crend(self)
Returns a CnxRandomAccessIterator into the const iteration of the given CnxVector(T), starting at the end of the reversed iteration (pointing at the beginning of the vector)
#define cnx_vector_const_iterator_equals(first, second)
Returns whether the given pair of const iterators are equal (they belong to the same collection and point to the same element), IE: if first == second
#define CnxScopedVector(T)
declare a CnxVector(T) variable with this attribute to have Cnx_vector_free automatically called on it at scope end

Define documentation

#define CnxVector(T)
#include <include/Cnx/vector/VectorDef.h>

macro alias for a CnxVector(T) containing Ts

CnxVector(T) is a bounds-safe, allocator aware, generic dynamic-capacity array type. It is implemented as a struct template, which enables 100% type safety, while providing abstractions that allow type agnostic use. It has greatly increased ergonomics over manual array management and provides many useful features such as random access iterators and optional scoped destruction.

Example:

#include <Cnx/Vector.h>
#include <Cnx/IO.h>

// create a `CnxVector(i32)` with default allocator, element default-constructor, and
element
// destructor
let_mut vec = cnx_vector_new(i32);

// append 10 elements to the vector
ranged_for(i, 0, 9) {
    cnx_vector_push_back(vec, i);
}

// prints information about `vec` to `stdout`
// because `CnxVector(T)` is generic, and thus can't be used in a `_Generic` match arm prior
to
// the type's instantiation, we have to explicitly cast to the `CnxFormat` Trait to get
// `CnxVector(T)`'s implementation of the Trait
println("{}", Cnx_as_format_t(CnxVector(i32), vec));
// prints `vec`'s elements to `stdout`
foreach(elem, vec) {
    println("{}", elem);
}

{
    let_mut CnxScopedVector(i32) vec2 = cnx_vector_new(i32);
    foreach(elem, vec) {
        cnx_vector_push_back(vec2, elem);
    }
}
// `vec2` is freed here

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)

#define CNX_VECTOR_DEFAULT_SHORT_OPT_CAPACITY
#include <include/Cnx/vector/VectorDef.h>

The default small-vector optimization capacity if not given as a template parameter.

#define CNX_VECTOR_DEFAULT_LONG_CAPACITY
#include <include/Cnx/vector/VectorDef.h>

The default heap-allocated capacity if not given as a template parameter.

#define cnx_vector_new(T)
#include <include/Cnx/vector/VectorDef.h>

Creates a new CnxVector(T) with defaulted associated functions and initial capacity.

Parameters
T - The element type of the CnxVector(T) instantiation to create
Returns a new CnxVector(T)

Creates a new CnxVector(T) with:

  1. defaulted initial capacity
  2. defaulted associated element default-constructor
  3. defaulted associated element copy-constructor
  4. defaulted associated element destructor
  5. defaulted associated memory allocator

#define cnx_vector_new_with_allocator(T, allocator)
#include <include/Cnx/vector/VectorDef.h>

Creates a new CnxVector(T) with defaulted capacity and associated functions and provided memory allocator.

Parameters
T - The element type of the CnxVector(T) instantiation to create
allocator - The CnxAllocator to use for memory allocations
Returns a new CnxVector(T)

Creates a new CnxVector(T) with:

  1. defaulted initial capacity
  2. defaulted associated element default-constructor
  3. defaulted associated element copy-constructor
  4. defaulted element destructor
  5. user-provided memory allocator

#define cnx_vector_new_with_collection_data(T, collection_data_ptr)
#include <include/Cnx/vector/VectorDef.h>

Creates a new CnxVector(T) with defaulted capacity and provided associated functions.

Parameters
T - The element type of the CnxVector(T) instantiation to create
collection_data_ptr - The CnxCollectionData(CollectionType) containing the element default-constructor, element copy-constructor, element destructor, and memory allocator to use
Returns a new CnxVector(T)

Creates a new CnxVector(T) with:

  1. defaulted initial capacity
  2. possibly user-provided element default-constructor
  3. possibly user-provided associated element copy-constructor
  4. possibly user-provided element destructor
  5. user-provided memory allocator

#define cnx_vector_new_with_allocator_and_collection_data(T, allocator, collection_data_ptr)
#include <include/Cnx/vector/VectorDef.h>

Creates a new CnxVector(T) with defaulted capacity and provided associated functions and memory allocator.

Parameters
T - The element type of the CnxVector(T) instantiation to create
allocator - The CnxAllocator to use for memory allocations
collection_data_ptr - The CnxCollectionData(CollectionType) containing the element default-constructor, element copy-constructor, element destructor, and memory allocator to use
Returns a new CnxVector(T)

Creates a new CnxVector(T) with:

  1. defaulted initial capacity
  2. possibly user-provided element default-constructor
  3. possibly user-provided associated element copy-constructor
  4. possibly user-provided element destructor
  5. user-provided memory allocator

#define cnx_vector_new_with_capacity(T, capacity)
#include <include/Cnx/vector/VectorDef.h>

Creates a new CnxVector(T) with at least the given capacity and defaulted associated functions.

Parameters
T - The element type of the CnxVector(T) instantiation to create
capacity - The initial capacity of the vector
Returns a new CnxVector(T)

Creates a new CnxVector(T) with:

  1. given initial capacity
  2. defaulted associated element default-constructor
  3. defaulted associated element copy-constructor
  4. defaulted associated element destructor
  5. defaulted memory allocator

#define cnx_vector_new_with_capacity_and_allocator(T, capacity, allocator)
#include <include/Cnx/vector/VectorDef.h>

Creates a new CnxVector(T) with at least the given capacity, defaulted associated functions, and provided memory allocator.

Parameters
T - The element type of the CnxVector(T) instantiation to create
capacity - The initial capacity of the vector
allocator - The CnxAllocator to use for memory allocations
Returns a new CnxVector(T)

Creates a new CnxVector(T) with:

  1. given initial capacity
  2. defaulted associated element default-constructor
  3. defaulted associated element copy-constructor
  4. defaulted associated element destructor
  5. defaulted memory allocator

#define cnx_vector_new_with_capacity_and_collection_data(T, capacity, collection_data_ptr)
#include <include/Cnx/vector/VectorDef.h>

Creates a new CnxVector(T) with at least the given capacity and provided associated functions.

Parameters
T - The element type of the CnxVector(T) instantiation to create
capacity - The initial capacity of the vector
collection_data_ptr - The CnxCollectionData(CollectionType) containing the element default-constructor, element copy-constructor, element destructor, and memory allocator to use
Returns a new CnxVector(T)

Creates a new CnxVector(T) with:

  1. given initial capacity
  2. possibly user-provided associated element default-constructor
  3. possibly user-provided associated element copy-constructor
  4. possibly user-provided associated element destructor
  5. user-provided memory allocator

#define cnx_vector_new_with_capacity_allocator_and_collection_data(T, capacity, allocator, collection_data_ptr)
#include <include/Cnx/vector/VectorDef.h>

Creates a new CnxVector(T) with at least the given capacity and provided associated functions and memory allocator.

Parameters
T - The element type of the CnxVector(T) instantiation to create
capacity - The initial capacity of the vector
allocator - The CnxAllocator to use for memory allocations
collection_data_ptr - The CnxCollectionData(CollectionType) containing the element default-constructor, element copy-constructor, element destructor, and memory allocator to use
Returns a new CnxVector(T)

Creates a new CnxVector(T) with:

  1. given initial capacity
  2. possibly user-provided associated element default-constructor
  3. possibly user-provided associated element copy-constructor
  4. possibly user-provided associated element destructor
  5. user-provided memory allocator

#define cnx_vector_clone(self)
#include <include/Cnx/vector/VectorDef.h>

Clones the given CnxVector(T)

Parameters
self - The CnxVector(T) to clone
Returns a clone of the given vector

Creates a deep copy of the given CnxVector(T) calling the associated copy constructor for each element stored in it.

#define cnx_vector_at_mut(self, index)
#include <include/Cnx/vector/VectorDef.h>

Returns a mutable reference to the element at the given index into the given CnxVector(T)

Parameters
self - The CnxVector(T) to get an element from
index - The index of the desired element
Returns a mutable reference to the element at the given index

#define cnx_vector_at(self, index)
#include <include/Cnx/vector/VectorDef.h>

Returns a const reference to the element at the given index into the given CnxVector(T)

Parameters
self - The CnxVector(T) to get an element from
index - The index of the desired element
Returns a const reference to the element at the given index

#define cnx_vector_front_mut(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a mutable reference to the first element in the given CnxVector(T)

Parameters
self - The CnxVector(T) to get the first element from
Returns a mutable reference to the first element

#define cnx_vector_front(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a const reference to the first element in the given CnxVector(T)

Parameters
self - The CnxVector(T) to get the first element from
Returns a const reference to the first element

#define cnx_vector_back_mut(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a mutable reference to the last element in the given CnxVector(T)

Parameters
self - The CnxVector(T) to get the last element from
Returns a mutable reference to the last element

#define cnx_vector_back(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a const reference to the last element in the given CnxVector(T)

Parameters
self - The CnxVector(T) to get the last element from
Returns a const reference to the last element

#define cnx_vector_data_mut(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a pointer to the mutable raw array containing the given CnxVector(T)'s elements.

Parameters
self - The CnxVector(T) to get the raw array from
Returns a pointer to the raw array

#define cnx_vector_data(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a pointer to the const raw array containing the given CnxVector(T)'s elements.

Parameters
self - The CnxVector(T) to get the raw array from
Returns a pointer to the raw array

#define cnx_vector_is_empty(self)
#include <include/Cnx/vector/VectorDef.h>

Returns whether the given CnxVector(T)is empty.

Parameters
self - The CnxVector(T) to check for emptiness
Returns true if empty, false otherwise

#define cnx_vector_is_full(self)
#include <include/Cnx/vector/VectorDef.h>

Returns whether the given CnxVector(T) is full (size equals capacity)

Parameters
self - The CnxVector(T) to check for fullness
Returns true if full, false otherwise

#define cnx_vector_size(self)
#include <include/Cnx/vector/VectorDef.h>

Returns the current size of the given CnxVector(T)

Parameters
self - The CnxVector(T) to get the size of
Returns the size of the CnxVector(T)

#define cnx_vector_max_size(T)
#include <include/Cnx/vector/VectorDef.h>

Returns the maximum possible size of a CnxVector(T) containing type T

Parameters
T - The element type of the CnxVector(T) instantiation
Returns The maximum possible size

#define cnx_vector_capacity(self)
#include <include/Cnx/vector/VectorDef.h>

Returns the current capacity of the given CnxVector(T)

Parameters
self - The CnxVector(T) to get the capacity of
Returns the capacity of the CnxVector(T)

#define cnx_vector_reserve(self, new_capacity)
#include <include/Cnx/vector/VectorDef.h>

Ensures enough memory to store at least new_capacity number of elements in the given CnxVector(T), reallocating if necessary.

Parameters
self - The CnxVector(T) to reserve memory for
new_capacity - The desired minimum number of storable elements

#define cnx_vector_resize(self, new_size)
#include <include/Cnx/vector/VectorDef.h>

Resizes the given CnxVector(T) to new_size number of elements. If new_size is greater than the current size, this will allocate memory if necessary and default-construct new elements. If new_size is less than the current size, this will destruct size - new_size number of elements and, if new_size is less than the SSO capacity, deallocate memory.

Parameters
self - The CnxVector(T) to resize
new_size - The desired size of the CnxVector(T)

#define cnx_vector_shrink_to_fit(self)
#include <include/Cnx/vector/VectorDef.h>

Shrinks the memory allocation for the given CnxVector(T) to match its current size.

Parameters
self - The CnxVector(T) to shrink

#define cnx_vector_clear(self)
#include <include/Cnx/vector/VectorDef.h>

Clears the contents of the given CnxVector(T), destructing all of its elements.

Parameters
self - The CnxVector(T) to clear

#define cnx_vector_push_back(self, element)
#include <include/Cnx/vector/VectorDef.h>

Appends the given element to the end of the given CnxVector(T), reallocating memory if necessary.

Parameters
self - The CnxVector(T) to append to
element - The element to append

#define cnx_vector_pop_back(self)
#include <include/Cnx/vector/VectorDef.h>

Returns the last element in the given CnxVector(T) and removes it, if the size is greater than zero.

Parameters
self - The CnxVector(T) to get the last element from
Returns Some(T) if size > 0, otherwise None(T)

#define cnx_vector_pop_front(self)
#include <include/Cnx/vector/VectorDef.h>

Returns the first element in the given CnxVector(T) and removes it, if the size is greater than zero.

Parameters
self - The CnxVector(T) to get the last element from
Returns Some(T) if size > 0, otherwise None(T)

#define cnx_vector_insert(self, element, index)
#include <include/Cnx/vector/VectorDef.h>

Inserts the given element at the given index in the given CnxVector(T), moving elements backward in the vector if necessary.

Parameters
self - The CnxVector(T) to insert into
element - The element to insert
index - The index at which to insert element

#define cnx_vector_erase(self, index)
#include <include/Cnx/vector/VectorDef.h>

Removes the element at the given index from the given CnxVector(T), moving elements forward in the vector if necessary.

Parameters
self - The CnxVector(T) to remove an element from
index - The index of the element to remove

#define cnx_vector_erase_n(self, index, num_elements)
#include <include/Cnx/vector/VectorDef.h>

Removes num_elements elements from the given CnxVector(T), starting with the element at index, and moving elements forward in the vector afterward, if necessary.

Parameters
self - The CnxVector(T) to remove elements from
index - The index to begin removal at
num_elements - The number of elements to remove from the vector

#define cnx_vector_free(self)
#include <include/Cnx/vector/VectorDef.h>

Frees the given CnxVector(T), calling the element destructor on each element and freeing any allocated memory.

Parameters
self - The CnxVector(T) to free

#define cnx_vector_begin(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a CnxRandomAccessIterator into the mutable iteration of the given CnxVector(T), starting at the beginning of the iteration (pointing at the beginning of the vector)

Parameters
self - The CnxVector(T) to get an iterator to
Returns a random access iterator at the beginning of the vector

#define cnx_vector_end(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a CnxRandomAccessIterator into the mutable iteration of the given CnxVector(T), starting at the end of the iteration (pointing at the end of the vector)

Parameters
self - The CnxVector(T) to get an iterator to
Returns a random access iterator at the end of the vector

#define cnx_vector_rbegin(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a CnxRandomAccessIterator into the mutable iteration of the given CnxVector(T), starting at the beginning of the reversed iteration (pointing at the end of the vector)

Parameters
self - The CnxVector(T) to get an iterator to
Returns a random access iterator at the beginning of the reversed vector

#define cnx_vector_rend(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a CnxRandomAccessIterator into the mutable iteration of the given CnxVector(T), starting at the end of the reversed iteration (pointing at the beginning of the vector)

Parameters
self - The CnxVector(T) to get an iterator to
Returns a random access iterator at the end of the reversed vector

#define cnx_vector_iterator_equals(first, second)
#include <include/Cnx/vector/VectorDef.h>

Returns whether the given pair of iterators are equal (they belong to the same collection and point to the same element), IE: if first == second

Parameters
first - The LHS iterator of the equality check
second - The RHS iterator of the equality check
Returns true if they are equal, false otherwise

#define cnx_vector_cbegin(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a CnxRandomAccessIterator into the const iteration of the given CnxVector(T), starting at the beginning of the iteration (pointing at the beginning of the vector)

Parameters
self - The CnxVector(T) to get an iterator to
Returns a random access iterator at the beginning of the vector

#define cnx_vector_cend(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a CnxRandomAccessIterator into the const iteration of the given CnxVector(T), starting at the end of the iteration (pointing at the end of the vector)

Parameters
self - The CnxVector(T) to get an iterator to
Returns a random access iterator at the end of the vector

#define cnx_vector_crbegin(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a CnxRandomAccessIterator into the const iteration of the given CnxVector(T), starting at the beginning of the reversed iteration (pointing at the end of the vector)

Parameters
self - The CnxVector(T) to get an iterator to
Returns a random access iterator at the beginning of the reversed vector

#define cnx_vector_crend(self)
#include <include/Cnx/vector/VectorDef.h>

Returns a CnxRandomAccessIterator into the const iteration of the given CnxVector(T), starting at the end of the reversed iteration (pointing at the beginning of the vector)

Parameters
self - The CnxVector(T) to get an iterator to
Returns a random access iterator at the end of the reversed vector

#define cnx_vector_const_iterator_equals(first, second)
#include <include/Cnx/vector/VectorDef.h>

Returns whether the given pair of const iterators are equal (they belong to the same collection and point to the same element), IE: if first == second

Parameters
first - The LHS iterator of the equality check
second - The RHS iterator of the equality check

#define CnxScopedVector(T)
#include <include/Cnx/vector/VectorDef.h>

declare a CnxVector(T) variable with this attribute to have Cnx_vector_free automatically called on it at scope end

Parameters
T - The element type of the CnxVector(T) instantiation