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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::ranges::advance - std::ranges::advance

Synopsis
	  Defined in header <iterator>
	  Call signature
	  template<	     std::input_or_output_iterator	   I	     >
       (1) (since C++20)
	  constexpr void advance( I& i,	std::iter_difference_t<I> n );
	  template< std::input_or_output_iterator I, std::sentinel_for<I> S
	  >
       (2) (since C++20)
	  constexpr void advance( I& i,	S bound	);
	  template< std::input_or_output_iterator I, std::sentinel_for<I> S
	  >
       (3) (since C++20)
	  constexpr std::iter_difference_t<I> advance( I& i,
	  std::iter_difference_t<I> n, S bound );

	  1) Increments	given iterator i for n times.
	  2) Increments	given iterator i until i == bound.
	  3) Increments	given iterator i for n times, or  until	 i  ==	bound,
       whichever comes
	  first.

	  If  n	is negative, the iterator is decremented. In this case,	I must
       model
	  std::bidirectional_iterator, and S must be the same  type  as	 I  if
       bound is	provided,
	  otherwise the	behavior is undefined.

	  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
	  i	- iterator to be advanced
	  bound	- sentinel denoting the	end of the range i is an iterator to
	  n	- number of maximal increments of i

Return value
	  3) The difference between n and the actual distance i	traversed.

Complexity
	  Linear.

	  However,  if I additionally models std::random_access_iterator, or S
       models
	  std::sized_sentinel_for<I>,  or  I   and   S	 model	 std::assigna-
       ble_from<I&, S>,	complexity
	  is constant.

Notes
	  The behavior is undefined if the specified sequence of increments or
       decrements
	  would	 require  that a non-incrementable iterator (such as the past-
       the-end iterator)
	  is incremented, or that a non-decrementable iterator	(such  as  the
       front iterator or
	  the singular iterator) is decremented.

Possible implementation
	  struct advance_fn {
	    template<std::input_or_output_iterator I>
	    constexpr void operator()(I& i, std::iter_difference_t<I> n) const
	    {
	      if constexpr (std::random_access_iterator<I>) {
		  i += n;
	      }
	      else {
		  while	(n > 0)	{
		      --n;
		      ++i;
		  }
		  if constexpr (std::bidirectional_iterator<I>)	{
		      while (n < 0) {
			  ++n;
			  --i;
		      }
		  }
	      }
	    }

	    template<std::input_or_output_iterator I, std::sentinel_for<I> S>
	    constexpr void operator()(I& i, S bound) const
	    {
	      if constexpr (std::assignable_from<I&, S>) {
		  i = std::move(bound);
	      }
	      else if constexpr	(std::sized_sentinel_for<S, I>)	{
		  (*this)(i, bound - i);
	      }
	      else {
		  while	(i != bound) {
		      ++i;
		  }
	      }
	    }

	    template<std::input_or_output_iterator I, std::sentinel_for<I> S>
	    constexpr std::iter_difference_t<I>
	    operator()(I& i, std::iter_difference_t<I> n, S bound) const
	    {
	      if constexpr (std::sized_sentinel_for<S, I>) {
		  // std::abs isn't constexpr until C++23
		  auto	abs = [](const std::iter_difference_t<I> x) { return x
       < 0 ? -x	: x; };

		  const	auto dist = abs(n) - abs(bound - i);
		  if (dist < 0)	{
		      (*this)(i, bound);
		      return -dist;
		  }

		  (*this)(i, n);
		  return 0;
	      }
	      else {
		  while	(n > 0 && i != bound) {
		      --n;
		      ++i;
		  }

		  if constexpr (std::bidirectional_iterator<I>)	{
		      while (n < 0 && i	!= bound) {
			  ++n;
			  --i;
		      }
		  }

		  return n;
	      }
	    }
	  };

	  inline constexpr auto	advance	= advance_fn();

Example
       // Run this code

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

	int main()
	{
	    std::vector<int> v{	3, 1, 4	};

	    auto vi = v.begin();

	    std::ranges::advance(vi, 2);
	    std::cout << "value: " << *vi << '\n';

	    {
		std::ranges::advance(vi, v.end());
		std::cout << std::boolalpha;
		std::cout << "vi == v.end(): " << (vi == v.end()) << '\n';

		std::ranges::advance(vi, -3);
		std::cout << "value: " << *vi << '\n';

		std::cout << "diff: " << std::ranges::advance(vi, 2,  v.end())
       << ", ";
		std::cout << "value: " << *vi << '\n';

		std::cout  << "diff: " << std::ranges::advance(vi, 4, v.end())
       << ", ";
		std::cout << "vi == v.end(): " << (vi == v.end()) << '\n';
		std::cout << std::noboolalpha;
	    }
	}

Output:
	value: 4
	vi == v.end(): true
	value: 3
	diff: 0, value:	4
	diff: 3, vi == v.end():	true

See also
	  ranges::next	   increment an	iterator by a given distance or	 to  a
       bound
	  (C++20)	   (niebloid)
	  ranges::prev	    decrement  an iterator by a	given distance or to a
       bound
	  (C++20)	   (niebloid)
	  ranges::distance returns the distance	between	an iterator and	a sen-
       tinel, or between
	  (C++20)	   the beginning and end of a range
			   (niebloid)
	  advance	   advances an iterator	by given distance
			   (function template)

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

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

home | help