GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing cplusplus.com — std::begin

Reference

C library:
- <cassert> (assert.h)
- <cctype> (ctype.h)
- <cerrno> (errno.h)
- C++11
  <cfenv> (fenv.h)
- <cfloat> (float.h)
- C++11
  <cinttypes> (inttypes.h)
- <ciso646> (iso646.h)
- <climits> (limits.h)
- <clocale> (locale.h)
- <cmath> (math.h)
- <csetjmp> (setjmp.h)
- <csignal> (signal.h)
- <cstdarg> (stdarg.h)
- C++11
  <cstdbool> (stdbool.h)
- <cstddef> (stddef.h)
- C++11
  <cstdint> (stdint.h)
- <cstdio> (stdio.h)
- <cstdlib> (stdlib.h)
- <cstring> (string.h)
- C++11
  <ctgmath> (tgmath.h)
- <ctime> (time.h)
- C++11
  <cuchar> (uchar.h)
- <cwchar> (wchar.h)
- <cwctype> (wctype.h)
Containers:
- C++11
  <array>
- <deque>
- C++11
  <forward_list>
- <list>
- <map>
- <queue>
- <set>
- <stack>
- C++11
  <unordered_map>
- C++11
  <unordered_set>
- <vector>
Input/Output:
- <fstream>
- <iomanip>
- <ios>
- <iosfwd>
- <iostream>
- <istream>
- <ostream>
- <sstream>
- <streambuf>
Multi-threading:
- C++11
  <atomic>
- C++11
  <condition_variable>
- C++11
  <future>
- C++11
  <mutex>
- C++11
  <thread>
Other:
- <algorithm>
- <bitset>
- C++11
  <chrono>
- C++11
  <codecvt>
- <complex>
- <exception>
- <functional>
- C++11
  <initializer_list>
- <iterator>
- <limits>
- <locale>
- <memory>
- <new>
- <numeric>
- C++11
  <random>
- C++11
  <ratio>
- C++11
  <regex>
- <stdexcept>
- <string>
- C++11
  <system_error>
- C++11
  <tuple>
- C++11
  <type_traits>
- C++11
  <typeindex>
- <typeinfo>
- <utility>
- <valarray>

<iterator>

iterator
iterator_traits
functions
- advance
- back_inserter
- C++11
  begin
- distance
- C++11
  end
- front_inserter
- inserter
- C++11
  make_move_iterator
- C++11
  next
- C++11
  prev
iterator categories
predefined iterators

function template

std::begin

container (1)

template <class Container>  auto begin (Container& cont) -> decltype (cont.begin());template <class Container>  auto begin (const Container& cont) -> decltype (cont.begin());

array (2)

template <class T, size_t N>  T* begin (T(&arr)[N]);

container (1)

template <class Container>  auto begin (Container& cont) -> decltype (cont.begin());template <class Container>  auto begin (const Container& cont) -> decltype (cont.begin());

array (2)

template <class T, size_t N>  constexpr T* begin (T(&arr)[N]) noexcept;

Iterator to beginning

Returns an iterator pointing to the first element in the sequence:

(1) Container: The function returns cont.begin().
(2) Array: The function returns the array-to-pointer conversion of its argument.

If the sequence is empty, the returned value shall not be dereferenced.

These function templates are defined in multiple headers: Each of these headers includes the generic templates for all container and array types and not simply a specific overload. The headers are: <iterator>, <array>, <deque>, <forward_list>, <list>, map, <regex>, <set>, <string>, <unordered_map>, <unordered_set> and <vector>.

Conversely, begin is overloaded (with a different definition) in headers <initializer_list> and <valarray>.

Parameters

cont: An object of a class type for which member begin is defined.
arr: An array.

Return Value

For (1), the same as returned by cont.begin().
For (2), a pointer to the first element in the array.

Example

// std::begin / std::end example
#include <iostream>     // std::cout
#include <vector>       // std::vector, std::begin, std::end

int main () {
  int foo[] = {10,20,30,40,50};
  std::vector<int> bar;

  // iterate foo: inserting into bar
  for (auto it = std::begin(foo); it!=std::end(foo); ++it)
    bar.push_back(*it);

  // iterate bar: print contents:
  std::cout << "bar contains:";
  for (auto it = std::begin(bar); it!=std::end(bar); ++it)
    std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}

Output:

bar contains: 10 20 30 40 50

Data races

The argument is accessed but not modified.
None of the elements in the sequence are accessed by the call, but the iterator returned can be used to access or modify them.

Exception safety

Provides the same level of guarantees as the operation performed on the argument (for standard containers and arrays this is a no-throw guarantee).

functions

iterator categories