Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Class template vector

boost::compute::vector — A resizable array of values.

Synopsis

// In header: <boost/compute/container/vector.hpp>

template<typename T, typename Alloc = buffer_allocator<T> > 
class vector {
public:
  // types
  typedef T                                       value_type;            
  typedef Alloc                                   allocator_type;        
  typedef allocator_type::size_type               size_type;             
  typedef allocator_type::difference_type         difference_type;       
  typedef unspecified                             reference;             
  typedef unspecified                             const_reference;       
  typedef allocator_type::pointer                 pointer;               
  typedef allocator_type::const_pointer           const_pointer;         
  typedef buffer_iterator< T >                    iterator;              
  typedef buffer_iterator< T >                    const_iterator;        
  typedef std::reverse_iterator< iterator >       reverse_iterator;      
  typedef std::reverse_iterator< const_iterator > const_reverse_iterator;

  // construct/copy/destruct
  explicit vector(const context & = system::default_context());
  explicit vector(size_type, const context & = system::default_context());
  vector(size_type, const T &, command_queue & = system::default_queue());
  template<typename InputIterator> 
    vector(InputIterator, InputIterator, 
           command_queue & = system::default_queue());
  vector(const vector &, command_queue & = system::default_queue());
  template<typename OtherAlloc> 
    vector(const vector< T, OtherAlloc > &, 
           command_queue & = system::default_queue());
  template<typename OtherAlloc> 
    vector(const std::vector< T, OtherAlloc > &, 
           command_queue & = system::default_queue());
  vector(std::initializer_list< T >, 
         command_queue & = system::default_queue());
  vector(vector &&);
  vector & operator=(const vector &);
  template<typename OtherAlloc> 
    vector & operator=(const vector< T, OtherAlloc > &);
  template<typename OtherAlloc> 
    vector & operator=(const std::vector< T, OtherAlloc > &);
  vector & operator=(vector &&);
  ~vector();

  // public member functions
  iterator begin();
  const_iterator begin() const;
  const_iterator cbegin() const;
  iterator end();
  const_iterator end() const;
  const_iterator cend() const;
  reverse_iterator rbegin();
  const_reverse_iterator rbegin() const;
  const_reverse_iterator crbegin() const;
  reverse_iterator rend();
  const_reverse_iterator rend() const;
  const_reverse_iterator crend() const;
  size_type size() const;
  size_type max_size() const;
  void resize(size_type, command_queue &);
  void resize(size_type);
  bool empty() const;
  size_type capacity() const;
  void reserve(size_type, command_queue &);
  void reserve(size_type);
  void shrink_to_fit(command_queue &);
  void shrink_to_fit();
  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;
  template<typename InputIterator> 
    void assign(InputIterator, InputIterator, command_queue &);
  template<typename InputIterator> void assign(InputIterator, InputIterator);
  void assign(size_type, const T &, command_queue &);
  void assign(size_type, const T &);
  void push_back(const T &, command_queue &);
  void push_back(const T &);
  void pop_back(command_queue &);
  void pop_back();
  iterator insert(iterator, const T &, command_queue &);
  iterator insert(iterator, const T &);
  void insert(iterator, size_type, const T &, command_queue &);
  void insert(iterator, size_type, const T &);
  template<typename InputIterator> 
    void insert(iterator, InputIterator, InputIterator, command_queue &);
  template<typename InputIterator> 
    void insert(iterator, InputIterator, InputIterator);
  iterator erase(iterator, command_queue &);
  iterator erase(iterator);
  iterator erase(iterator, iterator, command_queue &);
  iterator erase(iterator, iterator);
  void swap(vector &);
  void clear();
  allocator_type get_allocator() const;
  const buffer & get_buffer() const;
};

Description

The vector<T> class stores a dynamic array of values. Internally, the data is stored in an OpenCL buffer object.

The vector class is the prefered container for storing and accessing data on a compute device. In most cases it should be used instead of directly dealing with buffer objects. If the undelying buffer is needed, it can be accessed with the get_buffer() method.

The internal storage is allocated in a specific OpenCL context which is passed as an argument to the constructor when the vector is created.

For example, to create a vector on the device containing space for ten int values:

boost::compute::vector<int> vec(10, context);

Allocation and data transfer can also be performed in a single step:

// values on the host
int data[] = { 1, 2, 3, 4 };

// create a vector of size four and copy the values from data
boost::compute::vector<int> vec(data, data + 4, queue);

The Boost.Compute vector class provides a STL-like API and is modeled after the std::vector class from the C++ standard library. It can be used with any of the STL-like algorithms provided by Boost.Compute including copy(), transform(), and sort() (among many others).

For example:

// a vector on a compute device
boost::compute::vector<float> vec = ...

// copy data to the vector from a host std:vector
boost::compute::copy(host_vec.begin(), host_vec.end(), vec.begin(), queue);

// copy data from the vector to a host std::vector
boost::compute::copy(vec.begin(), vec.end(), host_vec.begin(), queue);

// sort the values in the vector
boost::compute::sort(vec.begin(), vec.end(), queue);

// calculate the sum of the values in the vector (also see reduce())
float sum = boost::compute::accumulate(vec.begin(), vec.end(), 0, queue);

// reverse the values in the vector
boost::compute::reverse(vec.begin(), vec.end(), queue);

// fill the vector with ones
boost::compute::fill(vec.begin(), vec.end(), 1, queue);

See Also:

