home | help 
std::ranges::cdata(3)	       C++ Standard Libary	   std::ranges::cdata(3)

NAME
     std::ranges::cdata - std::ranges::cdata

Synopsis
	Defined in header <ranges>
	Defined in header <iterator>
	inline namespace /*unspecified*/ {

	    inline constexpr /*unspecified*/ cdata =		(since C++20)
	/*unspecified*/;					  (customization
     point object)

	}
	Call signature
	template< class T >

	    requires /* see below */				(since C++20)

	constexpr /* see below */ cdata( T&& t );

	Returns a pointer to the first element
	of constant type
	(since C++23) of a contiguous range denoted by a
	const-qualified
	(until C++23) argument.

	Let CT be

	  * const std::remove_reference_t<T>& if the argument is an lvalue (i.e.
     T is
	    an lvalue reference type),
	  *		    const		   T		      otherwise.
     (until
										      C++23)
	A call to ranges::cdata is expression-equivalent to
	ranges::data(static_cast<CT&&>(t)).

	The return type is equivalent to
	std::remove_reference_t<ranges::range_reference_t<CT>>*.

	If the argument is an lvalue or
	ranges::enable_borrowed_range<std::remove_cv_t<T>>  is true, then a call
     to
	ranges::cdata is expression-equivalent to:

	  * /*as-const-pointer*/(ranges::data(/*possibly-const-range*/(t))).
										      (since
	The	    return	   type 	is	   equivalent	      to
     C++23)
	std::remove_reference_t<ranges::range_const_reference_t<T>>*.

	In all other cases, a call to ranges::cdata is ill-formed, which can re-
     sult
	in  substitution  failure when the call appears in the immediate context
     of a
	template instantiation.

	If ranges::cdata(t) is valid, then it returns a pointer to an object
	of constant type
	(since C++23).

       Customization point objects

	The name ranges::cdata denotes a customization point object, which is  a
     const
	function object of a literal semiregular class type. For exposition pur-
     poses, the
	cv-unqualified version of its type is denoted as __cdata_fn.

	All instances of __cdata_fn are equal. The effects of invoking different
     instances
	of  type  __cdata_fn on the same arguments are equivalent, regardless of
     whether the
	expression denoting the instance is an lvalue or rvalue, and  is  const-
     qualified or
	not  (however, a volatile-qualified instance is not required to be invo-
     cable). Thus,
	ranges::cdata can be copied freely and its copies  can	be  used  inter-
     changeably.

	Given  a  set  of types Args..., if std::declval<Args>()... meet the re-
     quirements for
	arguments to ranges::cdata above, __cdata_fn models

	  * std::invocable<__cdata_fn, Args...>,
	  * std::invocable<const __cdata_fn, Args...>,
	  * std::invocable<__cdata_fn&, Args...>, and
	  * std::invocable<const __cdata_fn&, Args...>.

	Otherwise, no function call operator of __cdata_fn participates in over-
     load
	resolution.

Example
     // Run this code

      #include <cstring>
      #include <iostream>
      #include <ranges>
      #include <string>

      int main()
      {
	  std::string src {"hello world!\n"};

      //  std::ranges::cdata(src)[0] = 'H'; // error, src.data() is  treated  as
     read-only
	  std::ranges::data(src)[0]  =	'H';  //  OK,  src.data() is a non-const
     storage

	  char dst[20]; // storage for a C-style string
	  std::strcpy(dst, std::ranges::cdata(src));
	  // [data(src), data(src) + size(src)] is guaranteed to be an NTBS

	  std::cout << dst;
      }

Output:
      Hello world!

See also
	ranges::data obtains a pointer to the beginning of a contiguous range
	(C++20)      (customization point object)
	data	     obtains the pointer to the underlying array
	(C++17)      (function template)

http://cppreference.com 	   2024.06.10		   std::ranges::cdata(3)
home | help