/*! @file Forward declares `boost::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) */ #ifndef BOOST_HANA_FWD_STRING_HPP #define BOOST_HANA_FWD_STRING_HPP #include #include #include 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`, as documented below. More //! details [in the tutorial](@ref tutorial-containers-types). //! //! //! 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`. 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 //! //! 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`. //! @include example/string/from_c_str.cpp //! //! 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. template struct string { // Default-construct a `hana::string`; no-op since `hana::string` is stateless. constexpr string() = default; // Copy-construct a `hana::string`; no-op since `hana::string` is stateless. constexpr string(string const&) = default; //! Equivalent to `hana::equal` template friend constexpr auto operator==(X&& x, Y&& y); //! Equivalent to `hana::not_equal` template friend constexpr auto operator!=(X&& x, Y&& y); //! Equivalent to `hana::less` template friend constexpr auto operator<(X&& x, Y&& y); //! Equivalent to `hana::greater` template friend constexpr auto operator>(X&& x, Y&& y); //! Equivalent to `hana::less_equal` template friend constexpr auto operator<=(X&& x, Y&& y); //! Equivalent to `hana::greater_equal` template friend constexpr auto operator>=(X&& x, Y&& y); //! Performs concatenation; equivalent to `hana::plus` template friend constexpr auto operator+(X&& x, Y&& y); //! Equivalent to `hana::at` template constexpr decltype(auto) operator[](N&& n); //! Returns a null-delimited C-style string. static constexpr char const* c_str(); }; #else template 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` 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 = [](auto&& ...chars) { return string{}; }; #endif //! Alias to `make`; provided for convenience. //! @relates hana::string constexpr auto make_string = make; //! Equivalent to `to`; provided for convenience. //! @relates hana::string constexpr auto to_string = to; //! 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 constexpr string string_c{}; #else template constexpr string 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, or where //! a constant expression is expected before C++17. //! //! //! 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 #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 constexpr auto operator"" _s(); } #endif BOOST_HANA_NAMESPACE_END #endif // !BOOST_HANA_FWD_STRING_HPP