Tag Archives: standard

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

template<std::ptrdiff_t Extent = dynamic_range>
using string_span = basic_string_span<char, Extent>;

template<std::ptrdiff_t Extent = dynamic_range>
using cstring_span = basic_string_span<const char, Extent>;

template<std::ptrdiff_t Extent = dynamic_range>
using wstring_span = basic_string_span<wchar_t, Extent>;

template<std::ptrdiff_t Extent = dynamic_range>
using cwstring_span = basic_string_span<const wchar_t, Extent>;

template<std::ptrdiff_t Extent = dynamic_range>

using string_span = basic_string_span<char, Extent>;

template<std::ptrdiff_t Extent = dynamic_range>

using cstring_span = basic_string_span<const char, Extent>;

template<std::ptrdiff_t Extent = dynamic_range>

using wstring_span = basic_string_span<wchar_t, Extent>;

template<std::ptrdiff_t Extent = dynamic_range>

using cwstring_span = basic_string_span<const wchar_t, Extent>;

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

template <std::ptrdiff_t Max = dynamic_range>
using zstring_span = basic_zstring_span<char, Max>;

template <std::ptrdiff_t Max = dynamic_range>
using wzstring_span = basic_zstring_span<wchar_t, Max>;

template <std::ptrdiff_t Max = dynamic_range>
using czstring_span = basic_zstring_span<const char, Max>;

template <std::ptrdiff_t Max = dynamic_range>
using cwzstring_span = basic_zstring_span<const wchar_t, Max>;

template <std::ptrdiff_t Max = dynamic_range>

using zstring_span = basic_zstring_span<char, Max>;

template <std::ptrdiff_t Max = dynamic_range>

using wzstring_span = basic_zstring_span<wchar_t, Max>;

template <std::ptrdiff_t Max = dynamic_range>

using czstring_span = basic_zstring_span<const char, Max>;

template <std::ptrdiff_t Max = dynamic_range>

using cwzstring_span = basic_zstring_span<const wchar_t, Max>;

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

C++

gsl::cstring_span<> s1 = gsl::ensure_z("Hello world"); gsl::cwstring_span<> s2 = gsl::ensure_z(L"Hello world");

1
2
3

gsl::cstring_span<> s1 = gsl::ensure_z("Hello world");

gsl::cwstring_span<> s2 = gsl::ensure_z(L"Hello world");
from a pointer

C++

const char* t1 = "Hello world"; gsl::cstring_span<> s1 = gsl::ensure_z(t1); const wchar_t* t2 = L"Hello world"; gsl::cwstring_span<> s2 = gsl::ensure_z(t2);

1
2
3
4
5

const char* t1 = "Hello world";
gsl::cstring_span<> s1 = gsl::ensure_z(t1);

const wchar_t* t2 = L"Hello world";
gsl::cwstring_span<> s2 = gsl::ensure_z(t2);
from a standard string

C++

std::string str1 = "Hello world"; gsl::cstring_span<> s1 = str1; std::wstring wstr1 = L"Hello world"; gsl::cwstring_span<> s2 = wstr1;

1
2
3
4
5

std::string str1 = "Hello world";
gsl::cstring_span<> s1 = str1;

std::wstring wstr1 = L"Hello world";
gsl::cwstring_span<> s2 = wstr1;
from an array

C++

char a1[] = "Hello world"; gsl::cstring_span<> s1 = gsl::ensure_z(a1); wchar_t a2[] = L"Hello world"; gsl::cwstring_span<> s2 = gsl::ensure_z(a2);

1
2
3
4
5

char a1[] = "Hello world";
gsl::cstring_span<> s1 = gsl::ensure_z(a1);

wchar_t a2[] = L"Hello world";
gsl::cwstring_span<> s2 = gsl::ensure_z(a2);

from a vector

std::vector<char> vec1 = { 'H','e','l','l','o',' ','w','o','r','l','d' };
gsl::string_span<> s1 = vec1;

std::vector<wchar_t> vec2 = { L'H',L'e',L'l',L'l',L'o',L' ',L'w',L'o',L'r',L'l',L'd' };
gsl::wstring_span<> s2 = vec2;

std::vector<char> vec1 = { 'H','e','l','l','o',' ','w','o','r','l','d' };

gsl::string_span<> s1 = vec1;

std::vector<wchar_t> vec2 = { L'H',L'e',L'l',L'l',L'o',L' ',L'w',L'o',L'r',L'l',L'd' };

gsl::wstring_span<> s2 = vec2;

Converting to string

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

char a1[] = "Hello world";
gsl::cstring_span<> s1 = gsl::ensure_z(a1);
std::string str1 = gsl::to_string(s1);   // str1 = "Hello world"

wchar_t a2[] = L"Hello world";
gsl::cwstring_span<> s2 = gsl::ensure_z(a2);
std::wstring str2 = gsl::to_string(s2);  // str2 = L"Hello world"

char a1[] = "Hello world";

gsl::cstring_span<> s1 = gsl::ensure_z(a1);

std::string str1 = gsl::to_string(s1); // str1 = "Hello world"

wchar_t a2[] = L"Hello world";

gsl::cwstring_span<> s2 = gsl::ensure_z(a2);

std::wstring str2 = gsl::to_string(s2); // str2 = L"Hello world"

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

std::string str1 = "Hello world";
gsl::cstring_span<> s1 = str1;

std::cout << "length=" << s1.length() << std::endl;              // length=11
std::cout << "size=" << s1.size() << std::endl;                  // size=11

std::cout << "length bytes=" << s1.length_bytes() << std::endl;  // length bytes=11
std::cout << "size bytes=" << s1.size_bytes() << std::endl;      // size bytes=11

std::wstring str2 = L"Hello world";
gsl::cwstring_span<> s2 = str2;

std::cout << "length=" << s2.length() << std::endl;              // length=11
std::cout << "size=" << s2.size() << std::endl;                  // size=11

std::cout << "length bytes=" << s2.length_bytes() << std::endl;  // length bytes=22
std::cout << "size bytes=" << s2.size_bytes() << std::endl;      // size bytes=22

std::string str1 = "Hello world";

gsl::cstring_span<> s1 = str1;

std::cout << "length=" << s1.length() << std::endl; // length=11

std::cout << "size=" << s1.size() << std::endl; // size=11

std::cout << "length bytes=" << s1.length_bytes() << std::endl; // length bytes=11

std::cout << "size bytes=" << s1.size_bytes() << std::endl; // size bytes=11

std::wstring str2 = L"Hello world";

gsl::cwstring_span<> s2 = str2;

std::cout << "length=" << s2.length() << std::endl; // length=11

std::cout << "size=" << s2.size() << std::endl; // size=11

std::cout << "length bytes=" << s2.length_bytes() << std::endl; // length bytes=22

std::cout << "size bytes=" << s2.size_bytes() << std::endl; // size bytes=22

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.

