VLA for C++: dynarray

简中版介绍在这里

繁中版介紹在這裏

A header-only library, providing C99 VLA-like class for C++. The VLA extension provide by compiler is not required.

Depencencies

C++ 14 or 17

C++ Standard Library

Purpose of this project

C Language provided VLA since C99. This is my favourite feature in C. A similar library was almost became a part of C++14 standard: N3662 but it's got removed before release year of C++14.

A proposal P0785R0 was proposed after C++14, but it's still not a part of C++ standard.

The most obvious feature of VLA is, a contiguous memory space will be allocated for a dynamic defined array, including multi-dimensional array. The size of this array will not (and cannot) be changed after definition.

vector can also do the same thing for multi-dimensional array, if use it with custom allocator to allocate contiguous memory space. But if the requirement is ‘I don't want to change the size after definition’, almost nothing we can do for it. The only thing we can do is, write a note or comment to inform everyone ‘Do not use push_back or emplace_back’.

Since std:dynarray was removed before C++14 release, I've modified std::dynarray and extended it to provide multi-dimensional array (nested-array) support. The behaviour of modified dynarray is designed between VLA and vector. It will allocates a contiguous memory space as VLA does, and uses C++ iterator as vector does.

File Description

Doxyfile

Create documents with doxygen.

dynarray.hpp

Proterotype version, use the same structure (class) all the time. The size is largest.

Requires C++17.

vla_nest/dynarray.hpp

Template specialised version. Medium size.

Requires C++14.

vla_nest/dynarray_lite.hpp

Lite version, does not guaranteed to provide contiguous memory spaces for multi-dimensional array.

Requires C++17.

vla_nest/dynarray_mini.hpp

Using std::unique_ptr<[]> inside the dynarray, does not guaranteed to provide contiguous memory spaces for multi-dimensional array. Custom allocator cannot be used in this version.

Requires C++17.

vla_neat/dynarray.hpp

Non-nested version from the appearance. The internal implementation is a nested-array as before. The usage is difference from above implementations.

Requires C++17.

Version comparison

| Version Description | File¹ | C++ Version | sizeof dynarray² (Outermost; middle layer per node³) | sizeof dynarray² (Innermost per node³) | sizeof dynarray² (one-dimensional array) | contiguous memory spaces for multi-dimensional array | custom allocator can be used | | ------------------------------- | ---------------------------- | ----------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------- | ---------------------------------------------------- | ---------------------------- | | Proterotype version | dynarray.hpp | C++17 | 48 bytes | 48 bytes | 48 bytes | Yes | Yes | | Partial template specialisation | vla_nest/dynarray.hpp | C++14 | 48 bytes | 32 bytes | 32 bytes | Yes | Yes | | Lite Version | vla_nest/dynarray_lite.hpp | C++17 | 24 bytes | 24 bytes | 24 bytes | No | Yes | | Mini Version | vla_nest/dynarray_mini.hpp | C++17 | 16 bytes | 16 bytes | 16 bytes | No | No | | Neat Version | vla_neat/dynarray.hpp | C++17 | 48 bytes | 32 bytes | 32 bytes | Yes | Yes |

¹ Use one of the .hpp file only. Please don't use them all at the same time.

² Aligned

³ Multi-dimensional array

How to use

Proterotype and each ‘Nest’ Versions:

#include <iostream>
#include "dynarray.hpp"

int main()
{
    int x = 100, y = 200;
    int value = 5;
    vla::dynarray<vla::dynarray<int>> vla_array(x, y, value);
    std::cout << vla_array[8][16] << std::endl;    // 5
    vla_array[8][16] = 20;
    std::cout << vla_array[8][16] << std::endl;    // 20
}

Neat Version:

#include <iostream>
#include "dynarray.hpp"

int main()
{
    int x = 100, y = 200;
    int value = 5;
    vla::dynarray<int, 2> vla_array(x, y, value);
    std::cout << vla_array[8][16] << std::endl;    // 5
    vla_array[8][16] = 20;
    std::cout << vla_array[8][16] << std::endl;    // 20
}

Create a one-dimensional array

1. Create an array with variable

int count = 100;
vla::dynarray<int> vla_array(count); 

Equivalent to

int count = 100;
int vla_array[count];
memset(vla_array, 0, sizeof vla_array);

For Neat Version, you can also

int count = 100;
vla::dynarray<int> vla_array(count);
vla::dynarray<int, 1> vla_array_other(count);

