HP C++ User Documentation

 

vector (3C++std) - Tru64 UNIX

Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.

NAME

  vector  - Sequence that supports random access iterators.

  This page describes the ANSI vector class.  If you would like information
  on the pre-ANSI vector class, use the command:

       man 3C++ vector or man vector.3C++

SYNOPSIS

  #include <vector>

  template <class T, class Allocator = allocator<T> >
  class vector ;

DESCRIPTION

  vector<T, Allocator> is a type of sequence that supports random access
  iterators.  In addition, it supports amortized constant time insert and
  erase operations at the end.  Insert and erase in the middle take linear
  time.  Storage management is handled automatically.  In vector, iterator is
  a random access iterator referring to T.  const_iterator is a constant
  random access iterator that returns a const T& when being dereferenced.  A
  constructor for iterator and const_iterator is guaranteed.  size_type is an
  unsigned integral type.  difference_type is a signed integral type.

  Any type used for the template parameter T must provide  the following
  (where T is the type, t is a value of T and u is a const value of T):

  Default constructor   T()
   Copy constructors     T(t) and T(u)
   Destructor            t.~T()
   Address of            &t and &u yielding T* and
                          const T* respectively
   Assignment            t = a where a is a
                          (possibly const) value of T

SPECIAL CASE

  Vectors of bit values (boolean 1/0 values) are handled as a special case by
  the standard library, so that they can be efficiently packed several
  elements to a word.  The operations for a boolean vector, vector<bool>, are
  a superset of those for an ordinary vector, only the implementation is more
  efficient.

  Two member functions are available to the boolean vector data type.  One
  is flip(), which inverts all the bits of the vector.  Boolean vectors also
  return as reference an internal value that also supports the flip() member
  function.  The other vector<bool>-specific member function is a second form
  of the swap() function

INTERFACE

  template <class T, class Allocator = allocator<T> >
  class vector {

  public:

   // Types

    typedef T value_type;
    typedef Allocator allocator_type;
    typename reference;
    typename const_reference;
    typename iterator;
    typename const_iterator;
    typename size_type;
    typename difference_type;
    typename reverse_iterator;
    typename const_reverse_iterator;

   // Construct/Copy/Destroy

    explicit vector (const Allocator& = Allocator());
    explicit vector (size_type, const Allocator& = Allocator ());
    vector (size_type, const T&, const Allocator& = Allocator());
    vector (const vector<T, Allocator>&);
    template <class InputIterator>
     vector (InputIterator, InputIterator,
             const Allocator& = Allocator ());
     ~vector ();
    vector<T,Allocator>& operator= (const vector<T, Allocator>&);
    template <class InputIterator>
     void assign (InputIterator first, InputIterator last);
    template <class Size, class TT>
     void assign (Size n);
    template <class Size, class TT>
     void assign (Size n, const TT&);
    allocator_type get_allocator () const;

   // Iterators

    iterator begin ();
    const_iterator begin () const;
    iterator end ();
    const_iterator end () const;
    reverse_iterator rbegin ();
    const_reverse_iterator rbegin () const;
    reverse_iterator rend ();
    const_reverse_iterator rend () const;

   // Capacity

    size_type size () const;
    size_type max_size () const;
    void resize (size_type);
    void resize (size_type, T);
    size_type capacity () const;
    bool empty () const;
    void reserve (size_type);

   // Element Access

    reference operator[] (size_type);
    const_reference operator[] (size_type) const;
    reference at (size_type);
    const_reference at (size_type) const;
    reference front ();
    const_reference front () const;
    reference back ();
    const_reference back () const;

   // Modifiers

    void push_back (const T&);
    void pop_back ();
    iterator insert (iterator);
    iterator insert (iterator, const T&);
    void insert (iterator, size_type, const T&);
    template <class InputIterator>
     void insert (iterator, InputIterator, InputIterator);
    iterator erase (iterator);
    iterator erase (iterator, iterator);
    void swap (vector<T, Allocator>&);

  };

   // Non-member Operators

  template <class T>
  bool operator== (const vector<T,Allocator>&,
                   const vector <T,Allocator>&);

  template <class T>
  bool operator!= (const vector<T,Allocator>&,
                   const vector <T,Allocator>&);

  template <class T>
  bool operator< (const vector<T,Allocator>&,
                  const vector<T,Allocator>&);

  template <class T>
  bool operator> (const vector<T,Allocator>&,
                  const vector<T,Allocator>&);

  template <class T>
  bool operator<= (const vector<T,Allocator>&,
                  const vector<T,Allocator>&);

  template <class T>
  bool operator>= (const vector<T,Allocator>&,
                  const vector<T,Allocator>&);

  // Specialized Algorithms

  template <class T, class Allocator>
  void swap (const vector<T,Allocator>&, const vector<T,Allocator>&);

