docs/headers.md

   1 The Guidelines Support Library (GSL) interface is very lightweight and exposed via a header-only library. This document attempts to document all of the headers and their exposed classes and functions.
   2
   3 Types and functions are exported in the namespace `gsl`.
   4
   5 See [GSL: Guidelines support library](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-gsl)
   6
   7 # <a name="H" />Headers
   8
   9 - [`<algorithms>`](#user-content-H-algorithms)
  10 - [`<assert>`](#user-content-H-assert)
  11 - [`<byte>`](#user-content-H-byte)
  12 - [`<gsl>`](#user-content-H-gsl)
  13 - [`<narrow>`](#user-content-H-narrow)
  14 - [`<pointers>`](#user-content-H-pointers)
  15 - [`<span>`](#user-content-H-span)
  16 - [`<span_ext>`](#user-content-H-span_ext)
  17 - [`<zstring>`](#user-content-H-zstring)
  18 - [`<util>`](#user-content-H-util)
  19
  20 ## <a name="H-algorithms" />`<algorithms>`
  21
  22 This header contains some common algorithms that have been wrapped in GSL safety features.
  23
  24 - [`gsl::copy`](#user-content-H-algorithms-copy)
  25
  26 ### <a name="H-algorithms-copy" />`gsl::copy`
  27
  28 ```cpp
  29 template <class SrcElementType, std::size_t SrcExtent, class DestElementType,
  30           std::size_t DestExtent>
  31 void copy(span<SrcElementType, SrcExtent> src, span<DestElementType, DestExtent> dest);
  32 ```
  33
  34 This function copies the content from the `src` [`span`](#user-content-H-span-span) to the `dest` [`span`](#user-content-H-span-span). It [`Expects`](#user-content-H-assert-expects)
  35 that the destination `span` is at least as large as the source `span`.
  36
  37 ## <a name="H-assert" />`<assert>`
  38
  39 This header contains some macros used for contract checking and suppressing code analysis warnings.
  40
  41 See [GSL.assert: Assertions](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-assertions)
  42
  43 - [`GSL_SUPPRESS`](#user-content-H-assert-gsl_suppress)
  44 - [`Expects`](#user-content-H-assert-expects)
  45 - [`Ensures`](#user-content-H-assert-ensures)
  46
  47 ### <a name="H-assert-gsl_suppress" />`GSL_SUPPRESS`
  48
  49 This macro can be used to suppress a code analysis warning.
  50
  51 The core guidelines request tools that check for the rules to respect suppressing a rule by writing
  52 `[[gsl::suppress(tag)]]` or `[[gsl::suppress(tag, justification: "message")]]`.
  53
  54 Clang does not use exactly that syntax, but requires `tag` to be put in double quotes `[[gsl::suppress("tag")]]`.
  55
  56 For portable code you can use `GSL_SUPPRESS(tag)`.
  57
  58 See [In.force: Enforcement](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#inforce-enforcement).
  59
  60 ### <a name="H-assert-expects" />`Expects`
  61
  62 This macro can be used for expressing a precondition. If the precondition is not held, then `std::terminate` will be called.
  63
  64 See [I.6: Prefer `Expects()` for expressing preconditions](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#i6-prefer-expects-for-expressing-preconditions)
  65
  66 ### <a name="H-assert-ensures" />`Ensures`
  67
  68 This macro can be used for expressing a postcondition. If the postcondition is not held, then `std::terminate` will be called.
  69
  70 See [I.8: Prefer `Ensures()` for expressing postconditions](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#i8-prefer-ensures-for-expressing-postconditions)
  71
  72 ## <a name="H-byte" />`<byte>`
  73
  74 This header contains the definition of a byte type, implementing `std::byte` before it was standardized into C++17.
  75
  76 - [`gsl::byte`](#user-content-H-byte-byte)
  77
  78 ### <a name="H-byte-byte" />`gsl::byte`
  79
  80 If `GSL_USE_STD_BYTE` is defined to be `1`, then `gsl::byte` will be an alias to `std::byte`.
  81 If `GSL_USE_STD_BYTE` is defined to be `0`, then `gsl::byte` will be a distinct type that implements the concept of byte.
  82 If `GSL_USE_STD_BYTE` is not defined, then the header file will check if `std::byte` is available (C\+\+17 or higher). If yes,
  83 `gsl::byte` will be an alias to `std::byte`, otherwise `gsl::byte` will be a distinct type that implements the concept of byte.
  84
  85 &#x26a0; Take care when linking projects that were compiled with different language standards (before C\+\+17 and C\+\+17 or higher).
  86 If you do so, you might want to `#define GSL_USE_STD_BYTE 0` to a fixed value to be sure that both projects use exactly
  87 the same type. Otherwise you might get linker errors.
  88
  89 See [SL.str.5: Use `std::byte` to refer to byte values that do not necessarily represent characters](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rstr-byte)
  90
  91 ### Non-member functions
  92
  93 ```cpp
  94 template <class IntegerType, class = std::enable_if_t<std::is_integral<IntegerType>::value>>
  95 constexpr byte& operator<<=(byte& b, IntegerType shift) noexcept;
  96
  97 template <class IntegerType, class = std::enable_if_t<std::is_integral<IntegerType>::value>>
  98 constexpr byte operator<<(byte b, IntegerType shift) noexcept;
  99
 100 template <class IntegerType, class = std::enable_if_t<std::is_integral<IntegerType>::value>>
 101 constexpr byte& operator>>=(byte& b, IntegerType shift) noexcept;
 102
 103 template <class IntegerType, class = std::enable_if_t<std::is_integral<IntegerType>::value>>
 104 constexpr byte operator>>(byte b, IntegerType shift) noexcept;
 105 ```
 106
 107 Left or right shift a `byte` by a given number of bits.
 108
 109 ```cpp
 110 constexpr byte& operator|=(byte& l, byte r) noexcept;
 111 constexpr byte operator|(byte l, byte r) noexcept;
 112 ```
 113
 114 Bitwise "or" of two `byte`s.
 115
 116 ```cpp
 117 constexpr byte& operator&=(byte& l, byte r) noexcept;
 118 constexpr byte operator&(byte l, byte r) noexcept;
 119 ```
 120
 121 Bitwise "and" of two `byte`s.
 122
 123 ```cpp
 124 constexpr byte& operator^=(byte& l, byte r) noexcept;
 125 constexpr byte operator^(byte l, byte r) noexcept;
 126 ```
 127
 128 Bitwise xor of two `byte`s.
 129
 130 ```cpp
 131 constexpr byte operator~(byte b) noexcept;
 132 ```
 133
 134 Bitwise negation of a `byte`. Flips all bits. Zeroes become ones, ones become zeroes.
 135
 136 ```cpp
 137 template <class IntegerType, class = std::enable_if_t<std::is_integral<IntegerType>::value>>
 138 constexpr IntegerType to_integer(byte b) noexcept;
 139 ```
 140
 141 Convert the given `byte` value to an integral type.
 142
 143 ```cpp
 144 template <typename T>
 145 constexpr byte to_byte(T t) noexcept;
 146 ```
 147
 148 Convert the given value to a `byte`. The template requires `T` to be an `unsigned char` so that no data loss can occur.
 149 If you want to convert an integer constant to a `byte` you probably want to call `to_byte<integer constant>()`.
 150
 151 ```cpp
 152 template <int I>
 153 constexpr byte to_byte() noexcept;
 154 ```
 155
 156 Convert the given value `I` to a `byte`. The template requires `I` to be in the valid range 0..255 for a `gsl::byte`.
 157
 158 ## <a name="H-gsl" />`<gsl>`
 159
 160 This header is a convenience header that includes all other [GSL headers](#user-content-H).
 161 Since `<narrow>` requires exceptions, it will only be included if exceptions are enabled.
 162
 163 ## <a name="H-narrow" />`<narrow>`
 164
 165 This header contains utility functions and classes, for narrowing casts, which require exceptions. The narrowing-related utilities that don't require exceptions are found inside [util](#user-content-H-util).
 166
 167 See [GSL.util: Utilities](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-utilities)
 168
 169 - [`gsl::narrowing_error`](#user-content-H-narrow-narrowing_error)
 170 - [`gsl::narrow`](#user-content-H-narrow-narrow)
 171
 172 ### <a name="H-narrow-narrowing_error" />`gsl::narrowing_error`
 173
 174 `gsl::narrowing_error` is the exception thrown by [`gsl::narrow`](#user-content-H-narrow-narrow) when a narrowing conversion fails. It is derived from `std::exception`.
 175
 176 ### <a name="H-narrow-narrow" />`gsl::narrow`
 177
 178 `gsl::narrow<T>(x)` is a named cast that does a `static_cast<T>(x)` for narrowing conversions with no signedness promotions.
 179 If the argument `x` cannot be represented in the target type `T`, then the function throws a [`gsl::narrowing_error`](#user-content-H-narrow-narrowing_error) (e.g., `narrow<unsigned>(-42)` and `narrow<char>(300)` throw).
 180
 181 Note: compare [`gsl::narrow_cast`](#user-content-H-util-narrow_cast) in header [util](#user-content-H-util).
 182
 183 See [ES.46: Avoid lossy (narrowing, truncating) arithmetic conversions](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-narrowing) and [ES.49: If you must use a cast, use a named cast](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts-named)
 184
 185 ## <a name="H-pointers" />`<pointers>`
 186
 187 This header contains some pointer types.
 188
 189 See [GSL.view](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-views)
 190
 191 - [`gsl::unique_ptr`](#user-content-H-pointers-unique_ptr)
 192 - [`gsl::shared_ptr`](#user-content-H-pointers-shared_ptr)
 193 - [`gsl::owner`](#user-content-H-pointers-owner)
 194 - [`gsl::not_null`](#user-content-H-pointers-not_null)
 195 - [`gsl::strict_not_null`](#user-content-H-pointers-strict_not_null)
 196
 197 ### <a name="H-pointers-unique_ptr" />`gsl::unique_ptr`
 198
 199 `gsl::unique_ptr` is an alias to `std::unique_ptr`.
 200
 201 See [GSL.owner: Ownership pointers](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-ownership)
 202
 203 ### <a name="H-pointers-shared_ptr" />`gsl::shared_ptr`
 204
 205 `gsl::shared_ptr` is an alias to `std::shared_ptr`.
 206
 207 See [GSL.owner: Ownership pointers](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-ownership)
 208
 209 ### <a name="H-pointers-owner" />`gsl::owner`
 210
 211 `gsl::owner<T>` is designed as a safety mechanism for code that must deal directly with raw pointers that own memory. Ideally such code should be restricted to the implementation of low-level abstractions. `gsl::owner` can also be used as a stepping point in converting legacy code to use more modern RAII constructs such as smart pointers.
 212 `T` must be a pointer type (`std::is_pointer<T>`).
 213
 214 A `gsl::owner<T>` is a typedef to `T`. It adds no runtime overhead whatsoever, as it is purely syntactic and does not add any runtime checks.  Instead, it serves as an annotation for static analysis tools which check for memory safety, and as a code comprehension guide for human readers.
 215
 216 See Enforcement section of [C.31: All resources acquired by a class must be released by the class’s destructor](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rc-dtor-release).
 217
 218 ### <a name="H-pointers-not_null" />`gsl::not_null`
 219
 220 `gsl::not_null<T>` restricts a pointer or smart pointer to only hold non-null values. It has no size overhead over `T`.
 221
 222 The checks for ensuring that the pointer is not null are done in the constructor. There is no overhead when retrieving or dereferencing the checked pointer.
 223 When a nullptr check fails, `std::terminate` is called.
 224
 225 See [F.23: Use a `not_null<T>` to indicate that “null” is not a valid value](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr)
 226
 227 #### Member functions
 228
 229 ##### Construct/Copy
 230
 231 ```cpp
 232 template <typename U, typename = std::enable_if_t<std::is_convertible<U, T>::value>>
 233 constexpr not_null(U&& u);
 234
 235 template <typename = std::enable_if_t<!std::is_same<std::nullptr_t, T>::value>>
 236 constexpr not_null(T u);
 237 ```
 238
 239 Constructs a `gsl_owner<T>` from a pointer that is convertible to `T` or that is a `T`. It [`Expects`](#user-content-H-assert-expects) that the provided pointer is not `== nullptr`.
 240
 241 ```cpp
 242 template <typename U, typename = std::enable_if_t<std::is_convertible<U, T>::value>>
 243 constexpr not_null(const not_null<U>& other);
 244 ```
 245
 246 Constructs a `gsl_owner<T>` from another `gsl_owner` where the other pointer is convertible to `T`. It [`Expects`](#user-content-H-assert-expects) that the provided pointer is not `== nullptr`.
 247
 248 ```cpp
 249 not_null(const not_null& other) = default;
 250 not_null& operator=(const not_null& other) = default;
 251 ```
 252
 253 Copy construction and assignment.
 254
 255 ```cpp
 256 not_null(std::nullptr_t) = delete;
 257 not_null& operator=(std::nullptr_t) = delete;
 258 ```
 259
 260 Construction from `std::nullptr_t`  and assignment of `std::nullptr_t` are explicitly deleted.
 261
 262 ##### Modifiers
 263
 264 ```cpp
 265 not_null& operator++() = delete;
 266 not_null& operator--() = delete;
 267 not_null operator++(int) = delete;
 268 not_null operator--(int) = delete;
 269 not_null& operator+=(std::ptrdiff_t) = delete;
 270 not_null& operator-=(std::ptrdiff_t) = delete;
 271 ```
 272
 273 Explicitly deleted operators. Pointers point to single objects ([I.13: Do not pass an array as a single pointer](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-array)), so don't allow these operators.
 274
 275 ##### Observers
 276
 277 ```cpp
 278 constexpr details::value_or_reference_return_t<T> get() const;
 279 constexpr operator T() const { return get(); }
 280 ```
 281
 282 Get the underlying pointer.
 283
 284 ```cpp
 285 constexpr decltype(auto) operator->() const { return get(); }
 286 constexpr decltype(auto) operator*() const { return *get(); }
 287 ```
 288
 289 Dereference the underlying pointer.
 290
 291 ```cpp
 292 void operator[](std::ptrdiff_t) const = delete;
 293 ```
 294
 295 Array index operator is explicitly deleted. Pointers point to single objects ([I.13: Do not pass an array as a single pointer](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-array)), so don't allow treating them as an array.
 296
 297 #### Non-member functions
 298
 299 ```cpp
 300 template <class T>
 301 auto make_not_null(T&& t) noexcept;
 302 ```
 303
 304 Creates a `gsl::not_null` object, deducing the target type from the type of the argument.
 305
 306 ```cpp
 307 template <class T, class U>
 308 auto operator==(const not_null<T>& lhs,
 309                 const not_null<U>& rhs) noexcept(noexcept(lhs.get() == rhs.get()))
 310     -> decltype(lhs.get() == rhs.get());
 311 template <class T, class U>
 312 auto operator!=(const not_null<T>& lhs,
 313                 const not_null<U>& rhs) noexcept(noexcept(lhs.get() != rhs.get()))
 314     -> decltype(lhs.get() != rhs.get());
 315 template <class T, class U>
 316 auto operator<(const not_null<T>& lhs,
 317                const not_null<U>& rhs) noexcept(noexcept(lhs.get() < rhs.get()))
 318     -> decltype(lhs.get() < rhs.get());
 319 template <class T, class U>
 320 auto operator<=(const not_null<T>& lhs,
 321                 const not_null<U>& rhs) noexcept(noexcept(lhs.get() <= rhs.get()))
 322     -> decltype(lhs.get() <= rhs.get());
 323 template <class T, class U>
 324 auto operator>(const not_null<T>& lhs,
 325                const not_null<U>& rhs) noexcept(noexcept(lhs.get() > rhs.get()))
 326     -> decltype(lhs.get() > rhs.get());
 327 template <class T, class U>
 328 auto operator>=(const not_null<T>& lhs,
 329                 const not_null<U>& rhs) noexcept(noexcept(lhs.get() >= rhs.get()))
 330     -> decltype(lhs.get() >= rhs.get());
 331 ```
 332
 333 Comparison of pointers that are convertible to each other.
 334
 335 ##### Input/Output
 336
 337 ```cpp
 338 template <class T>
 339 std::ostream& operator<<(std::ostream& os, const not_null<T>& val);
 340 ```
 341
 342 Performs stream output on a `not_null` pointer, invoking `os << val.get()`. This function is only available when `GSL_NO_IOSTREAMS` is not defined.
 343
 344 ##### Modifiers
 345
 346 ```cpp
 347 template <class T, class U>
 348 std::ptrdiff_t operator-(const not_null<T>&, const not_null<U>&) = delete;
 349 template <class T>
 350 not_null<T> operator-(const not_null<T>&, std::ptrdiff_t) = delete;
 351 template <class T>
 352 not_null<T> operator+(const not_null<T>&, std::ptrdiff_t) = delete;
 353 template <class T>
 354 not_null<T> operator+(std::ptrdiff_t, const not_null<T>&) = delete;
 355 ```
 356
 357 Addition and subtraction are explicitly deleted. Pointers point to single objects ([I.13: Do not pass an array as a single pointer](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-array)), so don't allow these operators.
 358
 359 ##### STL integration
 360
 361 ```cpp
 362 template <class T>
 363 struct std::hash<gsl::not_null<T>> { ... };
 364 ```
 365
 366 Specialization of `std::hash` for `gsl::not_null`.
 367
 368 ### <a name="H-pointers-strict_not_null" />`gsl::strict_not_null`
 369
 370 `strict_not_null` is the same as [`not_null`](#user-content-H-pointers-not_null) except that the constructors are `explicit`.
 371
 372 The free function that deduces the target type from the type of the argument and creates a `gsl::strict_not_null` object is `gsl::make_strict_not_null`.
 373
 374 ## <a name="H-span" />`<span>`
 375
 376 This header file exports the class `gsl::span`, a bounds-checked implementation of `std::span`.
 377
 378 - [`gsl::span`](#user-content-H-span-span)
 379
 380 ### <a name="H-span-span" />`gsl::span`
 381
 382 ```cpp
 383 template <class ElementType, std::size_t Extent>
 384 class span;
 385 ```
 386
 387 `gsl::span` is a view over memory. It does not own the memory and is only a way to access contiguous sequences of objects.
 388 The extent can be either a fixed size or [`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent).
 389
 390 The `gsl::span` is based on the standardized version of `std::span` which was added to C++20. Originally, the plan was to
 391 deprecate `gsl::span` when `std::span` finished standardization, however that plan changed when the runtime bounds checking
 392 was removed from `std::span`'s design.
 393
 394 The only difference between `gsl::span` and `std::span` is that `gsl::span` strictly enforces runtime bounds checking.
 395 Any violations of the bounds check results in termination of the program.
 396 Like `gsl::span`, `gsl::span`'s iterators also differ from `std::span`'s iterator in that all access operations are bounds checked.
 397
 398 #### Which version of span should I use?
 399
 400 ##### Use `gsl::span` if
 401
 402 - you want to guarantee bounds safety in your project.
 403   - All data accessing operations use bounds checking to ensure you are only accessing valid memory.
 404 - your project uses C++14 or C++17.
 405   - `std::span` is not available as it was not introduced into the STL until C++20.
 406
 407 ##### Use `std::span` if
 408
 409 - your project is C++20 and you need the performance offered by `std::span`.
 410
 411 #### Types
 412
 413 ```cpp
 414 using element_type = ElementType;
 415 using value_type = std::remove_cv_t<ElementType>;
 416 using size_type = std::size_t;
 417 using pointer = element_type*;
 418 using const_pointer = const element_type*;
 419 using reference = element_type&;
 420 using const_reference = const element_type&;
 421 using difference_type = std::ptrdiff_t;
 422
 423 using iterator = details::span_iterator<ElementType>;
 424 using reverse_iterator = std::reverse_iterator<iterator>;
 425 ```
 426
 427 #### Member functions
 428
 429 ```cpp
 430 constexpr span() noexcept;
 431 ```
 432
 433 Constructs an empty `span`. This constructor is only available if `Extent` is 0 or [`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent).
 434 `span::data()` will return `nullptr`.
 435
 436 ```cpp
 437 constexpr explicit(Extent != gsl::dynamic_extent) span(pointer ptr, size_type count) noexcept;
 438 ```
 439
 440 Constructs a `span` from a pointer and a size. If `Extent` is not [`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent),
 441 then the constructor [`Expects`](#user-content-H-assert-expects) that `count == Extent`.
 442
 443 ```cpp
 444 constexpr explicit(Extent != gsl::dynamic_extent) span(pointer firstElem, pointer lastElem) noexcept;
 445 ```
 446
 447 Constructs a `span` from a pointer to the begin and the end of the data. If `Extent` is not [`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent),
 448 then the constructor [`Expects`](#user-content-H-assert-expects) that `lastElem - firstElem == Extent`.
 449
 450 ```cpp
 451 template <std::size_t N>
 452 constexpr span(element_type (&arr)[N]) noexcept;
 453 ```
 454
 455 Constructs a `span` from a C style array. This overload is available if `Extent ==`[`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent)
 456 or `N == Extent`.
 457
 458 ```cpp
 459 template <class T, std::size_t N>
 460 constexpr span(std::array<T, N>& arr) noexcept;
 461
 462 template <class T, std::size_t N>
 463 constexpr span(const std::array<T, N>& arr) noexcept;
 464 ```
 465
 466 Constructs a `span` from a `std::array`. These overloads are available if `Extent ==`[`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent)
 467 or `N == Extent`, and if the array can be interpreted as a `ElementType` array.
 468
 469 ```cpp
 470 template <class Container>
 471 constexpr explicit(Extent != gsl::dynamic_extent) span(Container& cont) noexcept;
 472
 473 template <class Container>
 474 constexpr explicit(Extent != gsl::dynamic_extent) span(const Container& cont) noexcept;
 475 ```
 476
 477 Constructs a `span` from a container. These overloads are available if `Extent ==`[`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent)
 478 or `N == Extent`, and if the container can be interpreted as a contiguous `ElementType` array.
 479
 480 ```cpp
 481 constexpr span(const span& other) noexcept = default;
 482 ```
 483
 484 Copy constructor.
 485
 486 ```cpp
 487 template <class OtherElementType, std::size_t OtherExtent>
 488 explicit(Extent != gsl::dynamic_extent && OtherExtent == dynamic_extent)
 489 constexpr span(const span<OtherElementType, OtherExtent>& other) noexcept;
 490 ```
 491
 492 Constructs a `span` from another `span`. This constructor is available if `OtherExtent == Extent || Extent ==`[`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent)` || OtherExtent ==`[`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent)
 493 and if `ElementType` and `OtherElementType` are compatible.
 494
 495 If `Extent !=`[`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent) and `OtherExtent ==`[`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent),
 496 then the constructor [`Expects`](#user-content-H-assert-expects) that `other.size() == Extent`.
 497
 498 ```cpp
 499 constexpr span& operator=(const span& other) noexcept = default;
 500 ```
 501
 502 Copy assignment
 503
 504 ```cpp
 505 template <std::size_t Count>
 506 constexpr span<element_type, Count> first() const noexcept;
 507
 508 constexpr span<element_type, dynamic_extent> first(size_type count) const noexcept;
 509
 510 template <std::size_t Count>
 511 constexpr span<element_type, Count> last() const noexcept;
 512
 513 constexpr span<element_type, dynamic_extent> last(size_type count) const noexcept;
 514 ```
 515
 516 Return a subspan of the first/last `Count` elements. [`Expects`](#user-content-H-assert-expects) that `Count` does not exceed the `span`'s size.
 517
 518 ```cpp
 519 template <std::size_t offset, std::size_t count = dynamic_extent>
 520 constexpr auto subspan() const noexcept;
 521
 522 constexpr span<element_type, dynamic_extent>
 523 subspan(size_type offset, size_type count = dynamic_extent) const noexcept;
 524 ```
 525
 526 Return a subspan starting at `offset` and having size `count`. [`Expects`](#user-content-H-assert-expects) that `offset` does not exceed the `span`'s size,
 527 and that `offset == `[`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent) or `offset + count` does not exceed the `span`'s size.
 528 If `count` is `gsl::dynamic_extent`, the number of elements in the subspan is `size() - offset`.
 529
 530 ```cpp
 531 constexpr size_type size() const noexcept;
 532
 533 constexpr size_type size_bytes() const noexcept;
 534 ```
 535
 536 Returns the size respective the size in bytes of the `span`.
 537
 538 ```cpp
 539 constexpr bool empty() const noexcept;
 540 ```
 541
 542 Is the `span` empty?
 543
 544 ```cpp
 545 constexpr reference operator[](size_type idx) const noexcept;
 546 ```
 547
 548 Returns a reference to the element at the given index. [`Expects`](#user-content-H-assert-expects) that `idx` is less than the `span`'s size.
 549
 550 ```cpp
 551 constexpr reference front() const noexcept;
 552 constexpr reference back() const noexcept;
 553 ```
 554
 555 Returns a reference to the first/last element in the `span`. [`Expects`](#user-content-H-assert-expects) that the `span` is not empty.
 556
 557 ```cpp
 558 constexpr pointer data() const noexcept;
 559 ```
 560
 561 Returns a pointer to the beginning of the contained data.
 562
 563 ```cpp
 564 constexpr iterator begin() const noexcept;
 565 constexpr iterator end() const noexcept;
 566 constexpr reverse_iterator rbegin() const noexcept;
 567 constexpr reverse_iterator rend() const noexcept;
 568 ```
 569
 570 Returns an iterator to the first/last normal/reverse iterator.
 571
 572 ```cpp
 573 template <class Type, std::size_t Extent>
 574 span(Type (&)[Extent]) -> span<Type, Extent>;
 575
 576 template <class Type, std::size_t Size>
 577 span(std::array<Type, Size>&) -> span<Type, Size>;
 578
 579 template <class Type, std::size_t Size>
 580 span(const std::array<Type, Size>&) -> span<const Type, Size>;
 581
 582 template <class Container,
 583           class Element = std::remove_pointer_t<decltype(std::declval<Container&>().data())>>
 584 span(Container&) -> span<Element>;
 585
 586 template <class Container,
 587           class Element = std::remove_pointer_t<decltype(std::declval<const Container&>().data())>>
 588 span(const Container&) -> span<Element>;
 589 ```
 590
 591 Deduction guides.
 592
 593 ```cpp
 594 template <class ElementType, std::size_t Extent>
 595 span<const byte, details::calculate_byte_size<ElementType, Extent>::value>
 596 as_bytes(span<ElementType, Extent> s) noexcept;
 597
 598 template <class ElementType, std::size_t Extent>
 599 span<byte, details::calculate_byte_size<ElementType, Extent>::value>
 600 as_writable_bytes(span<ElementType, Extent> s) noexcept;
 601 ```
 602
 603 Converts a `span` into a `span` of `byte`s.
 604
 605 `as_writable_bytes` will only be available for non-const `ElementType`s.
 606
 607 ## <a name="H-span_ext" />`<span_ext>`
 608
 609 This file is a companion for and included by [`<gsl/span>`](#user-content-H-span), and should not be used on its own. It contains useful features that aren't part of the `std::span` API as found inside the STL `<span>` header (with the exception of [`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent), which is included here due to implementation constraints).
 610
 611 - [`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent)
 612 - [`gsl::span`](#user-content-H-span_ext-span)
 613 - [`gsl::span` comparison operators](#user-content-H-span_ext-span_comparison_operators)
 614 - [`gsl::make_span`](#user-content-H-span_ext-make_span)
 615 - [`gsl::at`](#user-content-H-span_ext-at)
 616 - [`gsl::ssize`](#user-content-H-span_ext-ssize)
 617 - [`gsl::span` iterator functions](#user-content-H-span_ext-span_iterator_functions)
 618
 619 ### <a name="H-span_ext-dynamic_extent" />`gsl::dynamic_extent`
 620
 621 Defines the extent value to be used by all `gsl::span` with dynamic extent.
 622
 623 Note: `std::dynamic_extent` is exposed by the STL `<span>` header and so ideally `gsl::dynamic_extent` would be under [`<gsl/span>`](#user-content-H-span), but to avoid cyclic dependency issues it is under `<span_ext>` instead.
 624
 625 ### <a name="H-span_ext-span" />`gsl::span`
 626
 627 ```cpp
 628 template <class ElementType, std::size_t Extent = dynamic_extent>
 629 class span;
 630 ```
 631
 632 Forward declaration of `gsl::span`.
 633
 634 ### <a name="H-span_ext-span_comparison_operators" />`gsl::span` comparison operators
 635
 636 ```cpp
 637 template <class ElementType, std::size_t FirstExtent, std::size_t SecondExtent>
 638 constexpr bool operator==(span<ElementType, FirstExtent> l, span<ElementType, SecondExtent> r);
 639 template <class ElementType, std::size_t FirstExtent, std::size_t SecondExtent>
 640 constexpr bool operator!=(span<ElementType, FirstExtent> l, span<ElementType, SecondExtent> r);
 641 template <class ElementType, std::size_t Extent>
 642 constexpr bool operator<(span<ElementType, Extent> l, span<ElementType, Extent> r);
 643 template <class ElementType, std::size_t Extent>
 644 constexpr bool operator<=(span<ElementType, Extent> l, span<ElementType, Extent> r);
 645 template <class ElementType, std::size_t Extent>
 646 constexpr bool operator>(span<ElementType, Extent> l, span<ElementType, Extent> r);
 647 template <class ElementType, std::size_t Extent>
 648 constexpr bool operator>=(span<ElementType, Extent> l, span<ElementType, Extent> r);
 649 ```
 650
 651 The comparison operators for two `span`s lexicographically compare the elements in the `span`s.
 652
 653 ### <a name="H-span_ext-make_span" />`gsl::make_span`
 654
 655 ```cpp
 656 template <class ElementType>
 657 constexpr span<ElementType> make_span(ElementType* ptr, typename span<ElementType>::size_type count);
 658 template <class ElementType>
 659 constexpr span<ElementType> make_span(ElementType* firstElem, ElementType* lastElem);
 660 template <class ElementType, std::size_t N>
 661 constexpr span<ElementType, N> make_span(ElementType (&arr)[N]) noexcept;
 662 template <class Container>
 663 constexpr span<typename Container::value_type> make_span(Container& cont);
 664 template <class Container>
 665 constexpr span<const typename Container::value_type> make_span(const Container& cont);
 666 template <class Ptr>
 667 constexpr span<typename Ptr::element_type> make_span(Ptr& cont, std::size_t count);
 668 template <class Ptr>
 669 constexpr span<typename Ptr::element_type> make_span(Ptr& cont);
 670 ```
 671
 672 Utility function for creating a `span` with [`gsl::dynamic_extent`](#user-content-H-span_ext-dynamic_extent) from
 673 - pointer and length,
 674 - pointer to start and pointer to end,
 675 - a C style array, or
 676 - a container.
 677
 678 ### <a name="H-span_ext-at" />`gsl::at`
 679
 680 ```cpp
 681 template <class ElementType, std::size_t Extent>
 682 constexpr ElementType& at(span<ElementType, Extent> s, index i);
 683 ```
 684
 685 The function `gsl::at` offers a safe way to access data with index bounds checking.
 686
 687 This is the specialization of [`gsl::at`](#user-content-H-util-at) for [`span`](#user-content-H-span-span). It returns a reference to the `i`th element and
 688 [`Expects`](#user-content-H-assert-expects) that the provided index is within the bounds of the `span`.
 689
 690 Note: `gsl::at` supports indexes up to `PTRDIFF_MAX`.
 691
 692 ### <a name="H-span_ext-ssize" />`gsl::ssize`
 693
 694 ```cpp
 695 template <class ElementType, std::size_t Extent>
 696 constexpr std::ptrdiff_t ssize(const span<ElementType, Extent>& s) noexcept;
 697 ```
 698
 699 Return the size of a [`span`](#user-content-H-span-span) as a `ptrdiff_t`.
 700
 701 ### <a name="H-span_ext-span_iterator_functions" />`gsl::span` iterator functions
 702
 703 ```cpp
 704 template <class ElementType, std::size_t Extent>
 705 constexpr typename span<ElementType, Extent>::iterator
 706 begin(const span<ElementType, Extent>& s) noexcept;
 707
 708 template <class ElementType, std::size_t Extent = dynamic_extent>
 709 constexpr typename span<ElementType, Extent>::iterator
 710 end(const span<ElementType, Extent>& s) noexcept;
 711
 712 template <class ElementType, std::size_t Extent>
 713 constexpr typename span<ElementType, Extent>::reverse_iterator
 714 rbegin(const span<ElementType, Extent>& s) noexcept;
 715
 716 template <class ElementType, std::size_t Extent>
 717 constexpr typename span<ElementType, Extent>::reverse_iterator
 718 rend(const span<ElementType, Extent>& s) noexcept;
 719
 720 template <class ElementType, std::size_t Extent>
 721 constexpr typename span<ElementType, Extent>::iterator
 722 cbegin(const span<ElementType, Extent>& s) noexcept;
 723
 724 template <class ElementType, std::size_t Extent = dynamic_extent>
 725 constexpr typename span<ElementType, Extent>::iterator
 726 cend(const span<ElementType, Extent>& s) noexcept;
 727
 728 template <class ElementType, std::size_t Extent>
 729 constexpr typename span<ElementType, Extent>::reverse_iterator
 730 crbegin(const span<ElementType, Extent>& s) noexcept;
 731
 732 template <class ElementType, std::size_t Extent>
 733 constexpr typename span<ElementType, Extent>::reverse_iterator
 734 crend(const span<ElementType, Extent>& s) noexcept;
 735 ```
 736
 737 Free functions for getting a non-const/const begin/end normal/reverse iterator for a [`span`](#user-content-H-span-span).
 738
 739 ## <a name="H-zstring" />`<zstring>`
 740
 741 This header exports a family of `*zstring` types.
 742
 743 A `gsl::XXzstring<T>` is a typedef to `T`. It adds no checks whatsoever, it is just for having a syntax to describe
 744 that a pointer points to a zero terminated C style string. This helps static code analysis, and it helps human readers.
 745
 746 `basic_zstring` is a pointer to a C-string (zero-terminated array) with a templated char type. Used to implement the rest of the `*zstring` family.
 747 `zstring` is a zero terminated `char` string.
 748 `czstring` is a const zero terminated `char` string.
 749 `wzstring` is a zero terminated `wchar_t` string.
 750 `cwzstring` is a const zero terminated `wchar_t` string.
 751 `u16zstring` is a zero terminated `char16_t` string.
 752 `cu16zstring` is a const zero terminated `char16_t` string.
 753 `u32zstring` is a zero terminated `char32_t` string.
 754 `cu32zstring` is a const zero terminated `char32_t` string.
 755
 756 See [GSL.view](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-views) and [SL.str.3: Use zstring or czstring to refer to a C-style, zero-terminated, sequence of characters](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rstr-zstring).
 757
 758 ## <a name="H-util" />`<util>`
 759
 760 This header contains utility functions and classes. This header works without exceptions being available. The parts that require
 761 exceptions being available are in their own header file [narrow](#user-content-H-narrow).
 762
 763 See [GSL.util: Utilities](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-utilities)
 764
 765 - [`gsl::narrow_cast`](#user-content-H-util-narrow_cast)
 766 - [`gsl::final_action`](#user-content-H-util-final_action)
 767 - [`gsl::at`](#user-content-H-util-at)
 768
 769 ### <a name="H-util-index" />`gsl::index`
 770
 771 An alias to `std::ptrdiff_t`. It serves as the index type for all container indexes/subscripts/sizes.
 772
 773 ### <a name="H-util-narrow_cast" />`gsl::narrow_cast`
 774
 775 `gsl::narrow_cast<T>(x)` is a named cast that is identical to a `static_cast<T>(x)`. It exists to make clear to static code analysis tools and to human readers that a lossy conversion is acceptable.
 776
 777 Note: compare the throwing version [`gsl::narrow`](#user-content-H-narrow-narrow) in header [narrow](#user-content-H-narrow).
 778
 779 See [ES.46: Avoid lossy (narrowing, truncating) arithmetic conversions](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-narrowing) and [ES.49: If you must use a cast, use a named cast](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts-named)
 780
 781 ### <a name="H-util-final_action" />`gsl::final_action`
 782
 783 ```cpp
 784 template <class F>
 785 class final_action { ... };
 786 ```
 787
 788 `final_action` allows you to ensure something gets run at the end of a scope.
 789
 790 See [E.19: Use a final_action object to express cleanup if no suitable resource handle is available](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Re-finally)
 791
 792 #### Member functions
 793
 794 ```cpp
 795 explicit final_action(const F& ff) noexcept;
 796 explicit final_action(F&& ff) noexcept;
 797 ```
 798
 799 Construct an object with the action to invoke in the destructor.
 800
 801 ```cpp
 802 ~final_action() noexcept;
 803 ```
 804
 805 The destructor will call the action that was passed in the constructor.
 806
 807 ```cpp
 808 final_action(final_action&& other) noexcept;
 809 final_action(const final_action&)   = delete;
 810 void operator=(const final_action&) = delete;
 811 void operator=(final_action&&)      = delete;
 812 ```
 813
 814 Move construction is allowed. Copy construction is deleted. Copy and move assignment are also explicitly deleted.
 815
 816 #### <a name="H-util-finally" />Non-member functions
 817 ```cpp
 818 template <class F>
 819 auto finally(F&& f) noexcept;
 820 ```
 821
 822 Creates a `gsl::final_action` object, deducing the template argument type from the type of the argument.
 823
 824 ### <a name="H-util-at" />`gsl::at`
 825
 826 The function `gsl::at` offers a safe way to access data with index bounds checking.
 827
 828 Note: `gsl::at` supports indexes up to `PTRDIFF_MAX`.
 829
 830 See [ES.42: Keep use of pointers simple and straightforward](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-ptr)
 831
 832 ```cpp
 833 template <class T, std::size_t N>
 834 constexpr T& at(T (&arr)[N], const index i);
 835 ```
 836
 837 This overload returns a reference to the `i`s element of a C style array `arr`. It [`Expects`](#user-content-H-assert-expects) that the provided index is within the bounds of the array.
 838
 839 ```cpp
 840 template <class Cont>
 841 constexpr auto at(Cont& cont, const index i) -> decltype(cont[cont.size()]);
 842 ```
 843
 844 This overload returns a reference to the `i`s element of the container `cont`. It [`Expects`](#user-content-H-assert-expects) that the provided index is within the bounds of the array.
 845
 846 ```cpp
 847 template <class T>
 848 constexpr T at(const std::initializer_list<T> cont, const index i);
 849 ```
 850
 851 This overload returns a reference to the `i`s element of the initializer list `cont`. It [`Expects`](#user-content-H-assert-expects) that the provided index is within the bounds of the array.
 852
 853 ```cpp
 854 template <class T, std::size_t extent = std::dynamic_extent>
 855 constexpr auto at(std::span<T, extent> sp, const index i) -> decltype(sp[sp.size()]);
 856 ```
 857
 858 This overload returns a reference to the `i`s element of the `std::span` `sp`. It [`Expects`](#user-content-H-assert-expects) that the provided index is within the bounds of the array.
 859
 860 For [`gsl::at`](#user-content-H-span_ext-at) for [`gsl::span`](#user-content-H-span-span) see header [`span_ext`](#user-content-H-span_ext).