From 3549e31ba4001ce2283593301df58fab186899ee Mon Sep 17 00:00:00 2001 From: Dmitry Kobets <89153909+dmitrykobets-msft@users.noreply.github.com> Date: Wed, 28 Jun 2023 10:48:23 -0700 Subject: [PATCH] Deprecate `` and replace with `` (#1125) With `string_span` having been deprecated (https://github.com/microsoft/GSL/pull/931, https://github.com/microsoft/GSL/pull/945) and removed (https://github.com/microsoft/GSL/pull/1074), the header `` now only contains the definitions for the `zstring` family. Update the name accordingly from `` to ``. The old header is now deprecated and should no longer be used and will be removed in some future release. --- README.md | 18 ++++++------ docs/headers.md | 4 +-- include/gsl/gsl | 2 +- include/gsl/string_span | 62 +++-------------------------------------- include/gsl/zstring | 58 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 74 insertions(+), 70 deletions(-) create mode 100644 include/gsl/zstring diff --git a/README.md b/README.md index 725bf66..a6e78df 100644 --- a/README.md +++ b/README.md @@ -29,15 +29,15 @@ Feature | Suppo [not_null](docs/headers.md#user-content-H-pointers-not_null) | ☑ | Restricts a pointer / smart pointer to hold non-null values [span](docs/headers.md#user-content-H-span-span) | ☑ | A view over a contiguous sequence of memory. Based on the standardized version of `std::span`, however `gsl::span` enforces bounds checking. span_p | ☐ | Spans a range starting from a pointer to the first place for which the predicate is true -[basic_zstring](docs/headers.md#user-content-H-string_span) | ☑ | A pointer to a C-string (zero-terminated array) with a templated char type -[zstring](docs/headers.md#user-content-H-string_span) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of char -[czstring](docs/headers.md#user-content-H-string_span) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const char -[wzstring](docs/headers.md#user-content-H-string_span) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of wchar_t -[cwzstring](docs/headers.md#user-content-H-string_span) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const wchar_t -[u16zstring](docs/headers.md#user-content-H-string_span) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of char16_t -[cu16zstring](docs/headers.md#user-content-H-string_span) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const char16_t -[u32zstring](docs/headers.md#user-content-H-string_span) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of char32_t -[cu32zstring](docs/headers.md#user-content-H-string_span) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const char32_t +[basic_zstring](docs/headers.md#user-content-H-zstring) | ☑ | A pointer to a C-string (zero-terminated array) with a templated char type +[zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of char +[czstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const char +[wzstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of wchar_t +[cwzstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const wchar_t +[u16zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of char16_t +[cu16zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const char16_t +[u32zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of char32_t +[cu32zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const char32_t [**2. Owners**][cg-owners] | | [unique_ptr](docs/headers.md#user-content-H-pointers-unique_ptr) | ☑ | An alias to `std::unique_ptr` [shared_ptr](docs/headers.md#user-content-H-pointers-shared_ptr) | ☑ | An alias to `std::shared_ptr` diff --git a/docs/headers.md b/docs/headers.md index e870eaf..37d7819 100644 --- a/docs/headers.md +++ b/docs/headers.md @@ -14,7 +14,7 @@ See [GSL: Guidelines support library](https://isocpp.github.io/CppCoreGuidelines - [``](#user-content-H-pointers) - [``](#user-content-H-span) - [``](#user-content-H-span_ext) -- [``](#user-content-H-string_span) +- [``](#user-content-H-zstring) - [``](#user-content-H-util) ## `` @@ -729,7 +729,7 @@ crend(const span& s) noexcept; Free functions for getting a non-const/const begin/end normal/reverse iterator for a [`span`](#user-content-H-span-span). -## `` +## `` This header exports a family of `*zstring` types. diff --git a/include/gsl/gsl b/include/gsl/gsl index 3d9e288..9e19140 100644 --- a/include/gsl/gsl +++ b/include/gsl/gsl @@ -22,7 +22,7 @@ #include "byte" // byte #include "pointers" // owner, not_null #include "span" // span -#include "string_span" // zstring, string_span, zstring_builder... +#include "zstring" // zstring #include "util" // finally()/narrow_cast()... #ifdef __cpp_exceptions diff --git a/include/gsl/string_span b/include/gsl/string_span index 6daf546..65790ab 100644 --- a/include/gsl/string_span +++ b/include/gsl/string_span @@ -1,58 +1,4 @@ -/////////////////////////////////////////////////////////////////////////////// -// -// Copyright (c) 2015 Microsoft Corporation. All rights reserved. -// -// This code is licensed under the MIT License (MIT). -// -// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -// THE SOFTWARE. -// -/////////////////////////////////////////////////////////////////////////////// - -#ifndef GSL_STRING_SPAN_H -#define GSL_STRING_SPAN_H - -#include "span_ext" // for dynamic_extent - -#include // for size_t, nullptr_t - -namespace gsl -{ -// -// czstring and wzstring -// -// These are "tag" typedefs for C-style strings (i.e. null-terminated character arrays) -// that allow static analysis to help find bugs. -// -// There are no additional features/semantics that we can find a way to add inside the -// type system for these types that will not either incur significant runtime costs or -// (sometimes needlessly) break existing programs when introduced. -// - -template -using basic_zstring = CharT*; - -using czstring = basic_zstring; - -using cwzstring = basic_zstring; - -using cu16zstring = basic_zstring; - -using cu32zstring = basic_zstring; - -using zstring = basic_zstring; - -using wzstring = basic_zstring; - -using u16zstring = basic_zstring; - -using u32zstring = basic_zstring; - -} // namespace gsl - -#endif // GSL_STRING_SPAN_H +#pragma once +#pragma message( \ + "This header will soon be removed. Use instead of ") +#include "zstring" diff --git a/include/gsl/zstring b/include/gsl/zstring new file mode 100644 index 0000000..2cc13d8 --- /dev/null +++ b/include/gsl/zstring @@ -0,0 +1,58 @@ +/////////////////////////////////////////////////////////////////////////////// +// +// Copyright (c) 2015 Microsoft Corporation. All rights reserved. +// +// This code is licensed under the MIT License (MIT). +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +// THE SOFTWARE. +// +/////////////////////////////////////////////////////////////////////////////// + +#ifndef GSL_ZSTRING_H +#define GSL_ZSTRING_H + +#include "span_ext" // for dynamic_extent + +#include // for size_t, nullptr_t + +namespace gsl +{ +// +// czstring and wzstring +// +// These are "tag" typedefs for C-style strings (i.e. null-terminated character arrays) +// that allow static analysis to help find bugs. +// +// There are no additional features/semantics that we can find a way to add inside the +// type system for these types that will not either incur significant runtime costs or +// (sometimes needlessly) break existing programs when introduced. +// + +template +using basic_zstring = CharT*; + +using czstring = basic_zstring; + +using cwzstring = basic_zstring; + +using cu16zstring = basic_zstring; + +using cu32zstring = basic_zstring; + +using zstring = basic_zstring; + +using wzstring = basic_zstring; + +using u16zstring = basic_zstring; + +using u32zstring = basic_zstring; + +} // namespace gsl + +#endif // GSL_ZSTRING_H