array<T, N>, buffer

vector public construct/copy/destruct

  1. explicit vector(const context & context = system::default_context());
    Creates an empty vector in context.
  2. explicit vector(size_type count, 
                    const context & context = system::default_context());

    Creates a vector with space for count elements in context.

    Note that unlike std::vector's constructor, this will not initialize the values in the container. Either call the vector constructor which takes a value to initialize with or use the fill() algorithm to set the initial values.

    For example:

    // create a vector on the device with space for ten ints
    boost::compute::vector<int> vec(10, context);
    

  3. vector(size_type count, const T & value, 
           command_queue & queue = system::default_queue());

    Creates a vector with space for count elements and sets each equal to value.

    For example:

    // creates a vector with four values set to nine (e.g. [9, 9, 9, 9]).
    boost::compute::vector<int> vec(4, 9, queue);
    

  4. template<typename InputIterator> 
      vector(InputIterator first, InputIterator last, 
             command_queue & queue = system::default_queue());

    Creates a vector with space for the values in the range [first, last) and copies them into the vector with queue.

    For example:

    // values on the host
    int data[] = { 1, 2, 3, 4 };
    
    // create a vector of size four and copy the values from data
    boost::compute::vector<int> vec(data, data + 4, queue);
    

  5. vector(const vector & other, command_queue & queue = system::default_queue());
    Creates a new vector and copies the values from other.
  6. template<typename OtherAlloc> 
      vector(const vector< T, OtherAlloc > & other, 
             command_queue & queue = system::default_queue());
    Creates a new vector and copies the values from other.
  7. template<typename OtherAlloc> 
      vector(const std::vector< T, OtherAlloc > & vector, 
             command_queue & queue = system::default_queue());
    Creates a new vector and copies the values from vector.
  8. vector(std::initializer_list< T > list, 
           command_queue & queue = system::default_queue());
  9. vector(vector && other);
    Move-constructs a new vector from other.
  10. vector & operator=(const vector & other);
  11. template<typename OtherAlloc> 
      vector & operator=(const vector< T, OtherAlloc > & other);
  12. template<typename OtherAlloc> 
      vector & operator=(const std::vector< T, OtherAlloc > & vector);
  13. vector & operator=(vector && other);
    Move-assigns the data from other to *this.
  14. ~vector();
    Destroys the vector object.

vector public member functions

  1. iterator begin();
  2. const_iterator begin() const;
  3. const_iterator cbegin() const;
  4. iterator end();
  5. const_iterator end() const;
  6. const_iterator cend() const;
  7. reverse_iterator rbegin();
  8. const_reverse_iterator rbegin() const;
  9. const_reverse_iterator crbegin() const;
  10. reverse_iterator rend();
  11. const_reverse_iterator rend() const;
  12. const_reverse_iterator crend() const;
  13. size_type size() const;
    Returns the number of elements in the vector.
  14. size_type max_size() const;
  15. void resize(size_type size, command_queue & queue);
    Resizes the vector to size.
  16. void resize(size_type size);
    This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
  17. bool empty() const;
    Returns true if the vector is empty.
  18. size_type capacity() const;
    Returns the capacity of the vector.
  19. void reserve(size_type size, command_queue & queue);
  20. void reserve(size_type size);
  21. void shrink_to_fit(command_queue & queue);
  22. void shrink_to_fit();
  23. reference operator[](size_type index);
  24. const_reference operator[](size_type index) const;
  25. reference at(size_type index);
  26. const_reference at(size_type index) const;
  27. reference front();
  28. const_reference front() const;
  29. reference back();
  30. const_reference back() const;
  31. template<typename InputIterator> 
      void assign(InputIterator first, InputIterator last, command_queue & queue);
  32. template<typename InputIterator> 
      void assign(InputIterator first, InputIterator last);
  33. void assign(size_type n, const T & value, command_queue & queue);
  34. void assign(size_type n, const T & value);
  35. void push_back(const T & value, command_queue & queue);

    Inserts value at the end of the vector (resizing if neccessary).

    Note that calling push_back() to insert data values one at a time is inefficient as there is a non-trivial overhead in performing a data transfer to the device. It is usually better to store a set of values on the host (for example, in a std::vector) and then transfer them in bulk using the insert() method or the copy() algorithm.

  36. void push_back(const T & value);
    This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
  37. void pop_back(command_queue & queue);
  38. void pop_back();
  39. iterator insert(iterator position, const T & value, command_queue & queue);
  40. iterator insert(iterator position, const T & value);
  41. void insert(iterator position, size_type count, const T & value, 
                command_queue & queue);
  42. void insert(iterator position, size_type count, const T & value);
  43. template<typename InputIterator> 
      void insert(iterator position, InputIterator first, InputIterator last, 
                  command_queue & queue);

    Inserts the values in the range [first, last) into the vector at position using queue.

  44. template<typename InputIterator> 
      void insert(iterator position, InputIterator first, InputIterator last);
    This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
  45. iterator erase(iterator position, command_queue & queue);
  46. iterator erase(iterator position);
  47. iterator erase(iterator first, iterator last, command_queue & queue);
  48. iterator erase(iterator first, iterator last);
  49. void swap(vector & other);
    Swaps the contents of *this with other.
  50. void clear();
    Removes all elements from the vector.
  51. allocator_type get_allocator() const;
  52. const buffer & get_buffer() const;
    Returns the underlying buffer.

PrevUpHomeNext