boost::hana::string< implementation_defined > Struct Template Reference

Description

template<typename implementation_defined>
struct boost::hana::string< implementation_defined >

Compile-time string.

Conceptually, a hana::string is like a tuple holding integral_constants of underlying type char. However, the interface of hana::string is not as rich as that of a tuple, because a string can only hold compile-time characters as opposed to any kind of object.

Compile-time strings are used for simple purposes like being keys in a hana::map or tagging the members of a Struct. However, you might find that hana::string does not provide enough functionality to be used as a full-blown compile-time string implementation (e.g. regexp matching or substring finding). Indeed, providing a comprehensive string interface is a lot of job, and it is out of the scope of the library for the time being.

Note

The representation of hana::string is implementation-defined. In particular, one should not take for granted that the template parameters are chars. The proper way to access the contents of a hana::string as character constants is to use hana::unpack, .c_str() or hana::to<char const*>, as documented below. More details in the tutorial.

Modeled concepts

For most purposes, a hana::string is functionally equivalent to a tuple holding Constants of underlying type char.

1. Comparable
   Two strings are equal if and only if they have the same number of characters and characters at corresponding indices are equal.

   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   
   #include <boost/hana/assert.hpp>
   #include <boost/hana/equal.hpp>
   #include <boost/hana/not_equal.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   
   
   int main() {
       BOOST_HANA_CONSTANT_CHECK(
           BOOST_HANA_STRING("abcdef") == BOOST_HANA_STRING("abcdef")
       );
   
       BOOST_HANA_CONSTANT_CHECK(
           BOOST_HANA_STRING("abcdef") != BOOST_HANA_STRING("abef")
       );
   }

2. Orderable
   The total order implemented for Orderable is the usual lexicographical comparison of strings.

   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   
   #include <boost/hana/assert.hpp>
   #include <boost/hana/greater.hpp>
   #include <boost/hana/less.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   
   
   int main() {
       BOOST_HANA_CONSTANT_CHECK(
           BOOST_HANA_STRING("abc") < BOOST_HANA_STRING("bcd")
       );
   
       BOOST_HANA_CONSTANT_CHECK(
           BOOST_HANA_STRING("abcd") > BOOST_HANA_STRING("abc")
       );
   }

3. Monoid
   Strings form a monoid under concatenation, with the neutral element being the empty string.

   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   
   #include <boost/hana/assert.hpp>
   #include <boost/hana/equal.hpp>
   #include <boost/hana/plus.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   
   
   auto hello_world = BOOST_HANA_STRING("Hello ") + BOOST_HANA_STRING("world!");
   BOOST_HANA_CONSTANT_CHECK(hello_world == BOOST_HANA_STRING("Hello world!"));
   
   int main() { }

4. Foldable
   Folding a string is equivalent to folding the sequence of its characters.

   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   
   #include <boost/hana/assert.hpp>
   #include <boost/hana/equal.hpp>
   #include <boost/hana/fold_left.hpp>
   #include <boost/hana/integral_constant.hpp>
   #include <boost/hana/plus.hpp>
   #include <boost/hana/string.hpp>
   #include <boost/hana/value.hpp>
   namespace hana = boost::hana;
   
   
   int main() {
       auto sum_string = [](auto str) {
           return hana::fold_left(str, hana::int_c<0>, [](auto sum, auto c) {
               constexpr int i = hana::value(c) - 48; // convert character to decimal
               return sum + hana::int_c<i>;
           });
       };
   
       BOOST_HANA_CONSTANT_CHECK(
           sum_string(BOOST_HANA_STRING("1234")) == hana::int_c<1 + 2 + 3 + 4>
       );
   }

5. Iterable
   Iterating over a string is equivalent to iterating over the sequence of its characters. Also note that operator[] can be used instead of the at function.

   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   
   #include <boost/hana/assert.hpp>
   #include <boost/hana/contains.hpp>
   #include <boost/hana/drop_while.hpp>
   #include <boost/hana/integral_constant.hpp>
   #include <boost/hana/is_empty.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   
   
   int main() {
       BOOST_HANA_CONSTANT_CHECK(!hana::is_empty(BOOST_HANA_STRING("abcd")));
       BOOST_HANA_CONSTANT_CHECK(hana::is_empty(BOOST_HANA_STRING("")));
   
       BOOST_HANA_CONSTANT_CHECK(BOOST_HANA_STRING("abcd")[hana::size_c<2>] == hana::char_c<'c'>);
   
       auto is_vowel = [](auto c) {
           return c ^hana::in^ BOOST_HANA_STRING("aeiouy");
       };
       BOOST_HANA_CONSTANT_CHECK(
           hana::drop_while(BOOST_HANA_STRING("aioubcd"), is_vowel) == BOOST_HANA_STRING("bcd")
       );
   }