std::string str1 = "Hello world";
gsl::cstring_span<> s1 = str1;            // s1 = { 'H','e','l','l','o',' ','w','o','r','l','d' }
gsl::cstring_span<> l = s1.first(5);      // l = { 'H','e','l','l','o' }
gsl::cstring_span<> r = s1.last(5);       // r = { 'w','o','r','l','d' }
gsl::cstring_span<> m = s1.subspan(3, 5); // m = { 'l','o',' ','w','o' }

std::string str1 = "Hello world";

gsl::cstring_span<> s1 = str1; // s1 = { 'H','e','l','l','o',' ','w','o','r','l','d' }

gsl::cstring_span<> l = s1.first(5); // l = { 'H','e','l','l','o' }

gsl::cstring_span<> r = s1.last(5); // r = { 'w','o','r','l','d' }

gsl::cstring_span<> m = s1.subspan(3, 5); // m = { 'l','o',' ','w','o' }

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).

std::string str1 = "Hello world";
gsl::cstring_span<> s1 = str1;

std::string str2 = "Hello world!";
gsl::cstring_span<> s2 = str2;

std::cout << (s1 == s2) << std::endl; // prints 0
std::cout << (s1 != s2) << std::endl; // prints 1
std::cout << (s1 < s2)  << std::endl; // prints 1
std::cout << (s1 > s2)  << std::endl; // prints 0

std::string str1 = "Hello world";

gsl::cstring_span<> s1 = str1;

std::string str2 = "Hello world!";

gsl::cstring_span<> s2 = str2;

std::cout << (s1 == s2) << std::endl; // prints 0

std::cout << (s1 != s2) << std::endl; // prints 1

std::cout << (s1 < s2) << std::endl; // prints 1

std::cout << (s1 > s2) << std::endl; // prints 0

Element access

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

std::string str = "Hello world";
gsl::cstring_span<> s = str;

// prints Hello world
for (auto const & e : s) std::cout << e;
std::cout << std::endl;

// prints dlrow olleH
for (auto it = s.rbegin(); it != s.rend(); ++it) std::cout << *it;
std::cout << std::endl;

// prints Hello world
for (auto it = std::begin(s); it != std::end(s); ++it) std::cout << *it;
std::cout << std::endl;

// prints Hello world
for (ptrdiff_t i = 0; i < s.size(); ++i)
    std::cout << s[i];
std::cout << std::endl;

//s[5] = '-'; // Error	C3892	's': you cannot assign to a variable that is const

std::string str = "Hello world";

gsl::cstring_span<> s = str;

// prints Hello world

for (auto const & e : s) std::cout << e;

std::cout << std::endl;

// prints dlrow olleH

for (auto it = s.rbegin(); it != s.rend(); ++it) std::cout << *it;

std::cout << std::endl;

// prints Hello world

for (auto it = std::begin(s); it != std::end(s); ++it) std::cout << *it;

std::cout << std::endl;

// prints Hello world

for (ptrdiff_t i = 0; i < s.size(); ++i)

std::cout << s[i];

std::cout << std::endl;

//s[5] = '-'; // Error C3892 's': you cannot assign to a variable that is const

std::string str = "Hello world";
gsl::string_span<> s = str;

s[5] = '-';

// prints Hello-world
for (ptrdiff_t i = 0; i < s.size(); ++i)
   std::cout << s[i];
std::cout << std::endl;

std::string str = "Hello world";

gsl::string_span<> s = str;

s[5] = '-';

// prints Hello-world

for (ptrdiff_t i = 0; i < s.size(); ++i)

std::cout << s[i];

std::cout << std::endl;

Guidelines Support Library Review: span<T>

6 Replies

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:

template <typename T>
void display(std::vector<T> const & data)
{
   for (auto const e : data) std::cout << e << ' ';
   std::cout << std::endl;
}

std::vector<int> v{ 1, 2, 3, 4, 5 };
display(v);

template <typename T>

void display(std::vector<T> const & data)

{

for (auto const e : data) std::cout << e << ' ';

std::cout << std::endl;

}

std::vector<int> v{ 1, 2, 3, 4, 5 };

display(v);

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

template <class Iterator>
void display(Iterator const b, Iterator const e)
{
   for (Iterator i = b; i != e; ++i) std::cout << *i << ' ';
   std::cout << std::endl;
}

template <typename T>
void display(std::vector<T> const & data)
{
   display(std::begin(data), std::end(data));
}

template <typename T, size_t S>
void display(std::array<T, S> const & data)
{
   display(std::begin(data), std::end(data));
}

std::vector<int> v{ 1, 2, 3, 4, 5 };
display(v);

std::array<int, 5> a{1, 2, 3, 4, 5};
display(a);

template <class Iterator>

void display(Iterator const b, Iterator const e)

{

for (Iterator i = b; i != e; ++i) std::cout << *i << ' ';

std::cout << std::endl;

}

template <typename T>

void display(std::vector<T> const & data)

{

display(std::begin(data), std::end(data));

}

template <typename T, size_t S>

void display(std::array<T, S> const & data)

{

display(std::begin(data), std::end(data));

}

std::vector<int> v{ 1, 2, 3, 4, 5 };

display(v);

std::array<int, 5> a{1, 2, 3, 4, 5};

display(a);

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.

template <typename T>
void display(gsl::span<T> const & data)
{
   for(auto const e : data) std::cout << e << ' ';
   std::cout << std::endl;
}

std::vector<int> v{ 1, 2, 3, 4, 5 };
gsl::span<int> s1{ v };
display(s1);

std::array<int, 5> a{1, 2, 3, 4, 5};
gsl::span<int> s2{ a };
display(s2);

int arr[] = { 1, 2, 3, 4, 5 };
gsl::span<int> s3{ arr };
display(s3);

template <typename T>

void display(gsl::span<T> const & data)

{

for(auto const e : data) std::cout << e << ' ';

std::cout << std::endl;

}

std::vector<int> v{ 1, 2, 3, 4, 5 };

gsl::span<int> s1{ v };

display(s1);

std::array<int, 5> a{1, 2, 3, 4, 5};

gsl::span<int> s2{ a };

display(s2);

int arr[] = { 1, 2, 3, 4, 5 };

gsl::span<int> s3{ arr };

display(s3);

The following helper functions are used in the samples below:

template <class Iterator>
void show(Iterator b, Iterator e)
{
   for (auto i = b; i != e; ++i)
   {
      std::cout << *i << ' ';
   }
   std::cout << std::endl;
}

template <class T>
void show(gsl::span<T> const & s)
{
   show(std::begin(s), std::end(s));
}

template <class T, size_t R>
void show(gsl::span<T, R> const & s)
{
   show(std::begin(s), std::end(s));
}

template <class T, size_t R, size_t C>
void show(gsl::span<T, R, C> const & s)
{
   show(std::begin(s), std::end(s));
}

template <class T, size_t R, size_t C>
void show(gsl::span<T, gsl::dynamic_range, R, C> const & s)
{
   show(std::begin(s), std::end(s));
}

