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

NAME
     std::iota - std::iota

Synopsis
	Defined in header <numeric>
	template< class ForwardIt, class T >			(since C++11)
	void iota( ForwardIt first, ForwardIt last, T value );	(constexpr since
     C++20)

	Fills  the  range  [first,  last)  with  sequentially increasing values,
     starting with
	value and repetitively evaluating ++value.

	Equivalent operation (assuming ++value returns the incremented value):

      *first   = value;
      *++first = ++value;
      *++first = ++value;
      *++first = ++value;
      // repeats until alasta is reached

	If any of the following conditions is satisfied,  the  program	is  ill-
     formed:

	  * T is not convertible to the value type of ForwardIt.
	  *  The expression ++val is ill-formed, where val is a variable of type
     T.

Parameters
	first, last - the range of elements to fill with sequentially increasing
     values
		      starting with value
	value	    - initial value to store

Complexity
	Exactly std::distance(first, last) increments and assignments.

Possible implementation
	template<class ForwardIt, class T>
	constexpr // since C++20
	void iota(ForwardIt first, ForwardIt last, T value)
	{
	    for (; first != last; ++first, ++value)
		*first = value;
	}

Notes
	The function is named after the integer function a^3 from  the	program-
     ming language
	APL.  It  was one of the STL components that were not included in C++98,
     but made it
	into the standard library in C++11.

Example
	The following example applies std::shuffle to a  vector  of  std::lists'
     iterators.
	std::iota is used to populate containers.

     // Run this code

      #include <algorithm>
      #include <iomanip>
      #include <iostream>
      #include <list>
      #include <numeric>
      #include <random>
      #include <vector>

      class BigData // inefficient to copy
      {
	  int data[1024]; /* some raw data */
      public:
	  explicit BigData(int i = 0) { data[0] = i; /* ... */ }
	  operator int() const { return data[0]; }
	  BigData& operator=(int i) { data[0] = i; return *this; }
	  /* ... */
      };

      int main()
      {
	  std::list<BigData> l(10);
	  std::iota(l.begin(), l.end(), -4);

	  std::vector<std::list<BigData>::iterator> v(l.size());
	  std::iota(v.begin(), v.end(), l.begin());
	  //  Vector  of iterators (to original data) is used to avoid expensive
     copying,
	  // and because std::shuffle (below) cannot be applied to  a  std::list
     directly.

	  std::shuffle(v.begin(),      v.end(),     std::mt19937{std::random_de-
     vice{}()});

	  std::cout << "Original contents of the list l:\t";
	  for (const auto& n : l)
	      std::cout << std::setw(2) << n << ' ';
	  std::cout << '\n';

	  std::cout << "Contents of l, viewed via shuffled v:\t";
	  for (const auto i : v)
	      std::cout << std::setw(2) << *i << ' ';
	  std::cout << '\n';
      }

Possible output:
      Original contents of the list l:	      -4 -3 -2 -1  0  1  2  3  4  5
      Contents of l, viewed via shuffled v:   -1  5 -4	0  2  1  4 -2  3 -3

See also
	ranges::iota_view a view consisting of a sequence generated  by  repeat-
     edly
	views::iota	  incrementing an initial value
	(C++20) 	  (class template) (customization point object)
	fill		   copy-assigns  the  given  value to every element in a
     range
			  (function template)
	ranges::fill	  assigns a range of elements a certain value
	(C++20) 	  (niebloid)
			  assigns the results of successive  function  calls  to
     every element
	generate	  in a range
			  (function template)
	ranges::generate  saves the result of a function in a range
	(C++20) 	  (niebloid)
	ranges::iota	  fills a range with successive increments of the start-
     ing value
	(C++23) 	  (niebloid)

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