6. Searchable
   Searching through a string is equivalent to searching through the sequence of its characters.

   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   
   #include <boost/hana/assert.hpp>
   #include <boost/hana/contains.hpp>
   #include <boost/hana/find.hpp>
   #include <boost/hana/integral_constant.hpp>
   #include <boost/hana/optional.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   
   
   int main() {
       BOOST_HANA_CONSTANT_CHECK(hana::char_c<'c'> ^hana::in^ BOOST_HANA_STRING("abcde"));
       BOOST_HANA_CONSTANT_CHECK(!(hana::char_c<'z'> ^hana::in^ BOOST_HANA_STRING("abcde")));
   
       BOOST_HANA_CONSTANT_CHECK(
           hana::find(BOOST_HANA_STRING("abcxefg"), hana::char_c<'x'>) == hana::just(hana::char_c<'x'>)
       );
   }

7. Hashable
   The hash of a compile-time string is a type uniquely representing that string.

   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   
   #include <boost/hana/assert.hpp>
   #include <boost/hana/hash.hpp>
   #include <boost/hana/not_equal.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   
   
   // `hana::hash` returns a type uniquely representing the string. The hash is
   // perfect, meaning no two different strings have the same hash value.
   BOOST_HANA_CONSTANT_CHECK(hana::not_equal(
       hana::hash(BOOST_HANA_STRING("abcdef")),
       hana::hash(BOOST_HANA_STRING("abcdefg"))
   ));
   
   int main() { }

Conversion to char const*

A hana::string can be converted to a constexpr null-delimited string of type char const* by using the c_str() method or hana::to<char const*>. This makes it easy to turn a compile-time string into a runtime string. However, note that this conversion is not an embedding, because char const* does not model the same concepts as hana::string does.

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)

#include <boost/hana/assert.hpp>
#include <boost/hana/core/to.hpp>
#include <boost/hana/string.hpp>
namespace hana = boost::hana;


constexpr auto str = hana::string_c<'h', 'i'>;

// using c_str()
constexpr char const* s1 = str.c_str();
static_assert(s1[0] == 'h' && s1[1] == 'i' && s1[2] == '\0', "");

// using hana::to
constexpr char const* s2 = hana::to<char const*>(str);
static_assert(s2[0] == 'h' && s2[1] == 'i' && s2[2] == '\0', "");

int main() { }

Conversion from any Constant holding a char const*

A hana::string can be created from any Constant whose underlying value is convertible to a char const* by using hana::to. The contents of the char const* are used to build the content of the hana::string.

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)

#include <boost/hana/assert.hpp>
#include <boost/hana/core/to.hpp>
#include <boost/hana/equal.hpp>
#include <boost/hana/integral_constant.hpp>
#include <boost/hana/string.hpp>
namespace hana = boost::hana;


constexpr char const hello[] = "hello";
auto hello_constant = hana::integral_constant<char const*, hello>{};

BOOST_HANA_CONSTANT_CHECK(
    hana::to_string(hello_constant) == hana::string_c<'h', 'e', 'l', 'l', 'o'>
);

int main() { }

Rationale for hana::string not being a Constant itself

The underlying type held by a hana::string could be either char const* or some other constexpr-enabled string-like container. In the first case, hana::string can not be a Constant because the models of several concepts would not be respected by the underlying type, causing value not to be structure-preserving. Providing an underlying value of constexpr-enabled string-like container type like std::string_view would be great, but that's a bit complicated for the time being.

Synopsis of associated functions
template<>
constexpr auto	make< string_tag >
	Create a compile-time hana::string from a parameter pack of char integral_constants. More...
constexpr auto	make_string = make<string_tag>
	Alias to make<string_tag>; provided for convenience. More...
constexpr auto	to_string = to<string_tag>
	Equivalent to to<string_tag>; provided for convenience. More...
template<char ... s>
constexpr string< implementation_defined >	string_c {}
	Create a compile-time string from a parameter pack of characters. More...
#define	BOOST_HANA_STRING(s)   see documentation
	Create a compile-time string from a string literal. More...
template<typename CharT , CharT ... s>
constexpr auto	operator""_s ()
	Creates a compile-time string from a string literal. More...

Friends
template<typename X , typename Y >
constexpr auto	operator== (X &&x, Y &&y)
	Equivalent to hana::equal
template<typename X , typename Y >
constexpr auto	operator!= (X &&x, Y &&y)
	Equivalent to hana::not_equal
template<typename X , typename Y >
constexpr auto	operator< (X &&x, Y &&y)
	Equivalent to hana::less
template<typename X , typename Y >
constexpr auto	operator> (X &&x, Y &&y)
	Equivalent to hana::greater
template<typename X , typename Y >
constexpr auto	operator<= (X &&x, Y &&y)
	Equivalent to hana::less_equal
template<typename X , typename Y >
constexpr auto	operator>= (X &&x, Y &&y)
	Equivalent to hana::greater_equal
template<typename X , typename Y >
constexpr auto	operator+ (X &&x, Y &&y)
	Performs concatenation; equivalent to hana::plus