template <class Iterator>

void show(Iterator b, Iterator e)

{

for (auto i = b; i != e; ++i)

{

std::cout << *i << ' ';

}

std::cout << std::endl;

}

template <class T>

void show(gsl::span<T> const & s)

{

show(std::begin(s), std::end(s));

}

template <class T, size_t R>

void show(gsl::span<T, R> const & s)

{

show(std::begin(s), std::end(s));

}

template <class T, size_t R, size_t C>

void show(gsl::span<T, R, C> const & s)

{

show(std::begin(s), std::end(s));

}

template <class T, size_t R, size_t C>

void show(gsl::span<T, gsl::dynamic_range, R, C> const & s)

{

show(std::begin(s), std::end(s));

}

Creating a span

A span can be created in many ways, including:

from a single value (variable, not a literal)

C++

int n = 1; gsl::span<int> s1 = n; // s1 = {1} gsl::span<int, 1> s2 = n; // se = {1}

1
2
3

int n = 1;
gsl::span<int> s1 = n; // s1 = {1}
gsl::span<int, 1> s2 = n; // se = {1}

from a pointer and number of elements

std::vector<int> v = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
gsl::span<int>    s1(v.data(), 4); // s1 = {1, 2, 3, 4}
gsl::span<int, 4> s2(v.data(), 4); // s2 = {1, 2, 3, 4}

std::vector<int> v = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };

gsl::span<int> s1(v.data(), 4); // s1 = {1, 2, 3, 4}

gsl::span<int, 4> s2(v.data(), 4); // s2 = {1, 2, 3, 4}

from a begin and end pointer

std::vector<int> v = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
gsl::span<int>    s1(&v[0], &v[4]); // s1 = {1, 2, 3, 4}
gsl::span<int, 4> s2(&v[0], &v[4]); // s2 = {1, 2, 3, 4}

std::vector<int> v = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };

gsl::span<int> s1(&v[0], &v[4]); // s1 = {1, 2, 3, 4}

gsl::span<int, 4> s2(&v[0], &v[4]); // s2 = {1, 2, 3, 4}

from a C-like array

int arr[] = { 1, 2, 3, 4, 5 };
gsl::span<int>    s1{ arr }; // s1 = {1, 2, 3, 4, 5}
gsl::span<int, 5> s2{ arr }; // s2 = {1, 2, 3, 4, 5}

int arr2[2][3] = {1, 2, 3, 4, 5, 6};
gsl::span<int>       s3{ arr2 }; // s3 = {1, 2, 3, 4, 5, 6}
gsl::span<int, 6>    s4{ arr2 }; // s3 = {1, 2, 3, 4, 5, 6}
gsl::span<int, 2, 3> s5{ arr2 }; // s3 = {1, 2, 3, 4, 5, 6}

int arr[] = { 1, 2, 3, 4, 5 };

gsl::span<int> s1{ arr }; // s1 = {1, 2, 3, 4, 5}

gsl::span<int, 5> s2{ arr }; // s2 = {1, 2, 3, 4, 5}

int arr2[2][3] = {1, 2, 3, 4, 5, 6};

gsl::span<int> s3{ arr2 }; // s3 = {1, 2, 3, 4, 5, 6}

gsl::span<int, 6> s4{ arr2 }; // s3 = {1, 2, 3, 4, 5, 6}

gsl::span<int, 2, 3> s5{ arr2 }; // s3 = {1, 2, 3, 4, 5, 6}

from a dynamic array

int (*arr)[3][3] = new int[2][3][3];
for (int i = 0; i < 2; ++i)
{
   for (int j = 0; j < 3; j++)
   {
      for (int k = 0; k < 3; ++k)
      {
         arr[i][j][k] = k + j * 3 + i * 9;
      }
   }
}

gsl::span<int, gsl::dynamic_range, 3, 4> s1{ arr, 2 };
show(s1);  // prints 0 1 2 3 4 .. 17

delete[] arr;

int (*arr)[3][3] = new int[2][3][3];

for (int i = 0; i < 2; ++i)

