EIC code displayed by LXR master/​include/​boost/​mysql/​sequence.hpp	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-09-17 08:39:23

 //
 // Copyright (c) 2019-2025 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 //
 
 #ifndef BOOST_MYSQL_SEQUENCE_HPP
 #define BOOST_MYSQL_SEQUENCE_HPP
 
 #include <boost/mysql/detail/sequence.hpp>
 
 #ifdef BOOST_MYSQL_HAS_CONCEPTS
 #include <concepts>
 #endif
 
 namespace boost {
 namespace mysql {
 
 /**
  * \brief The return type of \ref sequence.
  * \details
  * Contains a range, a formatter function, and a glue string.
  * This type satisfies the `Formattable` concept.
  *
  * When formatted, \ref format_function is invoked for each element
  * in \ref range. The string \ref glue is output raw (as per \ref format_context_base::append_raw)
  * between consecutive invocations of the formatter function, generating an effect
  * similar to `std::ranges::views::join`.
  *
  * Don't instantiate this struct directly - use \ref sequence, instead.
  *
  * \par Type requirements
  *
  *   - Expressions `std::begin(range)` and `std::end(range)` should return an input iterator/sentinel
  *     pair that can be compared for (in)equality.
  *   - The expression `static_cast<const FormatFn&>(fn)(* std::begin(range), ctx)`
  *     should be well formed, with `ctx` begin a `format_context_base&`.
  */
 template <class Range, class FormatFn>
 #if defined(BOOST_MYSQL_HAS_CONCEPTS)
     requires detail::format_fn_for_range<FormatFn, Range>
 #endif
 struct format_sequence
 {
     /// The range to format.
     Range range;
 
     /// The format function to apply to each element in the range.
     FormatFn format_function;
 
     /// The string to output between range elements.
     constant_string_view glue;
 };
 
 /**
  * \brief The type of range produced by \ref sequence.
  * \details
  * This type trait can be used to obtain the range type produced
  * by calling \ref sequence. This type is used as the `Range` template
  * parameter in \ref format_sequence.
  *
  * By default, \ref sequence copies its input range, unless
  * using `std::ref`. C arrays are copied into `std::array` objects.
  * This type trait accounts these transformations.
  *
  * Formally, given the input range type `T` (which can be a reference with cv-qualifiers):
  *
  *  - If `T` is a C array or a reference to one (as per `std::is_array`),
  *    and the array elements' type is `U`, yields `std::array<std::remove_cv_t<U>, N>`.
  *  - If `T` is a `std::reference_wrapper<U>` object, or a reference to one,
  *    yields `U&`.
  *  - Otherwise, yields `std::remove_cvref_t<T>`.
  *
  * Examples:
  *
  *  - `sequence_range_t<const std::vector<int>&>` is `std::vector<int>`.
  *  - `sequence_range_t<std::reference_wrapper<std::vector<int>>>` is `std::vector<int>&`.
  *  - `sequence_range_t<std::reference_wrapper<const std::vector<int>>>` is `const std::vector<int>&`.
  *  - `sequence_range_t<int(&)[4]>` is `std::array<int, 4>`.
  */
 template <class T>
 using sequence_range_t =
 #ifdef BOOST_MYSQL_DOXYGEN
     __see_below__
 #else
     typename detail::sequence_range_type<T>::type;
 #endif
     ;
 
 /**
  * \brief Creates an object that, when formatted, applies a per-element function to a range.
  * \details
  * Objects returned by this function satisfy `Formattable`.
  * Formatting such objects invokes `fn` for each element
  * in `range`, outputting `glue` between invocations.
  * This generates an effect similar to `std::ranges::views::join`.
  *
  * By default, this function creates an owning object by decay-copying `range` into it.
  * C arrays are copied into `std::array` objects. This behavior can be disabled
  * by passing `std::reference_wrapper` objects, which are converted to references
  * (as `std::make_tuple` does). The \ref sequence_range_t
  * type trait accounts for these transformations.
  *
  * Formally:
  *
  *   - If `Range` is a (possibly cv-qualified) C array reference (as per `std::is_array<Range>`),
  *     and the array has `N` elements of type `U`, the output range type is
  *     `std::array<std::remove_cv< U >, N>`, and the range is created as if `std::to_array` was called.
  *   - If `Range` is a `std::reference_wrapper< U >` object, or a reference to one,
  *     the output range type is `U&`. This effectively disables copying the input range.
  *     The resulting object will be a view type, and the caller is responsible for lifetime management.
  *   - Otherwise, the output range type is `std::remove_cvref_t<Range>`, and it will be
  *     created by forwarding the passed `range`.
  *
  * `FormatFn` is always decay-copied into the resulting object.
  *
  * The glue string is always stored as a view, as it should usually point to a compile-time constant.
  *
  * \par Type requirements
  *
  * The resulting range and format function should be compatible, and any required
  * copy/move operations should be well defined. Formally:
  *
  *   - `std::decay_t<FormatFn>` should be a formatter function compatible with
  *     the elements of the output range. See \ref format_sequence for the formal requirements.
  *   - If `Range` is a `std::reference_wrapper< U >`, or a reference to one,
  *     no further requirements are placed on `U`.
  *   - If `Range` is a lvalue reference to a C array, its elements should be copy-constructible
  *     (as per `std::to_array` requirements).
  *   - If `Range` is a rvalue reference to a C array, its elements should be move-constructible
  *     (as per `std::to_array` requirements).
  *   - Performing a decay-copy of `FormatFn` should be well defined.
  *
  * \par Exception safety
  * Basic guarantee. Propagates any exception thrown when constructing the output
  * range and format function.
  */
 template <class Range, class FormatFn>
 #if defined(BOOST_MYSQL_HAS_CONCEPTS)
     requires std::constructible_from<typename std::decay<FormatFn>::type, FormatFn&&>
 #endif
 format_sequence<sequence_range_t<Range>, typename std::decay<FormatFn>::type> sequence(
     Range&& range,
     FormatFn&& fn,
     constant_string_view glue = ", "
 )
 
 {
     return {detail::cast_range(std::forward<Range>(range)), std::forward<FormatFn>(fn), glue};
 }
 
 template <class Range, class FormatFn>
 struct formatter<format_sequence<Range, FormatFn>>
 {
     const char* parse(const char* begin, const char*) { return begin; }
 
     void format(format_sequence<Range, FormatFn>& value, format_context_base& ctx) const
     {
         detail::do_format_sequence(value.range, value.format_function, value.glue, ctx);
     }
 
     void format(const format_sequence<Range, FormatFn>& value, format_context_base& ctx) const
     {
         detail::do_format_sequence(value.range, value.format_function, value.glue, ctx);
     }
 };
 
 }  // namespace mysql
 }  // namespace boost
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team