checked_array_iterator Class

  • Article

The checked_array_iterator class allows you to transform an array or pointer into a checked iterator.

Note

This class is a Microsoft extension to the Standard C++ Library. Code implemented using this algorithm will not be portable. For an example demonstrating how to write code that does not require the use of this class, see the second example below.

template <class _Iterator>
    class checked_array_iterator
        : public iterator<
            typename iterator_traits<_Iterator>::iterator_category, 
            typename iterator_traits<_Iterator>::value_type, 
            typename iterator_traits<_Iterator>::difference_type, 
            typename iterator_traits<_Iterator>::pointer, 
            typename iterator_traits<_Iterator>::reference>

Remarks

This class is defined in the stdext namespace.

For more information on the checked iterator feature, see Checked Iterators.

Example

The following sample shows how to define and use a checked array iterator.

If the destination is not large enough to hold all the elements being copied, such as would be the case if you changed the line:

copy(a, a + 5, checked_array_iterator<int*>(b, 5));

to

copy(a, a + 5, checked_array_iterator<int*>(b, 4));

A runtime error will occur.

// checked_array_iterator_overview.cpp
// compile with: /EHsc
#include <algorithm>
#include <iostream>

using namespace std;
using namespace stdext;

int main() {
   int a[]={0, 1, 2, 3, 4};
   int b[5];
   copy(a, a + 5, checked_array_iterator<int*>(b, 5));

   cout << "(";
   for (int i = 0 ; i < 5 ; i++)
      cout << " " << b[i];
   cout << " )" << endl;

   // constructor example
   checked_array_iterator<int*> checked_out_iter(b, 5);
   copy(a, a + 5, checked_out_iter);

   cout << "(";
   for (int i = 0 ; i < 5 ; i++)
      cout << " " << b[i];
   cout << " )" << endl;
}

( 0 1 2 3 4 )
( 0 1 2 3 4 )

To avoid the need for the checked_array_iterator class when using Standard C++ Library algorithms, consider using a vector instead of a dynamically allocated array. The following example demonstrates how to do this.

// checked_array_iterator_2.cpp
// compile with: /EHsc

#include <algorithm>
#include <iostream>
#include <vector>

using namespace std;

int main()
{
    std::vector<int> v(10);
    int *arr = new int[10];
    for (int i = 0; i < 10; ++i)
    {
        v[i] = i;
        arr[i] = i;
    }

    // std::copy(v.begin(), v.end(), arr); will result in
    // warning C4996. To avoid this warning while using int *,
    // use the Microsoft extension checked_array_iterator.
    std::copy(v.begin(), v.end(),
              stdext::checked_array_iterator<int *>(arr, 10));

    // Instead of using stdext::checked_array_iterator and int *,
    // consider using std::vector to encapsulate the array. This will
    // result in no warnings, and the code will be portable.
    std::vector<int> arr2(10);    // Similar to int *arr = new int[10];
    std::copy(v.begin(), v.end(), arr2.begin());

    for (int j = 0; j < arr2.size(); ++j)
    {
        cout << " " << arr2[j];
    }
    cout << endl;

    return 0;
}

 0 1 2 3 4 5 6 7 8 9

Constructors

checked_array_iterator

Constructs a default checked_array_iterator or a checked_array_iterator from an underlying iterator.

Typedefs

difference_type

A type that provides the difference between two checked_array_iterators referring to elements within the same container.

pointer

A type that provides a pointer to an element addressed by a checked_array_iterator.

reference

A type that provides a reference to an element addressed by a checked_array_iterator.

Member Functions

base

Recovers the underlying iterator from its checked_array_iterator.

Operators

operator==

Tests two checked_array_iterators for equality.

operator!=

Tests two checked_array_iterators for inequality.

operator<

Tests if the checked_array_iterator on the left side of the operator is less than the checked_array_iterator on the right side.

operator>

Tests if the checked_array_iterator on the left side of the operator is greater than the checked_array_iterator on the right side.

operator<=

Tests if the checked_array_iterator on the left side of the operator is less than or equal to the checked_array_iterator on the right side.

operator>=

Tests if the checked_array_iterator on the left side of the operator is greater than or equal to the checked_array_iterator on the right side.

operator*

Returns the element that a checked_array_iterator addresses.

operator->

Returns a pointer to the element addressed by the checked_array_iterator.

operator++

Increments the checked_array_iterator to the next element.

operator--

Decrements the checked_array_iterator to the previous element.

operator+=

Adds a specified offset to a checked_array_iterator.

operator+

Adds an offset to an iterator and returns the new checked_array_iterator addressing the inserted element at the new offset position.

operator-=

Decrements a specified offset from a checked_array_iterator.

operator-

Decrements an offset from an iterator and returns the new checked_array_iterator addressing the inserted element at the new offset position.

operator[]

Returns a reference to an element offset from the element addressed by a checked_array_iterator by a specified number of positions.

Requirements

Header: <iterator>

Namespace: stdext

See Also

Reference

Standard Template Library

Other Resources

<iterator> Members

checked_array_iterator Members