[range.iter.op.advance]

# 24 Iterators library [[iterators]](./#iterators)

## 24.4 Iterator primitives [[iterator.primitives]](iterator.primitives#range.iter.op.advance)

### 24.4.4 Range iterator operations [[range.iter.ops]](range.iter.ops#range.iter.op.advance)

#### 24.4.4.2 ranges​::​advance [range.iter.op.advance]

[ð](#lib:advance)

`template<[input_or_output_iterator](iterator.concept.iterator#concept:input_or_output_iterator "24.3.4.6 Concept input_­or_­output_­iterator [iterator.concept.iterator]") I>
  constexpr void ranges::advance(I& i, iter_difference_t<I> n);
`

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iterators.tex#L2955)

*Preconditions*: If I does not model [bidirectional_iterator](iterator.concept.bidir#concept:bidirectional_iterator "24.3.4.12 Concept bidirectional_­iterator [iterator.concept.bidir]"),n is not negative[.](#1.sentence-1)

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iterators.tex#L2960)

*Effects*: 

- [(2.1)](#2.1)

  If I models [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_­access_­iterator [iterator.concept.random.access]"),
 equivalent to i += n[.](#2.1.sentence-1)

- [(2.2)](#2.2)

  Otherwise, if n is non-negative, increments i by n[.](#2.2.sentence-1)

- [(2.3)](#2.3)

  Otherwise, decrements i by -n[.](#2.3.sentence-1)

[ð](#lib:advance_)

`template<[input_or_output_iterator](iterator.concept.iterator#concept:input_or_output_iterator "24.3.4.6 Concept input_­or_­output_­iterator [iterator.concept.iterator]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel_for "24.3.4.7 Concept sentinel_­for [iterator.concept.sentinel]")<I> S>
  constexpr void ranges::advance(I& i, S bound);
`

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iterators.tex#L2978)

*Preconditions*: Either [assignable_from](concept.assignable#concept:assignable_from "18.4.8 Concept assignable_­from [concept.assignable]")<I&, S> || [sized_sentinel_for](iterator.concept.sizedsentinel#concept:sized_sentinel_for "24.3.4.8 Concept sized_­sentinel_­for [iterator.concept.sizedsentinel]")<S, I> is modeled, or
[i, bound) denotes a range[.](#3.sentence-1)

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iterators.tex#L2983)

*Effects*: 

- [(4.1)](#4.1)

  If I and S model [assignable_from](concept.assignable#concept:assignable_from "18.4.8 Concept assignable_­from [concept.assignable]")<I&, S>,
 equivalent to i = std​::​move(bound)[.](#4.1.sentence-1)

- [(4.2)](#4.2)

  Otherwise, if S and I model [sized_sentinel_for](iterator.concept.sizedsentinel#concept:sized_sentinel_for "24.3.4.8 Concept sized_­sentinel_­for [iterator.concept.sizedsentinel]")<S, I>,
 equivalent to ranges​::​advance(i, bound - i)[.](#4.2.sentence-1)

- [(4.3)](#4.3)

  Otherwise, while bool(i != bound) is true,
 increments i[.](#4.3.sentence-1)

[ð](#lib:advance__)

`template<[input_or_output_iterator](iterator.concept.iterator#concept:input_or_output_iterator "24.3.4.6 Concept input_­or_­output_­iterator [iterator.concept.iterator]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel_for "24.3.4.7 Concept sentinel_­for [iterator.concept.sentinel]")<I> S>
  constexpr iter_difference_t<I> ranges::advance(I& i, iter_difference_t<I> n, S bound);
`

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iterators.tex#L3002)

*Preconditions*: If n > 0, [i, bound) denotes a range[.](#5.sentence-1)

If n == 0, [i, bound) or [bound, i) denotes a range[.](#5.sentence-2)

If n < 0, [bound, i) denotes a range,I models [bidirectional_iterator](iterator.concept.bidir#concept:bidirectional_iterator "24.3.4.12 Concept bidirectional_­iterator [iterator.concept.bidir]"), andI and S model [same_as](concept.same#concept:same_as "18.4.2 Concept same_­as [concept.same]")<I, S>[.](#5.sentence-3)

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iterators.tex#L3010)

*Effects*: 

- [(6.1)](#6.1)

  If S and I model [sized_sentinel_for](iterator.concept.sizedsentinel#concept:sized_sentinel_for "24.3.4.8 Concept sized_­sentinel_­for [iterator.concept.sizedsentinel]")<S, I>:
  * [(6.1.1)](#6.1.1)

      If ​|n| â¥ |bound - i|,
 equivalent to ranges​::​advance(i, bound)[.](#6.1.1.sentence-1)

  * [(6.1.2)](#6.1.2)

      Otherwise, equivalent to ranges​::​advance(i, n)[.](#6.1.2.sentence-1)

- [(6.2)](#6.2)

  Otherwise,
  * [(6.2.1)](#6.2.1)

      if n is non-negative,
 while bool(i != bound) is true,
 increments i but at most n times[.](#6.2.1.sentence-1)

  * [(6.2.2)](#6.2.2)

      Otherwise,
 while bool(i != bound) is true,
 decrements i but at most -n times[.](#6.2.2.sentence-1)

[7](#7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iterators.tex#L3030)

*Returns*: n - M, where M is the difference between
the ending and starting positions of i[.](#7.sentence-1)