{

for (int j = 0; j < 3; j++)

{

for (int k = 0; k < 3; ++k)

{

arr[i][j][k] = k + j * 3 + i * 9;

}

gsl::span<int, gsl::dynamic_range, 3, 4> s1{ arr, 2 };

show(s1); // prints 0 1 2 3 4 .. 17

delete[] arr;

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

std::array<int, 5> a = { 1, 2, 3, 4, 5 };
gsl::span<int>    s1{ a }; // s1 = {1, 2, 3, 4, 5, 6}
gsl::span<int, 5> s2{ a }; // s2 = {1, 2, 3, 4, 5, 6}

std::vector<int> v = { 1, 2, 3, 4, 5 };
gsl::span<int>    s3{ v }; // s3 = {1, 2, 3, 4, 5, 6}
gsl::span<int, 5> s4{ v }; // s4 = {1, 2, 3, 4, 5, 6}

std::string text = "sample";
gsl::span<const char> s5{ text }; // s5 = {'s', 'a', 'm', 'p', 'l', 'e'}

std::array<int, 5> a = { 1, 2, 3, 4, 5 };

gsl::span<int> s1{ a }; // s1 = {1, 2, 3, 4, 5, 6}

gsl::span<int, 5> s2{ a }; // s2 = {1, 2, 3, 4, 5, 6}

std::vector<int> v = { 1, 2, 3, 4, 5 };

gsl::span<int> s3{ v }; // s3 = {1, 2, 3, 4, 5, 6}

gsl::span<int, 5> s4{ v }; // s4 = {1, 2, 3, 4, 5, 6}

std::string text = "sample";

gsl::span<const char> s5{ text }; // s5 = {'s', 'a', 'm', 'p', 'l', 'e'}

using the gsl::as_span() function:

std::vector<int> v = { 1, 2, 3, 4, 5 };
auto sv = gsl::as_span(v);  // sv = {1, 2, 3, 4, 5}

std::array<int, 5> a = { 1, 2, 3, 4, 5 };
auto sa = gsl::as_span(a);  // sa = {1, 2, 3, 4, 5}

std::vector<int> v = { 1, 2, 3, 4, 5 };

auto sv = gsl::as_span(v); // sv = {1, 2, 3, 4, 5}

std::array<int, 5> a = { 1, 2, 3, 4, 5 };

auto sa = gsl::as_span(a); // sa = {1, 2, 3, 4, 5}

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.

gsl::span<int> s0{ nullptr }; // rank = 1, extent[0] = 0
gsl::span<int> s1;            // rank = 1, extent[0] = 0 

int arr[] = { 1, 2, 3, 4, 5 };
gsl::span<int> s2{ arr };     // rank = 1, extent[0] = 5
gsl::span<int, 5> s3{ arr };  // rank = 1, extent[0] = 5

std::cout << "rank=" << s2.rank() << std::endl;           // rank=1
std::cout << "extent(0)=" << s2.extent(0) << std::endl;   // extent[0]=5
std::cout << "extent<0>=" << s2.extent<0>() << std::endl; // extent[0]=5

gsl::span<int, 2, 3> s4{ arr, 6 }; // rank = 2, extent[0] = 2, extent[1] = 3

std::cout << "rank=" << s4.rank() << std::endl;           // rank=2
std::cout << "extent(0)=" << s4.extent(0) << std::endl;   // extent[0]=2
std::cout << "extent(1)=" << s4.extent(1) << std::endl;   // extent[1]=3

gsl::span<int> s0{ nullptr }; // rank = 1, extent[0] = 0

gsl::span<int> s1; // rank = 1, extent[0] = 0

int arr[] = { 1, 2, 3, 4, 5 };

gsl::span<int> s2{ arr }; // rank = 1, extent[0] = 5

gsl::span<int, 5> s3{ arr }; // rank = 1, extent[0] = 5

std::cout << "rank=" << s2.rank() << std::endl; // rank=1

std::cout << "extent(0)=" << s2.extent(0) << std::endl; // extent[0]=5

std::cout << "extent<0>=" << s2.extent<0>() << std::endl; // extent[0]=5

gsl::span<int, 2, 3> s4{ arr, 6 }; // rank = 2, extent[0] = 2, extent[1] = 3

std::cout << "rank=" << s4.rank() << std::endl; // rank=2

std::cout << "extent(0)=" << s4.extent(0) << std::endl; // extent[0]=2

std::cout << "extent(1)=" << s4.extent(1) << std::endl; // extent[1]=3

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.

int arr[] = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
gsl::span<int> s{ arr };

auto fs1 = s.first(0);        // fs1 = {}
auto fs2 = s.first(5);        // fs2 = {1, 2, 3, 4, 5}
auto fs3 = s.first<3>();      // fs3 = {1, 2, 3}

auto ls1 = s.last(0);         // ls1 = {}
auto ls2 = s.last(5);         // ls2 = {6, 7, 8, 9, 10} 
auto ls3 = s.last<3>();       // ls3 = {8, 9, 10}

auto ns1 = s.subspan(0, 0);   // ns1 = {}
auto ns2 = s.subspan(0, 5);   // ns2 = {1, 2, 3, 4, 5}
auto ns3 = s.subspan(5, 0);   // ns3 = {}
auto ns4 = s.subspan<0, 0>(); // ns4 = {}
auto ns5 = s.subspan<0, 5>(); // ns5 = {1, 2, 3, 4, 5}
auto ns6 = s.subspan<5, 0>(); // ns6 = {}

int arr[] = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };

gsl::span<int> s{ arr };

auto fs1 = s.first(0); // fs1 = {}

auto fs2 = s.first(5); // fs2 = {1, 2, 3, 4, 5}

auto fs3 = s.first<3>(); // fs3 = {1, 2, 3}

auto ls1 = s.last(0); // ls1 = {}

auto ls2 = s.last(5); // ls2 = {6, 7, 8, 9, 10}

auto ls3 = s.last<3>(); // ls3 = {8, 9, 10}

auto ns1 = s.subspan(0, 0); // ns1 = {}

auto ns2 = s.subspan(0, 5); // ns2 = {1, 2, 3, 4, 5}

auto ns3 = s.subspan(5, 0); // ns3 = {}

auto ns4 = s.subspan<0, 0>(); // ns4 = {}

auto ns5 = s.subspan<0, 5>(); // ns5 = {1, 2, 3, 4, 5}

auto ns6 = s.subspan<5, 0>(); // ns6 = {}

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).

int arr1[2][3] = { 1, 2, 3, 4, 5, 6 };
gsl::span<int, 6> s1{ arr1 };

int arr2[] = { 1, 2, 3, 4, 5, 6 };
gsl::span<int> s2{ arr2 };

int arr3[] = { 1, 2, 3 };
gsl::span<int> s3{ arr3 };

int arr4[] = { 3, 2, 1 };
gsl::span<int> s4{ arr4 };

std::cout << (s1 == s2) << std::endl; // prints 1
std::cout << (s2 == s3) << std::endl; // prints 0
std::cout << (s2 > s3)  << std::endl; // prints 1
std::cout << (s4 != s3) << std::endl; // prints 1
std::cout << (s4 > s3)  << std::endl; // prints 1

int arr1[2][3] = { 1, 2, 3, 4, 5, 6 };

gsl::span<int, 6> s1{ arr1 };

int arr2[] = { 1, 2, 3, 4, 5, 6 };

gsl::span<int> s2{ arr2 };

int arr3[] = { 1, 2, 3 };

gsl::span<int> s3{ arr3 };

int arr4[] = { 3, 2, 1 };

gsl::span<int> s4{ arr4 };

std::cout << (s1 == s2) << std::endl; // prints 1

std::cout << (s2 == s3) << std::endl; // prints 0

std::cout << (s2 > s3) << std::endl; // prints 1

std::cout << (s4 != s3) << std::endl; // prints 1

std::cout << (s4 > s3) << std::endl; // prints 1

Element access

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

std::vector<int> v = { 1, 2, 3, 4, 5, 6 };
gsl::span<int> s{ v };

// prints 1 2 3 4 5 6
for (auto const & e : s) std::cout << e << std::endl;
// prints 6 5 4 3 2 1
for (auto it = s.rbegin(); it != s.rend(); ++it) std::cout << *it << std::endl;
// prints 1 2 3 4 5 6
for (auto it = std::begin(s); it != std::end(s); ++it) std::cout << *it << std::endl;

std::vector<int> v = { 1, 2, 3, 4, 5, 6 };

gsl::span<int> s{ v };

// prints 1 2 3 4 5 6

for (auto const & e : s) std::cout << e << std::endl;

// prints 6 5 4 3 2 1

for (auto it = s.rbegin(); it != s.rend(); ++it) std::cout << *it << std::endl;

// prints 1 2 3 4 5 6

for (auto it = std::begin(s); it != std::end(s); ++it) std::cout << *it << std::endl;

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.

std::vector<int> v = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12};
gsl::span<int> s1{ v };
gsl::span<int, 3, 4> s2{ v };

// prints 1 2 3 ... 12
for (int i = 0; i < s1.extent(0); ++i) 
   std::cout << s1[i] << ' ';
std::cout << std::endl;

// prints 
// 1 2 3 4
// 5 6 7 8
// 9 10 11 12
for (int i = 0; i < s2.extent(0); ++i)
{
   for (int j = 0; j < s2.extent(1); ++j)
      std::cout << s2[i][j] << ' ';
   std::cout << std::endl;
}

// uni-dimensional index
gsl::index<1> i1 = { 0 };
std::cout << s1[i1] << std::endl;  // prints 1

// bi-dimensional index
gsl::index<2> i2 = { 1, 1 };
std::cout << s2[i2] << std::endl;  // prints 6

