Tag Archives: gsl

Guidelines Support Library Review: string_span<T>

In a previous post I have introduced the span<T> type from the Guidelines Support Library. This is a non-owning range of contiguous memory recommended to be used instead of pointers (and size counter) or standard containers (such as vector or array). span<T> can be used with strings, but the Guidelines Support Library provides a different span implementation for various types of strings. These string span types are available in the string_span.h header.

String span types

There are several string span types defined in the string_span.h header:

  • basic_string_span: the actual implementation for a string span on which several type aliases are available:
    • string_span: a string span of char
    • cstring_span: a string span of const char
    • wstring_span: a string span of wchar_t
    • cwstring_span: a string span of const wchar_t

  • basic_zstring_span: a null terminated string span used for converting null terminated spans to legacy strings; it has several type aliases available:
    • zstring_span: a null terminated string span of char
    • czstring_span: a null terminated string span of const char
    • wzstring_span: a null terminated string span of wchar_t
    • cwzstring_span: a null terminated string span of const wchar_t

These look like a lot of classes with similar names, but the names are self explanatory (terminology is c=const, w=wide, z=null-terminated):

  • string: a string of char
  • cstring: a string of const char
  • wstring: a string of wchar_t
  • cwstring: a string of const wchar_t
  • zstring: a (zero) null-terminated string of char
  • czstring: a null-terminated string of const char
  • wzstring: a null-terminated string of wchar_t
  • cwzstring: a null-terminated string of const wchar_t

Creating a string_span

A string_span can be created in many ways, including:

(Note that in all following examples the string span is the range { L'H',L'e',L'l',L'l',L'o',L' ',L'w',L'o',L'r',L'l',L'd' } of either char or wchar_t.)

  • from a literal string

  • from a pointer

  • from a standard string

  • from an array

  • from a vector

Converting to string

To convert a string span into a string you can use the to_string() function.

Size of a string_span

Unlike span<T>, a string_span<T> only have one dimension, so the rank() method does not make make sense and is not available. However, a string span has several methods for the size of the span:

  • size() and length(): return the number of elements of the span
  • size_bytes() and length_bytes(): return the number of bytes of the span

Subspans

It is possible to create subspans from a string_span. There are several functions that do that:

  • first(): returns the sub-span with the first N elements from the original string_span
  • last(): returns the sub-span with the last N elements from the original string_span
  • subspan(): returns the sub-span within the specified range (first and last positions) of the original string_span.

Comparisons

You can use the comparison operators (==, !=, <, <=, >, >=) with two string spans. Just like in the case of span<T>, equality is checked with std::equal (two ranges are equal if every element in the first range is equal to the element corresponding to the same position in the second range) and less/greater is checked with std::lexicographical_compare() (one range is less than another if the first mismatch element in the first range is less than the element on the same position in the second range).

Element access

It is possible to access the content of a string_span either with iterators or indexes.

Guidelines Support Library Review: span<T>

The Guidelines Support Library is a Microsoft implementation of some of the types and functions described in the C++ Core Guidelines maintained by the Standard C++ Foundation. Among the types provided by the GSL is span<T> formerly known as array_view<T>. This article is an introduction to this type.

span<T> is a non-owning range of contiguous memory recommended to be used instead of pointers (and size counter) or standard containers (such as std::vector or std::array).

Suppose you want to create a function that displays the content of a container. Such a function could look like this:

This will work with vectors, but not with arrays or lists. So then you need overloads in order to support other containers.

But what if you now what to display the content of an int[] or an int*?

The span<T> type is intended as a uniform interface over arrays, pointers and standard containers that can be used as a replacement of these types. It does not store a copy of the original data, only a pointer to data and counters.

The following helper functions are used in the samples below:

Creating a span

A span can be created in many ways, including:

  • from a single value (variable, not a literal)

  • from a pointer and number of elements

  • from a begin and end pointer

  • from a C-like array

  • from a dynamic array

  • from a standard container with contiguous memory layout such as array, vector or string

  • using the gsl::as_span() function:

Notice that it is not possible to create a span from an initializer_list because an initializer list is a temporary object and a span is a non-owning container, it does not make a copy of the data, and therefore it can end up containing dangling references to temporary data. For a detailed discussion on the topic see this issue.

Size of a span

A span can have zero, one or more dimensions, and each dimension can have a different size (number of elements). The number of dimensions is called rank and the number of elements in a dimension is called extent. You can retrieve the rank and extent using the functions with the same name.

Subspans

It is possible to create subspans from a span. There are several functions that do that:

  • first(): returns the sub-span with the first N elements from the original span
  • last(): returns the sub-span with the last N elements from the original span
  • subspan(): returns the sub-span within the specified range (first and last positions) of the original span.

Comparisons

You can use the comparison operators (==, !=, <, <=, >, >=) with two spans. Equality is checked with std::equal (two ranges are equal if every element in the first range is equal to the element corresponding to the same position in the second range) and less/greater is checked with std::lexicographical_compare() (one range is less than another if the first mismatch element in the first range is less than the element on the same position in the second range).

Element access

It is possible to access the content of a span either with iterators or indexes.

When it comes to index access you can either index like a regular array (s[0], s[1][2], etc.) or using a special type called index.