2. Create an array with initial value

int count = 100;
vla::dynarray<int> vla_array(count, 256); // initial value 256

Equivalent to

int count = 100;
int vla_array[count];
memset(vla_array, 256, sizeof vla_array);

3. Create a zero-size array

vla::dynarray<int> vla_array;

or

vla::dynarray<int> vla_array(0); 

or (Neat Version only)

vla::dynarray<int, 0> vla_array;

4. Initialise current dynarray or replace current dynarray with another dynarray

vla::dynarray<int> vla_array(vla::dynarray<int>(100, 256));

vla::dynarray<int> vla_array_a(100);
vla::dynarray<int> vla_array_b(vla_array_a);

vla::dynarray<int> vla_array_a(100);
vla::dynarray<int> vla_array_b;
vla_array_b = vla_array_a;

5. Initialization list

vla::dynarray<int> vla_array = {2, 4, 8, 16};

vla::dynarray<int> vla_array;
vla_array = {2, 4, 8, 16};

6. Iterator

int raw_array[100] = {};
vla::dynarray<int> vla_array(std::begin(raw_array), std::end(raw_array));

vla::dynarray<int> vla_array_a(100);
vla::dynarray<int> vla_array_b(vla_array_a.begin() + 20, vla_array_a.end());

Create a 2D array

1. Create an array with variable

Nest Versions:

int x = 100, y = 200;
vla::dynarray<vla::dynarray<int>> vla_array(x, y); 

Equivalent to

int x = 100, y = 200;
int vla_array[x][y];
memset(vla_array, 0, sizeof vla_array);

Neat Version:

int x = 100, y = 200;
vla::dynarray<int, 2> vla_array(x, y); 

2. Create an array with initial value

Nest Versions:

int x = 100, y = 200;
vla::dynarray<vla::dynarray<int>> vla_array(x, y, 256); 

Equivalent to

int x = 100, y = 200;
int vla_array[x][y];
memset(vla_array, 256, sizeof vla_array);

Neat Version:

int x = 100, y = 200;
vla::dynarray<int, 2> vla_array(x, y, 256); 

3. Create a zero-size array

As long as the number of parameters is less than the actual dimension, or one of the size is set as zero, a zero-size array will be created.

Nest Versions:

vla::dynarray<vla::dynarray<int>> vla_array;

or

vla::dynarray<vla::dynarray<int>> vla_array(0); 

or

vla::dynarray<vla::dynarray<int>> vla_array(30, 0); 

or

vla::dynarray<vla::dynarray<int>> vla_array(0, 5); 

Neat Version:

vla::dynarray<int, 2> vla_array;

or

vla::dynarray<int, 2> vla_array(0); 

or

vla::dynarray<int, 2> vla_array(30, 0); 

or

vla::dynarray<int, 2> vla_array(0, 5); 

4. Initialise current dynarray or replace current dynarray with another dynarray

Nest Versions:

vla::dynarray<vla::dynarray<int>> vla_array(vla::dynarray<vla::dynarray<int>>(100, 200));

vla::dynarray<vla::dynarray<int>> vla_array_a(100, 300);
vla::dynarray<vla::dynarray<int>> vla_array_b(vla_array_a);

vla::dynarray<vla::dynarray<int>> vla_array_a(100, 200, 10);
vla::dynarray<vla::dynarray<int>> vla_array_b(100, 200);
vla_array_b = vla_array_a;	// all elements of vla_array_b have value 10

Neat Version:

vla::dynarray<int, 2> vla_array(vla::dynarray<int, 2>(100, 200));

vla::dynarray<int, 2> vla_array_a(100, 300);
vla::dynarray<int, 2> vla_array_b(vla_array_a);

vla::dynarray<int, 2> vla_array_a(100, 200, 10);
vla::dynarray<int, 2> vla_array_b(100, 200);
vla_array_b = vla_array_a;	// all elements of vla_array_b have value 10

5. Initialization list

   Nest Version:

   • create 3 × 3 array

   vla::dynarray<vla::dynarray<int>> array33 = { {1, 2, 3 }, {3, 2, 1}, {2, 4, 6} };
   

   • create 3 × 3 array

   vla::dynarray<vla::dynarray<int>> array33(3, 3);
   array33 = { {1, 2, 3 }, {3, 2, 1}, {2, 4, 6} };
   

   or (Not