// bi-dimensional index computed from another index
gsl::index<2> i3 = i2 * 2; 
std::cout << s2[i3] << std::endl;  // prints 11

std::vector<int> v = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12};

gsl::span<int> s1{ v };

gsl::span<int, 3, 4> s2{ v };

// prints 1 2 3 ... 12

for (int i = 0; i < s1.extent(0); ++i)

std::cout << s1[i] << ' ';

std::cout << std::endl;

// prints

// 1 2 3 4

// 5 6 7 8

// 9 10 11 12

for (int i = 0; i < s2.extent(0); ++i)

{

for (int j = 0; j < s2.extent(1); ++j)

std::cout << s2[i][j] << ' ';

std::cout << std::endl;

}

// uni-dimensional index

gsl::index<1> i1 = { 0 };

std::cout << s1[i1] << std::endl; // prints 1

// bi-dimensional index

gsl::index<2> i2 = { 1, 1 };

std::cout << s2[i2] << std::endl; // prints 6

// bi-dimensional index computed from another index

gsl::index<2> i3 = i2 * 2;

std::cout << s2[i3] << std::endl; // prints 11

C++ Gems: ref-qualifiers

cv-qualifiers

Let’s take the following example of a type foo that has two overloaded methods, one const and one not const.

struct foo
{
   void test()       { std::cout << "test" << std::endl; }
   void test() const { std::cout << "test const" << std::endl; }
};

struct foo

{

void test() { std::cout << "test" << std::endl; }

void test() const { std::cout << "test const" << std::endl; }

};

The following code prints either “test” or “test const” depending on whether the object function test() is called on is const or not.

foo f1;
f1.test();     // prints "test"

foo const f2;
f2.test();     // prints "test const"

foo().test();  // prints "test"

foo f1;

f1.test(); // prints "test"

foo const f2;

f2.test(); // prints "test const"

foo().test(); // prints "test"

Notice that the const/volatile specification is not a constrain on the function, but on the implied this parameter. A const function can freely modify state or call non-const methods, but not state or non-const methods that belong to the object referred by this.

Let’s consider a second example where he have a Widget contained within a bar. The bar has methods to return the internal state. If the object is const, the overload resolution picks the const method, if it is non-const it picks the non-const method.

struct Widget
{
   Widget(std::string const & name) : name(name) {};
   Widget(Widget const & w)   { std::cout << "copy" << std::endl; name = w.name; }
   Widget(Widget&& w)         { std::cout << "move" << std::endl; name = std::move(w.name); }

private:
   std::string name;
};

struct bar
{   
   Widget&       data()          { return _widget; }
   Widget const& data() const    { return _widget; }

private:
   Widget _widget{ "bar" };
};

bar b1;
auto w1 = b1.data();    // prints copy

bar const b2;
auto w2 = b2.data();    // prints copy

auto w3 = bar().data(); // prints copy

struct Widget

{

Widget(std::string const & name) : name(name) {};

Widget(Widget const & w) { std::cout << "copy" << std::endl; name = w.name; }

Widget(Widget&& w) { std::cout << "move" << std::endl; name = std::move(w.name); }

private:

std::string name;

};

struct bar

{

Widget& data() { return _widget; }

Widget const& data() const { return _widget; }

private:

Widget _widget{ "bar" };

};

bar b1;

auto w1 = b1.data(); // prints copy

bar const b2;

auto w2 = b2.data(); // prints copy

auto w3 = bar().data(); // prints copy

The problem with this code is that in all cases the Widget was copied even though in the last example the Widget owner was an rvalue reference and the object could have been moved.

To fix this problem we can add a new method that returns an rvalue reference. However, the problem now is that we cannot have two overloaded methods, one that returns a lvalue reference and one that returns an rvalue reference. So the best we could do is this:

struct bar
{   
   Widget const & data() const   { return _widget; }
   Widget&&       data()         { return std::move(_widget); }

private:
   Widget _widget{ "bar" };
};

bar b1;
auto w1 = b1.data();    // prints move

bar const b2;
auto w2 = b2.data();    // prints copy

auto w3 = bar().data(); // prints move

struct bar

{

Widget const & data() const { return _widget; }

Widget&& data() { return std::move(_widget); }

private:

Widget _widget{ "bar" };

};

bar b1;

auto w1 = b1.data(); // prints move

bar const b2;

auto w2 = b2.data(); // prints copy

auto w3 = bar().data(); // prints move

This fixed the 3rd case with the rvalue reference, but it broke the first object. After calling b1.data() the Widget from b1 was moved to w1.

What’s the solution?

Enter ref-qualifiers

ref-qualifiers are a way to help the compiler decide which function to call when the object is an lvalue or an rvalue. Since the object is passed as an implicit pointer type parameter to the function (pointer this) the ref-qualifiers have been also referred as “rvalue reference for *this”.

ref-qualifiers are specified with & for lvalues and && for rvalues at the end of the function signature after the cv-qualifiers.

struct bar
{   
   Widget&        data() &         { return _widget; }
   Widget const & data() const &   { return _widget; }
   Widget&&       data() &&        { return std::move(_widget); }

private:
   Widget _widget{ "bar" };
};

struct bar

{

Widget& data() & { return _widget; }

Widget const & data() const & { return _widget; }

Widget&& data() && { return std::move(_widget); }

private:

Widget _widget{ "bar" };

};

The following code now prints “copy”, “copy”, “move” as expected.

bar b1;
auto w1 = b1.data();    // prints copy

bar const b2;
auto w2 = b2.data();    // prints copy

auto w3 = bar().data(); // prints move

bar b1;

auto w1 = b1.data(); // prints copy

bar const b2;

auto w2 = b2.data(); // prints copy

auto w3 = bar().data(); // prints move

One important thing to note is that you cannot mix ref-qualifier and non-ref-qualifier overloads. You must decided over one or another set of overloads. The following is illegal:

Widget&        data()           { return _widget; } // no ref-qualifier
Widget const & data() const     { return _widget; } // no ref-qualifier
Widget&&       data() &&        { return std::move(_widget); } // ref-qualifier

Widget& data() { return _widget; } // no ref-qualifier

Widget const & data() const { return _widget; } // no ref-qualifier

Widget&& data() && { return std::move(_widget); } // ref-qualifier

The ref-qualifiers help avoiding unnecessary calls/operations on rvalue references which is helpful when may involve large objects. But they are also helpful to avoid making coding mistakes. Here is an example. Consider the following type:

struct foo
{
   foo(int const value = 0) :value(value)
   {}

   foo& operator=(foo const & other)
   {
      this->value = other.value;
      return *this;
   }

   operator int() const { return value; }

private:
   int value;
};

foo get_foo()
{
   return foo(13);
}

struct foo

{

foo(int const value = 0) :value(value)

{}

foo& operator=(foo const & other)

{

this->value = other.value;

return *this;

}

operator int() const { return value; }

private:

int value;

};

