std::distance() is a utility function in the C++ Standard Library that calculates the distance between two iterators. It works with all iterator categories and automatically uses the most efficient approach based on the iterator type.
- Computes the number of elements between two iterator positions.
- Supports input, forward, bidirectional, and random-access iterators.
#include <bits/stdc++.h>
using namespace std;
int main() {
vector<int> v = {11, 9, 12, 15, 67};
cout << distance(v.begin(), v.end());
return 0;
}
Output
5
Explanation: std::distance() calculates the number of elements between v.begin() and v.end(), which is equal to the size of the vector.
Syntax
std::distance(first, last);
Parameters
- first: Iterator pointing to the beginning of the range.
- last: Iterator pointing to the end of the range.
Return Value
Returns the number of elements between first and last.
- If first comes before last, the result is positive.
- For random-access iterators, the result can also be negative when first comes after last.
Working of std::distance()
The implementation of std::distance() depends on the iterator category:
- Input, Forward, and Bidirectional Iterators: Computes the distance by traversing the elements one by one.
- Random-Access Iterators: Computes the distance using iterator arithmetic in constant time.
Time Complexity
| Iterator Category | Time Complexity |
|---|---|
| Input Iterator | O(n) |
| Forward Iterator | O(n) |
| Bidirectional Iterator | O(n) |
| Random Access Iterator | O(1) |
Example 1: Finding Distance in a Vector
#include <iostream>
#include <vector>
using namespace std;
int main()
{
vector<int> v = {11, 9, 12, 15, 67};
auto first = v.begin();
auto last = v.begin() + 4;
cout << distance(first, last);
return 0;
}
Output
4
Explanation: The distance between the first element and the fifth element of the vector is 4.
Example 2: Finding Distance in an Array
#include <iostream>
#include <iterator>
using namespace std;
int main()
{
int arr[] = {11, 9, 12, 15, 67};
cout << distance(arr, arr + 5);
return 0;
}
Output
5
Explanation: Arrays support random-access iterators, so the distance is calculated in constant time.
Example 3: Finding Distance in a set
#include <iostream>
#include <set>
using namespace std;
int main()
{
set<int> s = {11, 9, 12, 15, 67};
auto first = s.find(9);
auto last = s.find(67);
cout << distance(first, last);
return 0;
}
Output
4
Explanation: Since set provides bidirectional iterators, std::distance() traverses the elements one by one.
Example 4: Negative Distance
#include <iostream>
#include <vector>
using namespace std;
int main()
{
vector<int> v = {11, 9, 12, 15, 67};
cout << distance(v.end(), v.begin());
return 0;
}
Output
-5
Explanation: Random-access iterators support negative distances when the first iterator comes after the second iterator.
Note: Negative distances are meaningful only for random-access iterators.
Important Restriction of std::distance()
Both iterators passed to std::distance() must belong to the same container (or valid range). Using iterators from different containers results in undefined behavior.
vector<int> v1 = {1, 2, 3};
vector<int> v2 = {4, 5, 6};
distance(v1.begin(), v2.end()); // Undefined behavior
Advantages of Using std::distance()
std::distance() provides a generic way to determine the number of elements between two iterators.
- Works with all standard iterator categories.
- Automatically uses the most efficient implementation based on iterator type.
- Improves code readability compared to manual counting.
- Useful in generic programming and STL algorithms.
Applications of std::distance()
std::distance() is commonly used in STL-based programming for:
- Finding the number of elements in a range.
- Determining the position of an iterator.
- Implementing generic algorithms.
- Working with containers that do not support indexing.
std::distance() vs std::advance()
| std::distance() | std::advance() |
|---|---|
| Computes the distance between iterators | Moves an iterator by a specified distance |
| Returns a numeric value | Modifies the iterator |
| Does not change iterators | Changes the iterator position |
| Used for measurement | Used for traversal |
