/*!
@file
Forward declares `boost::hana::string`.
@copyright Louis Dionne 2013-2016
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
*/
#ifndef BOOST_HANA_FWD_STRING_HPP
#define BOOST_HANA_FWD_STRING_HPP
#include <boost/hana/config.hpp>
#include <boost/hana/fwd/core/make.hpp>
BOOST_HANA_NAMESPACE_BEGIN
#ifdef BOOST_HANA_DOXYGEN_INVOKED
//! @ingroup group-datatypes
//! Compile-time string.
//!
//! Conceptually, a `hana::string` is like a tuple holding
//! `integral_constant`s 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 `char`s. 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.
//!
//!
//! Modeled concepts
//! ----------------
//! For most purposes, a `hana::string` is functionally equivalent to a
//! tuple holding `Constant`s of underlying type `char`.
//!
//! 1. `Comparable`\n
//! Two strings are equal if and only if they have the same number of
//! characters and characters at corresponding indices are equal.
//! @include example/string/comparable.cpp
//!
//! 2. `Orderable`\n
//! The total order implemented for `Orderable` is the usual
//! lexicographical comparison of strings.
//! @include example/string/orderable.cpp
//!
//! 3. `Monoid`\n
//! Strings form a monoid under concatenation, with the neutral element
//! being the empty string.
//! @include example/string/monoid.cpp
//!
//! 4. `Foldable`\n
//! Folding a string is equivalent to folding the sequence of its
//! characters.
//! @include example/string/foldable.cpp
//!
//! 5. `Iterable`\n
//! 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.
//! @include example/string/iterable.cpp
//!
//! 6. `Searchable`\n
//! Searching through a string is equivalent to searching through the
//! sequence of its characters.
//! @include example/string/searchable.cpp
//!
//! 7. `Hashable`\n
//! The hash of a compile-time string is a type uniquely representing
//! that string.
//! @include example/string/hashable.cpp
//!
//!
//! 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.
//! @include example/string/to.cpp
//!
//!
//! > #### Rationale for `hana::string` not being a `Constant`
//! > 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.
template <typename implementation_defined>
struct string {
//! Equivalent to `hana::equal`
template <typename X, typename Y>
friend constexpr auto operator==(X&& x, Y&& y);
//! Equivalent to `hana::not_equal`
template <typename X, typename Y>
friend constexpr auto operator!=(X&& x, Y&& y);
//! Equivalent to `hana::less`
template <typename X, typename Y>
friend constexpr auto operator<(X&& x, Y&& y);
//! Equivalent to `hana::greater`
template <typename X, typename Y>
friend constexpr auto operator>(X&& x, Y&& y);
//! Equivalent to `hana::less_equal`
template <typename X, typename Y>
friend constexpr auto operator<=(X&& x, Y&& y);
//! Equivalent to `hana::greater_equal`
template <typename X, typename Y>
friend constexpr auto operator>=(X&& x, Y&& y);
//! Performs concatenation; equivalent to `hana::plus`
template <typename X, typename Y>
friend constexpr auto operator+(X&& x, Y&& y);
//! Equivalent to `hana::at`
template <typename N>
constexpr decltype(auto) operator[](N&& n);
//! Returns a null-delimited C-style string.
static constexpr char const* c_str();
};
#else
template <char ...s>
struct string;
#endif
//! Tag representing a compile-time string.
//! @relates hana::string
struct string_tag { };
#ifdef BOOST_HANA_DOXYGEN_INVOKED
//! Create a compile-time `hana::string` from a parameter pack of `char`
//! `integral_constant`s.
//! @relates hana::string
//!
//! Given zero or more `integral_constant`s 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
//! -------
//! @include example/string/make.cpp
template <>
constexpr auto make<string_tag> = [](auto&& ...chars) {
return string<implementation_defined>{};
};
#endif
//! Alias to `make<string_tag>`; provided for convenience.
//! @relates hana::string
constexpr auto make_string = make<string_tag>;
//! Create a compile-time string from a parameter pack of characters.
//! @relates hana::string
//!
//!
//! Example
//! -------
//! @include example/string/string_c.cpp
#ifdef BOOST_HANA_DOXYGEN_INVOKED
template <char ...s>
constexpr string<implementation_defined> string_c{};
#else
template <char ...s>
constexpr string<s...> string_c{};
#endif
//! Create a compile-time string from a string literal.
//! @relates hana::string
//!
//! 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.
//!
//!
//! Example
//! -------
//! @include example/string/macro.cpp
#ifdef BOOST_HANA_DOXYGEN_INVOKED
auto BOOST_HANA_STRING(s) = see documentation;
#define BOOST_HANA_STRING(s) see documentation
// Note:
// The trick above seems to exploit a bug in Doxygen, which makes the
// BOOST_HANA_STRING macro appear in the related objects of hana::string
// (as we want it to).
#else
// defined in <boost/hana/string.hpp>
#endif
#ifdef BOOST_HANA_CONFIG_ENABLE_STRING_UDL
namespace literals {
//! Creates a compile-time string from a string literal.
//! @relatesalso boost::hana::string
//!
//! 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]
//! [Hana.issue80] 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
//! -------
//! @include example/string/literal.cpp
//!
//! [Hana.issue80]: https://github.com/boostorg/hana/issues/80
template <typename CharT, CharT ...s>
constexpr auto operator"" _s();
}
#endif
BOOST_HANA_NAMESPACE_END
#endif // !BOOST_HANA_FWD_STRING_HPP