foo get_foo()

{

return foo(13);

}

You can write things like this:

foo() = 42;

if (get_foo() = 42)
{
}

foo() = 42;

if (get_foo() = 42)

{

}

Probably the first example is a little bit silly, you don’t do that kind of mistake in real life, but it’s still legal code that executes, and is not right because there’s an rvalue reference on the left side of the assignment operator. The second example is definitely a much realistic example. Sometimes we just type = instead of == in conditional expressions and what the code will do is assigning 42 to temporary, instead of testing their equality.

If we changed the signature of foo’s operator= to include a ref-qualifier (as shown below) the compiler would flag immediately both examples above as errors:

foo& operator=(foo const & other) & 
{
 // ...
}

foo& operator=(foo const & other) &

{

// ...

}

VC++ 2014 now flags the following error:

error C2678: binary ‘=’: no operator found which takes a left-hand operand of type ‘foo’ (or there is no acceptable conversion)

Compiler support

GCC: 4.8.1
Clang: 2.9
Intel: 14.0
VC++: v13 (Visual Studio 2014)

User defined literals

3 Replies

The C++ language defines various built-in literals (numerical, character, string, boolean and pointer) and a series of prefixes and suffixes to specify some of them. The suffix or prefix is part of the literal.

auto b = true;     // boolean
auto s = "sample"; // const char[7]
auto i = 128;      // int
auto d = 128.0;    // double
auto p = nullptr;  // nullptr_t

// with prefixes
auto w = L"text";  // const wchar_t[5]
auto h = 0xBAD;    // int (in hexadecimal representation)

// with suffixes
auto a = 128u;     // unsigned int
auto l = 128l;     // signed long
auto f = 128.0f;   // float

auto b = true; // boolean

auto s = "sample"; // const char[7]

auto i = 128; // int

auto d = 128.0; // double

auto p = nullptr; // nullptr_t

// with prefixes

auto w = L"text"; // const wchar_t[5]

auto h = 0xBAD; // int (in hexadecimal representation)

// with suffixes

auto a = 128u; // unsigned int

auto l = 128l; // signed long

auto f = 128.0f; // float

The C++11 standard introduced the possibility to create user-defined literals, that are basically built-in type literals (integer, float, char or string) followed by a used-defined suffix. User-defined literals enable the creation of new objects based on the built-in literal value and the applied user-defined suffix.

auto temp = 77_fah;       // 77 Fahrenheit degrees = 25 Celsius degrees
auto size = 1_KB;         // 1 kilobyte = 1024 bytes
auto emp  = "marius"_dev; // a user defined type Developer

auto temp = 77_fah; // 77 Fahrenheit degrees = 25 Celsius degrees

auto size = 1_KB; // 1 kilobyte = 1024 bytes

auto emp = "marius"_dev; // a user defined type Developer

A bit of theory

A user-defined literal is treated as a call to a literal operator or a literal operator template. User-defined literals have two forms:

raw: a sequence of characters; the literal 0xBAD is in raw form is ‘0’, ‘x’, ‘B’, ‘A’, ‘D’
cooked: is the compiler interpreted type of the sequence of characters; the literal 0xBAD is the integer 2898 in cooked form.

User-defined literals:

support only the suffix form; defining prefixes is not possible;
begin with a underscore (‘_’); all suffixes that begin with any other character except underscore are reserved by the standard;
can be extended in both raw and cooked form; the exception is represented by strings that can only be extended in the cooked form

Cooked literals

The literal operator called for a cooked literal has following form:

OutputType operator "" _suffix(InputType);

1	OutputType operator "" _suffix(InputType);

Only several input types are allowed:

for integral literals (decimal, octal, hexadecimal or binary) the type is unsigned long long (the reason for unsigned is that the sign is not part of a numeric literal, but is in fact a unary operator applied to the numerical value).

C++

OutputType operator "" _suffix(unsigned long long);

1

OutputType operator "" _suffix(unsigned long long);
for floating point types the type is long double:

C++

OutputType operator "" _suffix(long double);

1

OutputType operator "" _suffix(long double);

for characters the type is char, wchar_t, char16_t or char32_t:

OutputType operator "" _suffix(char);
OutputType operator "" _suffix(wchar_t);
OutputType operator "" _suffix(char16_t);
OutputType operator "" _suffix(char32_t);

OutputType operator "" _suffix(char);

OutputType operator "" _suffix(wchar_t);

OutputType operator "" _suffix(char16_t);

OutputType operator "" _suffix(char32_t);

for strings the type is char const *, wchar_t const *, char16_t const * or char32_t const *:

OutputType operator "" _suffix(char const *, std::size_t);
OutputType operator "" _suffix(wchar_t const *, std::size_t);
OutputType operator "" _suffix(char16_t const *, std::size_t);
OutputType operator "" _suffix(char32_t const *, std::size_t);

OutputType operator "" _suffix(char const *, std::size_t);

OutputType operator "" _suffix(wchar_t const *, std::size_t);

OutputType operator "" _suffix(char16_t const *, std::size_t);

OutputType operator "" _suffix(char32_t const *, std::size_t);

Raw literals

Raw literals are supported only for integral and floating point types. The literal operator called for a cooked literal has following form (notice that the operator does not take a second parameter to indicate the size, the string is null-terminated):

OutputType operator "" _suffix(const char*);

1	OutputType operator "" _suffix(const char*);

Parsing this array of characters may involve loops, variable declaration, function calls, etc. As a result this form of the literal operator cannot be constexpr, which means it cannot be evaluated at compile time.

An alternative way of processing raw literals is with a literal operator variadic template. The purpose of a variadic template literal operator is to make the literal transformation at compile time. The form of the literal operator template is:

template<char...> OutputType operator "" _tuffix();

1	template<char...> OutputType operator "" _tuffix();

A bit of practice

Let’s take the following example where we declare a buffer of 4 KB.

std::array<unsigned char, 4_KB> buffer;

1	std::array<unsigned char, 4_KB> buffer;

This is identical to the following declaration (you’d usually expect)

std::array<unsigned char, 4096> buffer;

1	std::array<unsigned char, 4096> buffer;

It is made possible by the existence of a literal operator with the following form:

constexpr size_t operator "" _KB(unsigned long long size)
{
   return static_cast<size_t>(size * 1024);
}

constexpr size_t operator "" _KB(unsigned long long size)

{

return static_cast<size_t>(size * 1024);

}

If the literal operator was not a constexpr then the compiler would trigger an error when declaring the buffer variable, because the size of the array must be known at compile time. You’d still be able to use the user-defined literal but in runtime contexts, such as sizing a vector.

std::vector<unsigned char> buffer(4_KB);

1	std::vector<unsigned char> buffer(4_KB);

In the next example we define a user-defined literal for expressing temperatures in Fahrenheit degrees. Supposing the Celsius degrees are the norm, we can write sometime like this:

