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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::ranges::distance - std::ranges::distance

Synopsis
	  Defined in header <iterator>
	  Call signature
	  template< std::input_or_output_iterator I, std::sentinel_for<I> S
	  >
									     (1)
       (since C++20)
	  requires (!std::sized_sentinel_for<S,	I>)

	  constexpr std::iter_difference_t<I> distance(	I first, S last	);
	  template< std::input_or_output_iterator I,
	  std::sized_sentinel_for<I>			S		     >
       (2) (since C++20)
	  constexpr std::iter_difference_t<I> distance(	const I& first,
	  const	S& last	);
	  template<		 ranges::range		     R		     >
       (3) (since C++20)
	  constexpr ranges::range_difference_t<R> distance( R&&	r );

	  1,2) Returns the number of hops from first to	last.
	  3) Returns the size of r as a	signed integer.

	  The  function-like  entities	described  on this page	are niebloids,
       that is:

	    * Explicit template	argument lists may not be specified when call-
       ing any of them.
	    * None of them is visible to argument-dependent lookup.
	    * When one of them is found	by normal unqualified lookup  for  the
       name to the left
	      of  the  function-call  operator,	it inhibits argument-dependent
       lookup.

	  In practice, they may	be implemented as function  objects,  or  with
       special compiler
	  extensions.

Parameters
	  first	- iterator pointing to the first element
	  last	 - sentinel denoting the end of	the range first	is an iterator
       to
	  r	- range	to calculate the distance of

Return value
	  1) The number	of increments needed to	go from	first to last.
	  2) last - first.
	  3) If	R models ranges::sized_range, returns ranges::size(r);	other-
       wise
	  ranges::distance(ranges::begin(r), ranges::end(r)).

Complexity
	  1) Linear.
	  2) Constant.
	  2) If	R models ranges::sized_range or	if
	  std::sized_sentinel_for<ranges::sentinel_t<R>,	ranges::itera-
       tor_t<R>> is modeled,
	  complexity is	constant; otherwise linear.

Possible implementation
	  struct distance_fn {
	    template<std::input_or_output_iterator I, std::sentinel_for<I> S>
	      requires (!std::sized_sentinel_for<S, I>)
	    constexpr std::iter_difference_t<I>	operator()(I  first,  S	 last)
       const
	    {
	      std::iter_difference_t<I>	result = 0;
	      while (first != last) {
		  ++first;
		  ++result;
	      }
	      return result;
	    }

	    template<std::input_or_output_iterator	I,     std::sized_sen-
       tinel_for<I> S>
	    constexpr  std::iter_difference_t<I>  operator()(const  I&	first,
       const S&	last) const
	    {
	      return last - first;
	    }

	    template<ranges::range R>
	    constexpr ranges::range_difference_t<R> operator()(R&& r) const
	    {
	      if constexpr (ranges::sized_range<std::remove_cvref_t<R>>) {
		return			     static_cast<ranges::range_differ-
       ence_t<R>>(ranges::size(r));
	      }
	      else {
		return (*this)(ranges::begin(r), ranges::end(r));
	      }
	    }
	  };

	  inline constexpr auto	distance = distance_fn{};

Example
       // Run this code

	#include <iostream>
	#include <iterator>
	#include <vector>

	int main()
	{
	    std::vector<int> v{	3, 1, 4	};
	    namespace ranges = std::ranges;
	    std::cout << "distance(first, last)	= "
		      << ranges::distance(v.begin(), v.end()) << '\n'
		      << "distance(last, first)	= "
		      << ranges::distance(v.end(), v.begin()) << '\n'
		      << "distance(v) =	" << ranges::distance(v) << '\n';
	}

Output:
	distance(first,	last) =	3
	distance(last, first) =	-3
	distance(v) = 3

	 Defect	reports

	  The following	behavior-changing defect reports were applied retroac-
       tively to
	  previously published C++ standards.

	     DR	      Applied	 to		 Behavior     as     published
       Correct behavior
			      distance	takes  iterator	 by value, thus	    by
       reference overload
	  LWG 3392 C++20      rejecting	move-only iterator lvalue with a added
			      sized sentinel

See also
	  ranges::advance  advances an iterator	by  given  distance  or	 to  a
       given bound
	  (C++20)	   (niebloid)
	  ranges::count
	  ranges::count_if  returns the	number of elements satisfying specific
       criteria
	  (C++20)	   (niebloid)
	  (C++20)
	  distance	   returns the distance	between	two iterators
			   (function template)

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

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

home | help