CONSTRUCTORS AND DESTRUCTORS

  explicit vector(const Allocator& alloc = Allocator());
     The default constructor.  Creates a vector of length zero. The vector
     will use the allocator alloc for all storage management.

  explicit vector(size_type n,
                  const Allocator& alloc = Allocator());
                     Creates a vector of length n, containing n copies of the
                     default value for type T. Requires that T have a default
                     constructor.  The vector will use the allocator alloc
                     for all storage management.

  vector(size_type n, const T& value,
         const Allocator& alloc = Allocator());
            Creates a vector of length n, containing n copies of value.  The
            vector will use the allocator alloc for all storage management.

  vector(const vector<T, Allocator>& x);
     Creates a copy of x.

  template <class InputIterator>
  vector(InputIterator first, InputIterator last,
         const Allocator& alloc = Allocator());
            Creates a vector of length last - first, filled with all values
            obtained by dereferencing the InputIterators on the range [first,
            last). The vector will use the allocator alloc for all storage
            management.

  ~vector();
     The destructor.  Releases any allocated memory for this vector.

ITERATORS

  iterator
  begin();
     Returns a random access iterator that points to the first element.

  const_iterator
  begin() const;
     Returns a random access const_iterator that points to the first element.

  iterator
  end();
     Returns a random access iterator that points to the past-the-end value.

  const_iterator
  end() const;
     Returns a random access const_iterator that points to the past-the-end
     value.

  reverse_iterator
  rbegin();
     Returns a random access reverse_iterator that points to the past-the-end
     value.

  const_reverse_iterator
  rbegin() const;
     Returns a random access const_reverse_iterator that points to the past-
     the-end value.

  reverse_iterator
  rend();
     Returns a random access reverse_iterator that points to the first
     element.

  const_reverse_iterator
  rend() const;
     Returns a random access const_reverse_iterator that points to the first
     element.

ASSIGNMENT OPERATOR

  vector<T, Allocator>&
  operator=(const vector<T, Allocator>& x);
     Erases all elements in self then inserts into self a copy of each
     element in x.  Returns a reference to self.

ALLOCATOR

  allocator_type
  get_allocator() const;
     Returns a copy of the allocator used by self for storage management.

REFERENCE OPERATORS

  reference
  operator[](size_type n);
     Returns a reference to element n of self.  The result can be used as an
     lvalue.  The index n must be between 0 and the size less one.

  const_reference
  operator[](size_type n) const;
     Returns a constant reference to element n of self. The index n must be
     between 0 and the size less one.

MEMBER FUNCTIONS

  template <class InputIterator>
  void
  assign(InputIterator first, InputIterator last);
     Erases all elements contained in self, then inserts new elements from
     the range [first, last).

  template <class Size, class T>
  void
  assign(Size n, const T& t);
     Erases all elements contained in self, then inserts n instances of the
     default value of  type T.

  template <class Size, class T>
  void
  assign(Size n, const T& t);
     Erases all elements contained in self, then inserts n instances of the
     value of t.

  reference
  at(size_type n);
     Returns a reference to element n of self.   The result can be used as an
     lvalue.  The index n must be between 0 and the size less one.

  const_reference
  at(size_type) const;
     Returns a constant reference to element n of self. The index n must be
     between 0 and the size less one.

  reference
  back();
     Returns a reference to the last element.

  const_reference
  back() const;
     Returns a constant reference to the last element.

  size_type
  capacity() const;
     Returns the size of the allocated storage, as the number of elements
     that can be stored.

  void
  clear() ;
     Deletes all elements from the vector.

  bool
  empty() const;
     Returns true if the size is zero.

  iterator
  erase(iterator position);
     Deletes the vector element pointed to by the iterator position.  Returns
     an iterator pointing to the element following the deleted element, or
     end() if the deleted element was the last one in this vector.

  iterator
  erase(iterator first, iterator last);
     Deletes the vector elements in the range (first, last).  Returns an
     iterator pointing to the element following the last deleted element, or
     end() if there were no elements in the deleted range.

  void
  flip();
     Flips all the bits in the vector.  This member function is only defined
     for vector<bool>.

  reference
  front();
     Returns a reference to the first element.

  const_reference
  front() const;
     Returns a constant reference to the first element.

  iterator
  insert(iterator position);
     Inserts x before position.  The return value  points to the inserted x.

  iterator
  insert(iterator position, const T& x);
     Inserts x before position.  The return value  points to the inserted x.

  void
  insert(iterator position, size_type n, const  T& x);
     Inserts n copies of x before position.

  template <class InputIterator>
  void
  insert(iterator position, InputIterator first,
         InputIterator last);
            Inserts copies of the elements in the range [first, last] before
            position.

  size_type
  max_size() const;
     Returns size() of the largest possible vector.

  void
  pop_back();
     Removes the last element of self.

  void
  push_back(const T& x);
     Inserts a copy of x to the end of self.

  void
  reserve(size_type n);
     Increases the capacity of self in anticipation of adding new elements.
     reserve itself does not add any new elements.  After a call to reserve,
     capacity() is greater than or equal to n and subsequent insertions will
     not cause a reallocation until the size of the vector exceeds n.
     Reallocation does not occur if n is less than capacity().  If
     reallocation does occur, then all iterators and references pointing to
     elements in the vector are invalidated.  reserve takes at most linear
     time in the size of self.

  void
  resize(size_type sz);
     Alters the size of self.  If the new size (sz) is greater than the
     current size, then sz-size() instances of the default value of type T
     are inserted at the end of the vector.  If the new size is smaller than
     the current capacity, then the vector is truncated by erasing size()-sz
     elements off the end. If sz is equal to capacity then no action is
     taken.

  void
  resize(size_type sz, T c);
     Alters the size of self.  If the new size (sz) is greater than the
     current size, then sz-size() c's are inserted at the end of the vector.
     If the new size is smaller than the current capacity, then the vector is
     truncated by erasing size()-sz elements off the end. If sz is equal to
     capacity then no action is taken.

  size_type
  size() const;
     Returns the number of elements.

  void
  swap(vector<T, Allocator>& x);
     Exchanges self with x, by swapping all elements.

  void
  swap(reference x, reference y);
     Swaps the values of x and y.  This is a member function of vector<bool>
     only.