constexpr long double operator"" _fah(long double const degrees)
{
   return (degrees - 32.0) / 1.8;
}

constexpr long double operator"" _fah(long double const degrees)

{

return (degrees - 32.0) / 1.8;

}

and use it like in the following example:

auto threshold = 77.0_fah;
auto temp = 0.0;
std::cout << "Input temperature (in Celsius):";
std::cin >> temp;

std::cout << (temp < threshold ? "cold" : "warm") << std::endl;

auto threshold = 77.0_fah;

auto temp = 0.0;

std::cout << "Input temperature (in Celsius):";

std::cin >> temp;

std::cout << (temp < threshold ? "cold" : "warm") << std::endl;

The return type of the literal operator can be any type; it does not have to be a built-in type like in the previous examples. Given the following hierarchy of classes we can create user-defined literals that enable the creation of developer and quality assurer objects:

class Employee
{
   std::string name;
public:
   Employee(std::string const & name) :name(name){}
   std::string getName() const { return name; }
};

class Developer : public Employee
{
public:
   using Employee::Employee;
};

class QualityAssurer : public Employee
{
public:
   using Employee::Employee;
};

Developer operator "" _dev(char const * text, std::size_t const size)
{
   return Developer(std::string(text, text + size));
}

QualityAssurer operator "" _qa(char const * text, std::size_t const size)
{
   return QualityAssurer(std::string(text, text + size));
}

int main()
{
   auto d = "marius"_dev;
   auto q = "john"_qa;
   std::cout << d.getName() << std::endl;
   std::cout << q.getName() << std::endl;

   return 0;
}

class Employee

{

std::string name;

public:

Employee(std::string const & name) :name(name){}

std::string getName() const { return name; }

};

class Developer : public Employee

{

public:

using Employee::Employee;

};

class QualityAssurer : public Employee

{

public:

using Employee::Employee;

};

Developer operator "" _dev(char const * text, std::size_t const size)

{

return Developer(std::string(text, text + size));

}

QualityAssurer operator "" _qa(char const * text, std::size_t const size)

{

return QualityAssurer(std::string(text, text + size));

}

int main()

{

auto d = "marius"_dev;

auto q = "john"_qa;

std::cout << d.getName() << std::endl;

std::cout << q.getName() << std::endl;

return 0;

}

In the next example we want to express latitudes, such as 66°33’39”N (the Arctic Circle). (Notice that the following types and just some simple implementations for demo purposes only).

class GeoCoordinate
{
protected:
   double degrees;
   double minutes;
   double seconds;
public:
   constexpr GeoCoordinate(double const degrees, double const minutes, double const seconds)
      :degrees(degrees), minutes(minutes), seconds(seconds)
   {}

   GeoCoordinate& operator+=(GeoCoordinate const & other)
   {
      seconds += other.seconds;
      minutes += other.minutes;
      degrees += other.degrees;

      return *this;
   }

   friend GeoCoordinate operator+(GeoCoordinate lhs, GeoCoordinate const & rhs)
   {
      return lhs += rhs;
   }

   double get_degrees() const { return degrees; }
   double get_minutes() const { return minutes; }
   double get_seconds() const { return seconds; }
};

enum class LatitudeDirection
{
   Undefined,
   North,
   South,
};

class Latitude : public GeoCoordinate
{
   LatitudeDirection direction;
public:
   constexpr Latitude(double const degree, double const minutes, double const seconds, LatitudeDirection const dir = LatitudeDirection::Undefined)
      :GeoCoordinate(degree, minutes, seconds), direction(dir)
   {}

   Latitude& operator+=(Latitude const & other)
   {
      if (direction == other.direction || direction == LatitudeDirection::Undefined || other.direction == LatitudeDirection::Undefined)
      {
         seconds += other.seconds;
         minutes += other.minutes;
         degrees += other.degrees;

         if (direction == LatitudeDirection::Undefined)
         {
            direction = other.direction;
         }
      }
      else
         throw std::exception("Invalid latitude direction");

      return *this;
   }

   friend Latitude operator+(Latitude lhs, Latitude const & rhs)
   {
      return lhs += rhs;
   }

   friend Latitude operator+(Latitude lhs, LatitudeDirection dir)
   {
      if (lhs.direction != LatitudeDirection::Undefined &&
         lhs.direction != dir)
         throw std::exception("Invalid latitude direction");

      Latitude l = lhs;
      l.direction = dir;
      return l;
   }
};

Latitude operator+(GeoCoordinate lhs, LatitudeDirection dir)
{
   return Latitude(lhs.get_degrees(), lhs.get_minutes(), lhs.get_seconds(), dir);
}

class GeoCoordinate

{

protected:

double degrees;

double minutes;

double seconds;

public:

constexpr GeoCoordinate(double const degrees, double const minutes, double const seconds)

:degrees(degrees), minutes(minutes), seconds(seconds)

{}

GeoCoordinate& operator+=(GeoCoordinate const & other)

{

seconds += other.seconds;

minutes += other.minutes;

degrees += other.degrees;

return *this;

}

friend GeoCoordinate operator+(GeoCoordinate lhs, GeoCoordinate const & rhs)

{

return lhs += rhs;

}

double get_degrees() const { return degrees; }

double get_minutes() const { return minutes; }

double get_seconds() const { return seconds; }

};

enum class LatitudeDirection

{

Undefined,

North,

South,

};

class Latitude : public GeoCoordinate