Public Member Functions
template<typename N >
decltype(auto) constexpr	operator[] (N &&n)
	Equivalent to hana::at

Static Public Member Functions
static constexpr char const *	c_str ()
	Returns a null-delimited C-style string.

Associated functions

make< string_tag >

template<typename implementation_defined >

template<>

constexpr auto make< string_tag >

related

Initial value:

= [](auto&& ...chars) {
        return string<implementation_defined>{};
    }

Create a compile-time hana::string from a parameter pack of char integral_constants.

Given zero or more integral_constants of underlying type char, make<string_tag> creates a hana::string containing those characters. This is provided mostly for consistency with the rest of the library, as hana::string_c is more convenient to use in most cases.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)

#include <boost/hana/assert.hpp>
#include <boost/hana/equal.hpp>
#include <boost/hana/string.hpp>
#include <boost/hana/tuple.hpp>
#include <boost/hana/unpack.hpp>
namespace hana = boost::hana;


constexpr auto vowels = hana::tuple_c<char, 'a', 'e', 'i', 'o', 'u', 'y'>;
constexpr auto str = hana::unpack(vowels, hana::make<hana::string_tag>);
BOOST_HANA_CONSTANT_CHECK(str == BOOST_HANA_STRING("aeiouy"));

int main() { }

make_string

template<typename implementation_defined >

constexpr auto make_string = make<string_tag>

related

Alias to make<string_tag>; provided for convenience.

to_string

template<typename implementation_defined >

constexpr auto to_string = to<string_tag>

related

Equivalent to to<string_tag>; provided for convenience.

string_c

template<typename implementation_defined >

template<char ... s>

constexpr string<implementation_defined> string_c {}

related

Create a compile-time string from a parameter pack of characters.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)

#include <boost/hana/assert.hpp>
#include <boost/hana/core/is_a.hpp>
#include <boost/hana/string.hpp>
namespace hana = boost::hana;


constexpr auto str = hana::string_c<'a', 'b', 'c', 'd', 'e', 'f'>;
BOOST_HANA_CONSTANT_CHECK(hana::is_a<hana::string_tag>(str));

int main() { }

BOOST_HANA_STRING

template<typename implementation_defined >

#define BOOST_HANA_STRING (   s )    see documentation

related

Create a compile-time string from a string literal.

This macro is a more convenient alternative to string_c for creating compile-time strings. However, since this macro uses a lambda internally, it can't be used in an unevaluated context, or where a constant expression is expected before C++17.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)

#include <boost/hana/assert.hpp>
#include <boost/hana/config.hpp>
#include <boost/hana/core/is_a.hpp>
#include <boost/hana/equal.hpp>
#include <boost/hana/string.hpp>
namespace hana = boost::hana;


int main() {
    BOOST_HANA_CONSTEXPR_LAMBDA auto str = BOOST_HANA_STRING("abcdef");
    BOOST_HANA_CONSTANT_CHECK(str == hana::string_c<'a', 'b', 'c', 'd', 'e', 'f'>);
    BOOST_HANA_CONSTANT_CHECK(hana::is_a<hana::string_tag>(str));
}

operator""_s()

template<typename CharT , CharT ... s>

constexpr auto operator""_s ( )

related

Creates a compile-time string from a string literal.

The string literal is parsed at compile-time and the result is returned as a hana::string. This feature is an extension that is disabled by default; see below for details.

Note

Only narrow string literals are supported right now; support for fancier types of string literals like wide or UTF-XX might be added in the future if there is a demand for it. See this issue if you need this.

Warning

This user-defined literal is an extension which requires a special string literal operator that is not part of the standard yet. That operator is supported by both Clang and GCC, and several proposals were made for it to enter C++17. However, since it is not standard, it is disabled by default and defining the BOOST_HANA_CONFIG_ENABLE_STRING_UDL config macro is required to get this operator. Hence, if you want to stay safe, just use the BOOST_HANA_STRING macro instead. If you want to be fast and furious (I do), define BOOST_HANA_CONFIG_ENABLE_STRING_UDL.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)

#include <boost/hana/assert.hpp>
#include <boost/hana/config.hpp>
#include <boost/hana/core/is_a.hpp>
#include <boost/hana/equal.hpp>
#include <boost/hana/integral_constant.hpp>
#include <boost/hana/length.hpp>
#include <boost/hana/string.hpp>
namespace hana = boost::hana;
using namespace hana::literals;


// By default, this is disabled
#ifdef BOOST_HANA_CONFIG_ENABLE_STRING_UDL

    constexpr auto str = "Hello world!"_s;
    BOOST_HANA_CONSTANT_CHECK(str == hana::string_c<'H', 'e', 'l', 'l', 'o', ' ',
                                                    'w', 'o', 'r', 'l', 'd', '!'>);

    BOOST_HANA_CONSTANT_CHECK(hana::is_a<hana::string_tag>(str));
    BOOST_HANA_CONSTANT_CHECK(hana::length(str) == hana::size_c<12>);

#endif

int main() { }