Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

NAME
       std::ranges::empty - std::ranges::empty

Synopsis
	  Defined in header <ranges>
	  inline namespace /*unspecified*/ {
							  (since C++20)
	  inline constexpr auto	empty =	/*unspecified*/;  (customization point
       object)

	  }
	  Call signature
	  template< class T >

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

	  constexpr bool empty(	T&& t );

	  Determines whether or	not t has any elements.

	  A call to ranges::empty is expression-equivalent to:

	   1. bool(t.empty()), if that expression is valid.
	   2. Otherwise, (ranges::size(t) == 0), if that expression is valid.
	   3. Otherwise, bool(ranges::begin(t) == ranges::end(t)), if that ex-
       pression	is valid
	      and decltype(ranges::begin(t)) models std::forward_iterator.

	  In all other cases, a	call to	ranges::empty is ill-formed, which can
       result in
	  substitution	failure	when ranges::empty(t) appears in the immediate
       context of a
	  template instantiation.

	 Expression-equivalent

	  Expression e is expression-equivalent	to expression f, if

	    * e	and f have the same effects, and
	    * either both are constant subexpressions or  else	neither	 is  a
       constant
	      subexpression, and
	    *  either  both are	potentially-throwing or	else neither is	poten-
       tially-throwing
	      (i.e. noexcept(e)	== noexcept(f)).

	 Customization point objects

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

	  All instances	of __empty_fn are equal. The effects of	invoking  dif-
       ferent instances
	  of  type __empty_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
       invocable). Thus,
	  ranges::empty	can be copied freely and its copies can	be used	inter-
       changeably.

	  Given	a set of types Args...,	if  std::declval<Args>()...  meet  the
       requirements for
	  arguments to ranges::empty above, __empty_fn models

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

	  Otherwise,  no  function call	operator of __empty_fn participates in
       overload
	  resolution.

Example
       // Run this code

	#include <iostream>
	#include <ranges>
	#include <vector>

	template <std::ranges::input_range R>
	void print(char	id, R&&	r)
	{
	    if (std::ranges::empty(r)) {
		std::cout << '\t' << id	<< ") Empty\n";
		return;
	    }

	    std::cout << '\t' << id << ") Elements:";
	    for	(const auto& element : r) {
		std::cout << ' ' << element;
	    }

	    std::cout << '\n';
	}

	int main()
	{
	    {
		auto v = std::vector<int>{1, 2,	3};
		std::cout << "(1) ranges::empty	uses std::vector::empty:\n";
		print('a', v);

		v.clear();
		print('b', v);
	    }
	    {
		std::cout <<  "(2)  ranges::empty  uses	 ranges::size(initial-
       izer_list):\n";
		auto il	= {7, 8, 9};
		print('a', il);

		print('b', std::initializer_list<int>{});
	    }
	    {
		std::cout   <<	 "(2)	ranges::empty  on  a  raw  array  uses
       ranges::size:\n";
		int array[] = {4, 5, 6}; // array has a	known bound
		print('a', array);
	    }
	    {
		struct Scanty :	private	std::vector<int> {
		    using std::vector<int>::begin;
		    using std::vector<int>::end;
		    using std::vector<int>::push_back;
		    // Note: both empty() and size() are hidden
		};

		std::cout << "(3)  calling  ranges::empty  on  an  object  w/o
       empty() or size():\n";
		Scanty y;
		print('a', y);
		y.push_back(42);
		print('b', y);
	    }
	}

Output:
	(1) ranges::empty uses std::vector::empty:
		a) Elements: 1 2 3
		b) Empty
	(2) ranges::empty uses ranges::size(initializer_list):
		a) Elements: 7 8 9
		b) Empty
	(2) ranges::empty on a raw array uses ranges::size:
		a) Elements: 4 5 6
	(3) calling ranges::empty on an	object w/o empty() or size():
		a) Empty
		b) Elements: 42

See also
	  empty	  checks whether the container is empty
	  (C++17) (function template)

http://cppreference.com		  2022.07.31		 std::ranges::empty(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::ranges::empty&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help