Skip to content

Commit

Permalink
Deprecate <gsl/string_span> and replace with <gsl/zstring> (#1125)
Browse files Browse the repository at this point in the history
With `string_span` having been deprecated (#931, #945) and removed (#1074), the header `<gsl/string_span>` now only contains the definitions for the `zstring` family. Update the name accordingly from `<gsl/string_span>` to `<gsl/zstring>`. The old header is now deprecated and should no longer be used and will be removed in some future release.
  • Loading branch information
dmitrykobets-msft committed Jun 28, 2023
1 parent 65a5995 commit 3549e31
Show file tree
Hide file tree
Showing 5 changed files with 74 additions and 70 deletions.
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,15 @@ Feature | Suppo
[not_null](docs/headers.md#user-content-H-pointers-not_null) | &#x2611; | Restricts a pointer / smart pointer to hold non-null values
[span](docs/headers.md#user-content-H-span-span) | &#x2611; | A view over a contiguous sequence of memory. Based on the standardized version of `std::span`, however `gsl::span` enforces bounds checking.
span_p | &#x2610; | 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) | &#x2611; | A pointer to a C-string (zero-terminated array) with a templated char type
[zstring](docs/headers.md#user-content-H-string_span) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of char
[czstring](docs/headers.md#user-content-H-string_span) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of const char
[wzstring](docs/headers.md#user-content-H-string_span) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of wchar_t
[cwzstring](docs/headers.md#user-content-H-string_span) | &#x2611; | 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) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of char16_t
[cu16zstring](docs/headers.md#user-content-H-string_span) | &#x2611; | 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) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of char32_t
[cu32zstring](docs/headers.md#user-content-H-string_span) | &#x2611; | 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) | &#x2611; | A pointer to a C-string (zero-terminated array) with a templated char type
[zstring](docs/headers.md#user-content-H-zstring) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of char
[czstring](docs/headers.md#user-content-H-zstring) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of const char
[wzstring](docs/headers.md#user-content-H-zstring) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of wchar_t
[cwzstring](docs/headers.md#user-content-H-zstring) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of const wchar_t
[u16zstring](docs/headers.md#user-content-H-zstring) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of char16_t
[cu16zstring](docs/headers.md#user-content-H-zstring) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of const char16_t
[u32zstring](docs/headers.md#user-content-H-zstring) | &#x2611; | An alias to `basic_zstring` with dynamic extent and a char type of char32_t
[cu32zstring](docs/headers.md#user-content-H-zstring) | &#x2611; | 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) | &#x2611; | An alias to `std::unique_ptr`
[shared_ptr](docs/headers.md#user-content-H-pointers-shared_ptr) | &#x2611; | An alias to `std::shared_ptr`
Expand Down
4 changes: 2 additions & 2 deletions docs/headers.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ See [GSL: Guidelines support library](https://isocpp.github.io/CppCoreGuidelines
- [`<pointers>`](#user-content-H-pointers)
- [`<span>`](#user-content-H-span)
- [`<span_ext>`](#user-content-H-span_ext)
- [`<string_span>`](#user-content-H-string_span)
- [`<zstring>`](#user-content-H-zstring)
- [`<util>`](#user-content-H-util)

## <a name="H-algorithms" />`<algorithms>`
Expand Down Expand Up @@ -729,7 +729,7 @@ crend(const span<ElementType, Extent>& s) noexcept;

Free functions for getting a non-const/const begin/end normal/reverse iterator for a [`span`](#user-content-H-span-span).

## <a name="H-string_span" />`<string_span>`
## <a name="H-zstring" />`<zstring>`

This header exports a family of `*zstring` types.

Expand Down
2 changes: 1 addition & 1 deletion include/gsl/gsl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
62 changes: 4 additions & 58 deletions include/gsl/string_span
Original file line number Diff line number Diff line change
@@ -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 <cstddef> // 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 <typename CharT, std::size_t Extent = dynamic_extent>
using basic_zstring = CharT*;

using czstring = basic_zstring<const char, dynamic_extent>;

using cwzstring = basic_zstring<const wchar_t, dynamic_extent>;

using cu16zstring = basic_zstring<const char16_t, dynamic_extent>;

using cu32zstring = basic_zstring<const char32_t, dynamic_extent>;

using zstring = basic_zstring<char, dynamic_extent>;

using wzstring = basic_zstring<wchar_t, dynamic_extent>;

using u16zstring = basic_zstring<char16_t, dynamic_extent>;

using u32zstring = basic_zstring<char32_t, dynamic_extent>;

} // namespace gsl

#endif // GSL_STRING_SPAN_H
#pragma once
#pragma message( \
"This header will soon be removed. Use <gsl/zstring> instead of <gsl/string_span>")
#include "zstring"
58 changes: 58 additions & 0 deletions include/gsl/zstring
Original file line number Diff line number Diff line change
@@ -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 <cstddef> // 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 <typename CharT, std::size_t Extent = dynamic_extent>
using basic_zstring = CharT*;

using czstring = basic_zstring<const char, dynamic_extent>;

using cwzstring = basic_zstring<const wchar_t, dynamic_extent>;

using cu16zstring = basic_zstring<const char16_t, dynamic_extent>;

using cu32zstring = basic_zstring<const char32_t, dynamic_extent>;

using zstring = basic_zstring<char, dynamic_extent>;

using wzstring = basic_zstring<wchar_t, dynamic_extent>;

using u16zstring = basic_zstring<char16_t, dynamic_extent>;

using u32zstring = basic_zstring<char32_t, dynamic_extent>;

} // namespace gsl

#endif // GSL_ZSTRING_H

0 comments on commit 3549e31

Please sign in to comment.