NON-MEMBER OPERATORS

  template <class T, class Allocator>
  bool operator==(const vector<T, Allocator>& x,
                  const vector<T, Allocator>& y);
                     Returns true if x is the same as y.

  template <class T, class Allocator>
  bool operator!=(const vector<T, Allocator>& x,
                  const vector<T, Allocator>& y);
                     Returns !(x==y).

  template <class T>
  bool operator<(const vector<T, Allocator>& x,
                 const vector<T, Allocator>& y);
                    Returns true if the elements contained in x are
                    lexicographically less than the elements contained in y.

  template <class T>
  bool operator>(const vector<T, Allocator>& x,
                 const vector<T, Allocator>& y);
                    Returns y < x.

  template <class T>
  bool operator<=(const vector<T, Allocator>& x,
                 const vector<T, Allocator>& y);
                    Returns !(y < x).

  template <class T>
  bool operator>=(const vector<T, Allocator>& x,
                 const vector<T, Allocator>& y);
                    Returns !(x < y).

SPECIALIZED ALGORITHMS

  template <class T, class Allocator>
  void swap(vector <T, Allocator>& a, vector <T, Allocator>& b);
     Efficiently swaps the contents of a and b.

EXAMPLE

  //
  // vector.cpp
  //
   #include <vector>
   #include <iostream.h>
  ostream& operator<< (ostream& out,
                       const vector<int, allocator>& v)
   {
    copy(v.begin(), v.end(), ostream_iterator<int,char>(out," "));
    return out;
   }
  int main(void)
   {
     // create a vector of doubles
     vector<int>         vi;
    int                 i;
    for(i = 0; i < 10; ++i) {
       // insert values before the beginning
      vi.insert(vi.begin(), i);
     }
     // print out the vector
    cout << vi << endl;
     // now let's erase half of the elements
    int half = vi.size() >> 1;
    for(i = 0; i < half; ++i) {
      vi.erase(vi.begin());
     }
     // print ir out again
    cout << vi << endl;
    return 0;
   }
  Output :

  9 8 7 6 5 4 3 2 1 0
  4 3 2 1 0

WARNINGS

  Member function templates are used in all containers provided by the
  Standard C++ Library.  An example of this feature is the constructor for
  vector<T, Allocator> that takes two templated iterators:

  template <class InputIterator>
  vector (InputIterator, InputIterator,
          const Allocator = Allocator());

  vector also has an insert function of this type.  These functions, when not
  restricted by compiler limitations, allow you to use any type of input
  iterator as arguments.   For compilers that do not support this feature we
  provide substitute functions that allow you to use an iterator obtained
  from the same type of container as the one you are constructing (or calling
  a member function on), or you can use a pointer to the type of element you
  have in the container.

  For example, if your compiler does not support member function templates
  you can construct a vector in the following two ways:

  int intarray[10];
  vector<int> first_vector(intarray, intarray + 10);
  vector<int> second_vector(first_vector.begin(),
                                      first_vector.end());

  but not this way:

  vector<long>
  long_vector(first_vector.begin(),first_vector.end());

  since the long_vector and first_vector are not the same type.

  Additionally, if your compiler does not support default template
  parameters, you will need to supply the Allocator template argument.  For
  instance, you will need to write :

  vector<int, allocator<int> >

  instead of :

  vector<int>

SEE ALSO

  allocator, Containers, Iterators, lexicographical_compare

STANDARDS CONFORMANCE

  ANSI X3J16/ISO WG21 Joint C++ Committee
About PDF files: The PDF files on this site can be read online or printed using Adobe® Acrobat® Reader. If you do not have this software on your system, you may download it from Adobe's website.
Privacy statement Using this site means you accept its terms C++ support
© 2008 Hewlett-Packard Development Company, L.P.