{

LatitudeDirection direction;

public:

constexpr Latitude(double const degree, double const minutes, double const seconds, LatitudeDirection const dir = LatitudeDirection::Undefined)

:GeoCoordinate(degree, minutes, seconds), direction(dir)

{}

Latitude& operator+=(Latitude const & other)

{

if (direction == other.direction || direction == LatitudeDirection::Undefined || other.direction == LatitudeDirection::Undefined)

{

seconds += other.seconds;

minutes += other.minutes;

degrees += other.degrees;

if (direction == LatitudeDirection::Undefined)

{

direction = other.direction;

}

else

throw std::exception("Invalid latitude direction");

return *this;

}

friend Latitude operator+(Latitude lhs, Latitude const & rhs)

{

return lhs += rhs;

}

friend Latitude operator+(Latitude lhs, LatitudeDirection dir)

{

if (lhs.direction != LatitudeDirection::Undefined &&

lhs.direction != dir)

throw std::exception("Invalid latitude direction");

Latitude l = lhs;

l.direction = dir;

return l;

}

};

Latitude operator+(GeoCoordinate lhs, LatitudeDirection dir)

{

return Latitude(lhs.get_degrees(), lhs.get_minutes(), lhs.get_seconds(), dir);

}

With this in place we can create objects like this:

auto g1 = GeoCoordinate(66, 0, 0);
auto g2 = GeoCoordinate(0, 33, 0);
auto g3 = GeoCoordinate(0, 0, 39);
auto g4 = g1 + g2 + g3;
auto g5 = GeoCoordinate(66, 0, 0) + GeoCoordinate(0, 33, 0) + GeoCoordinate(0, 0, 39);

auto l1 = Latitude(66, 0, 0, LatitudeDirection::North);
auto l2 = Latitude(0, 33, 0);
auto l3 = Latitude(0, 0, 39);
auto l4 = l1 + l2 + l3;

auto l5 = Latitude(66, 0, 0, LatitudeDirection::North) + Latitude(0, 33, 0) + Latitude(0, 0, 39);
auto l6 = Latitude(66, 0, 0) + Latitude(0, 33, 0) + Latitude(0, 0, 39) + LatitudeDirection::North;
auto l7 = GeoCoordinate(66, 0, 0) + GeoCoordinate(0, 33, 0) + GeoCoordinate(0, 0, 39) + LatitudeDirection::North;

auto g1 = GeoCoordinate(66, 0, 0);

auto g2 = GeoCoordinate(0, 33, 0);

auto g3 = GeoCoordinate(0, 0, 39);

auto g4 = g1 + g2 + g3;

auto g5 = GeoCoordinate(66, 0, 0) + GeoCoordinate(0, 33, 0) + GeoCoordinate(0, 0, 39);

auto l1 = Latitude(66, 0, 0, LatitudeDirection::North);

auto l2 = Latitude(0, 33, 0);

auto l3 = Latitude(0, 0, 39);

auto l4 = l1 + l2 + l3;

auto l5 = Latitude(66, 0, 0, LatitudeDirection::North) + Latitude(0, 33, 0) + Latitude(0, 0, 39);

auto l6 = Latitude(66, 0, 0) + Latitude(0, 33, 0) + Latitude(0, 0, 39) + LatitudeDirection::North;

auto l7 = GeoCoordinate(66, 0, 0) + GeoCoordinate(0, 33, 0) + GeoCoordinate(0, 0, 39) + LatitudeDirection::North;

Values like Latitude(66, 0, 0) are not very intuitive. Even though it’s more verbose it may be more desirable to be able to create objects like this:

auto lat = deg(66) + min(33) + sec(39) + LatitudeDirection::North;

1	auto lat = deg(66) + min(33) + sec(39) + LatitudeDirection::North;

That is possible if we define deg(), min() and sec() as following:

constexpr GeoCoordinate deg(double value)
{
   return GeoCoordinate(value, 0, 0);
}

constexpr GeoCoordinate min(double value)
{
   return GeoCoordinate(0, value, 0);
}

constexpr GeoCoordinate sec(double value)
{
   return GeoCoordinate(0, 0, value);
}

constexpr GeoCoordinate deg(double value)

{

return GeoCoordinate(value, 0, 0);

}

constexpr GeoCoordinate min(double value)

{

return GeoCoordinate(0, value, 0);

}

constexpr GeoCoordinate sec(double value)

{

return GeoCoordinate(0, 0, value);

}

User-defined literals makes is more simple and more natural. By transforming the above functions into literal operators we can simplify the syntax.

constexpr GeoCoordinate operator "" _deg(long double value)
{
   return GeoCoordinate(value, 0, 0);
}

constexpr GeoCoordinate operator "" _min(long double value)
{
   return GeoCoordinate(0, value, 0);
}

constexpr GeoCoordinate operator "" _sec(long double value)
{
   return GeoCoordinate(0, 0, value);
}

constexpr GeoCoordinate operator "" _deg(long double value)

{

return GeoCoordinate(value, 0, 0);

}

constexpr GeoCoordinate operator "" _min(long double value)

{

return GeoCoordinate(0, value, 0);

}

constexpr GeoCoordinate operator "" _sec(long double value)

{

return GeoCoordinate(0, 0, value);

}

As a result we can now create latitudes like this:

auto lat = 66.0_deg + 33.0_min + 39.0_sec + LatitudeDirection::North;

1	auto lat = 66.0_deg + 33.0_min + 39.0_sec + LatitudeDirection::North;

It should be very simple to develop this to support longitudes. You don’t have to add more literal operators, just the Longitude type and the appropriate overloaded operators for it.

Standard user-defined literals

C++14 defines several literal operators:

operator""if, operator""i and operator""il for creating a std::complex value

C++

#include <complex> int main() { using namespace std::literals::complex_literals; std::complex<double> c = 1.0 + 2i; }

1
2
3
4
5
6
7

#include <complex>

int main()
{
using namespace std::literals::complex_literals;
std::complex<double> c = 1.0 + 2i;
}
operator""h, operator""min, operator""s, operator""ms, operator""us, operator""ns for creating a std::chrono::duration value

C++

#include <chrono> int main() { using namespace std::literals::chrono_literals; auto timer = 1h + 30min + 30s; // duration 01:30:30 }

1
2
3
4
5
6
7

#include <chrono>

int main()
{
using namespace std::literals::chrono_literals;
auto timer = 1h + 30min + 30s; // duration 01:30:30
}

This is equivalent to the following (longer) form in C++11:

C++

auto timer = std::chrono::hours(1) + std::chrono::minutes(30) + std::chrono::seconds(30);

1

auto timer = std::chrono::hours(1) + std::chrono::minutes(30) + std::chrono::seconds(30);
operator""s for converting a character array literal to a std::basic_string

C++

int main() { using namespace std::string_literals; std::string s1 = "text\0"; // s1 = "text" std::string s2 = "text\0"s; // s2 = "text\0" }

1
2
3
4
5
6

int main()
{
   using namespace std::string_literals;
   std::string s1 = "text\0";  // s1 = "text"
   std::string s2 = "text\0"s; // s2 = "text\0"
}

Notice that all these literal operators are defined in separate namespaces that you have to use.

References

Compiler support

User defined literals are supported by major compilers starting with the following version:

GCC: 4.7
Clang: 3.1
VC++: v13 (Visual Studio 2014)

codexpert blog

I see native code

Tag Archives: standard

Guidelines Support Library Review: string_span<T>

String span types

Creating a string_span

Converting to string

Size of a string_span

Subspans

Comparisons

Element access

Like this:

Guidelines Support Library Review: span<T>

Creating a span

Size of a span

Subspans

Comparisons

Element access

Like this:

C++ Gems: ref-qualifiers

cv-qualifiers

Enter ref-qualifiers

Compiler support

See also

Like this:

User defined literals

A bit of theory

Cooked literals

Raw literals

A bit of practice

Standard user-defined literals

References

Compiler support

See also:

Like this:

String span types

Creating a string_span

Converting to string

Size of a string_span

Subspans

Comparisons

Element access

Share this:

Like this:

Creating a span

Size of a span

Subspans

Comparisons

Element access

Share this:

Like this:

cv-qualifiers

Enter ref-qualifiers

Compiler support

See also

Share this:

Like this:

A bit of theory

Cooked literals

Raw literals

A bit of practice

Standard user-defined literals

References

Compiler support

See also:

Share this:

Like this: