Class template vector

| Home | Libraries | People | FAQ | More

## 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 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 std::vector< T, OtherAlloc > & vector);

12.     vector & operator=(vector && other);

    Move-assigns the data from `other` to `*this`.

13.     ~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.