Skip to content

Commit 75d0fe7

Browse files
committed
final draft of proposal
1 parent 6864a9f commit 75d0fe7

File tree

1 file changed

+92
-0
lines changed

1 file changed

+92
-0
lines changed

docs/dyn_array.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
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

Comments
 (0)