|
| 1 | +<!-- $ pandoc -V geometry:margin=1in -V colorlinks=true -o dyn_array.pdf dyn_array.md --> |
| 2 | + |
| 3 | +# `gsl::dyn_array<T, Allocator>` |
| 4 | + |
| 5 | +### Revision History |
| 6 | + |
| 7 | +| Date | Author | Description | |
| 8 | +| ---- | ------ | ----------- | |
| 9 | +| Jan 16, 2025 | Carson Radtke (Microsoft) | Initial draft. | |
| 10 | + |
| 11 | +A specification to guide the implementation of `gsl::dyn_array`. This is a dynamic array |
| 12 | +that is intended to be a replacement for slinging around raw pointers and sizes. |
| 13 | +Notably, it _owns_ all of its elements. It can be thought of like a... |
| 14 | + |
| 15 | +* `std::array` except the size is specified at runtime. |
| 16 | +* `std::vector` except it can neither shrink nor grow. |
| 17 | + |
| 18 | +### Container Named Requirements |
| 19 | +In order to allow element access using iterators and to align with various container |
| 20 | +idioms, `gsl::dyn_array` should satisfy the following named requirements: |
| 21 | + |
| 22 | +* Container ([link](https://en.cppreference.com/w/cpp/named_req/Container)) |
| 23 | +* ReversibleContainer ([link](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer)) |
| 24 | +* ContiguousContainer ([link](https://en.cppreference.com/w/cpp/named_req/ContiguousContainer)) |
| 25 | +* SequenceContainer ([link](https://en.cppreference.com/w/cpp/named_req/SequenceContainer)) |
| 26 | +* AllocatorAwareContainer ([link](https://en.cppreference.com/w/cpp/named_req/AllocatorAwareContainer)) |
| 27 | + |
| 28 | +### Construction |
| 29 | +In addition to the constructors required by the named requirements (default, copy, and |
| 30 | +move), `gsl::dyn_array` will support the following constructors: |
| 31 | + |
| 32 | +* Construct a `dyn_array` with `n` elements, each constructed with `Args...`: |
| 33 | +```c++ |
| 34 | +template <typename... Args> |
| 35 | +constexpr explicit dyn_array(size_t n, Args&&...); |
| 36 | +template <typename... Args> |
| 37 | +constexpr dyn_array(size_t n, const Allocator &, Args&&...); |
| 38 | +``` |
| 39 | +
|
| 40 | +* Construct a `dyn_array` with elements from the range `[first, last)`: |
| 41 | +```c++ |
| 42 | +template <typename InputIt> |
| 43 | +constexpr dyn_array(InputIt first, InputIt last) |
| 44 | +template <typename InputIt> |
| 45 | +constexpr dyn_array(InputIt first, InputIt last, const Allocator & alloc = Allocator()); |
| 46 | +``` |
| 47 | + |
| 48 | +* Construct a `dyn_array` with elements from the initializer list: |
| 49 | +```c++ |
| 50 | +constexpr dyn_array(std::initializer_list<T>); |
| 51 | +``` |
| 52 | +
|
| 53 | +* Construct a `dyn_array` with elements from the range `R`: |
| 54 | +```c++ |
| 55 | +template <container-compatible-range<T> R> constexpr dyn_array(R&&); |
| 56 | +``` |
| 57 | + |
| 58 | +### Operations |
| 59 | +In addition to the operations required by the named requirements, `gsl::dyn_array` will |
| 60 | +support the following operations: |
| 61 | + |
| 62 | +* Access the specified element **_with bounds checking_**: |
| 63 | +```c++ |
| 64 | +constexpr T& operator[](size_t); |
| 65 | +constexpr const T& operator[](size_t) const |
| 66 | +``` |
| 67 | + |
| 68 | +* Access the underlying array: |
| 69 | +```c++ |
| 70 | +constexpr T* data() noexcept; |
| 71 | +constexpr const T* data() const noexcept; |
| 72 | +``` |
| 73 | + |
| 74 | +* Return the number of elements in the `dyn_array`: |
| 75 | +```c++ |
| 76 | +constexpr size_t size() const noexcept; |
| 77 | +``` |
| 78 | + |
| 79 | +#### Note: Why no push_back (and friends)? |
| 80 | +`gsl::dyn_array` is intended to be a fixed-size array and all objects should be |
| 81 | +constructed at creation. Moreover, the memory overhead of storing another member |
| 82 | +variable to track where to push the next item is not desired. |
| 83 | + |
| 84 | +### Bounds Checking Semantics |
| 85 | +If an out-of-bounds access (read or write) is attempted, `gsl::dyn_array` should follow |
| 86 | +the contract violation strategy outlined in [GSL.assert: Assertions](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#gslassert-assertions). |
| 87 | + |
| 88 | +### References |
| 89 | +* [C++ Named Requirements](https://en.cppreference.com/w/cpp/named_req) |
| 90 | +* [Microsoft/GSL #1169](https://github.com/microsoft/GSL/issues/1169) |
| 91 | +* [isocpp/CppCoreGuidelines #2244](https://github.com/isocpp/CppCoreGuidelines/issues/2244) |
| 92 | +* [n3662](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3662.html) |
0 commit comments