080_vector.Rmd

# Vector

## Creating vector object

You can create vector objects in several ways.

```cpp
// Create a Vector object equivalent to
// v <- rep(0, 3)
NumericVector v (3);

// v <- rep(1, 3)
NumericVector v (3,1);

// v <- c(1,2,3) 
// C++11 Initializer list
NumericVector v = {1,2,3}; 

// v <- c(1,2,3)
NumericVector v = NumericVector::create(1,2,3);

// v <- c(x=1, y=2, z=3)
NumericVector v =
  NumericVector::create(Named("x",1), Named("y")=2 , _["z"]=3);
```

## Accessing vector elements

You can access an individual element of a vector object using `[]` or `()` operator. Both operators accept NumericVector/IntegerVector (numerical index), CharacterVector (element names) and LogicalVector. `[]` operator ignores out of bound access, while `()` operator throws an exception `index_out_of_bounds`.

**Note that the index of the Vector object in C++ starts from 0.**

```cpp
// [[Rcpp::export]]
void rcpp_vector_access(){

  // Creating vector
  NumericVector v  {10,20,30,40,50};

  // Setting element names
  v.names() = CharacterVector({"A","B","C","D","E"});

  // Preparing vector for access
  NumericVector   numeric = {1,3};
  IntegerVector   integer = {1,3};
  CharacterVector character = {"B","D"};
  LogicalVector   logical = {false, true, false, true, false};

  // Getting values of vector elements
  double x1 = v[0];
  double x2 = v["A"];
  NumericVector res1 = v[numeric];
  NumericVector res2 = v[integer];
  NumericVector res3 = v[character];
  NumericVector res4 = v[logical];

  // Assigning values to vector elements
  v[0]   = 100;
  v["A"] = 100;
  NumericVector v2 {100,200};
  v[numeric]   = v2;
  v[integer]   = v2;
  v[character] = v2;
  v[logical]   = v2;
}
```

## Member functions {#member-functions-vector}

Member functions (also called Methods) are functions that are attached to an individual object. You can call member functions `f()` of object `v` in the form of `v.f()`.

```cpp
NumericVector v = {1,2,3,4,5};

// Calling member function
int n = v.length(); // 5
```

The `Vector` object in Rcpp has member functions listed below.


### `length()`, `size()`

Returns the number of elements of this vector object.

### `names()`

Returns the element names of this vector object as `CharacterVector.`

### `offset( name )`, `findName( name )`

Returns numerical index of the element specified by character string `name`.

### `offset( i )`

Returns numerical index of the element specified by numerical index `i` after doing bounds checking to ensure `i` is valid.

### `fill( x )`

Fills all the elements of this vector object with scalar value `x`.

### `sort()`

Returns a vector that sorts this vector object in ascending order.

### `assign( first_it, last_it )`

Assigns values specified by the iterator `first_it` and `last_it` to this vector object.

### `push_back( x )`

Append a scalar value `x` to the end of this vector object.

### `push_back( x, name )`

Append a scalar value `x` to the end of this vector object and set name of the element as character string `name`.

### `push_front( x )`

Append a scalar value `x` to the front of this vector object.

### `push_front( x, name )`

Append a scalar value `x` to the front of this vector and set name of the element as character string `name`.

### `begin()`

Returns an iterator pointing to the first element of this vector. See [the Chapter 28 Iterator](280_iterator.html).

### `end()`

Returns an iterator pointing to the end of the vector (**one past the last element of this vector**). See [the Chapter 28 Iterator](280_iterator.html).


### `cbegin()`

Returns a const iterator pointing to the first element of the vector. See [the Chapter 28 Iterator](280_iterator.html).

### `cend()`

Returns a const iterator pointing to the end of the vector (**one past the last element of this vector**). See [the Chapter 28 Iterator](280_iterator.html).


### `insert( i, x )`

Insert scalar value `x` to the position pointed by numerical index `i`. And returns the iterator pointing to the inserted element.


### `insert( it, x )`

Insert scalar value `x` to the position pointed by iterator `it`. And returns the iterator pointing to the inserted element.

### `erase(i)`

Erase element at the position pointed by numerical index `i`. And returns the iterator pointing to the element just behind the erased element.

### `erase(it)`

Erase element at the position pointed by iterator `it`. And returns the iterator pointing to the element just behind the erased element.

### `erase( first_i, last_i )`

Erase elements from the position pointed by numerical index `first_i` to `last_i - 1`. And returns the iterator pointing to the element just behind the erased elements.

### `erase( first_it, last_it )`

Erase elements from the position pointed by the iterator `first_it` to `last_it - 1`. Return the iterator pointing the element just behind the erased elements.

### `containsElementNamed(name)`

Returns `true` if this vector contains an element with the name specified by character string `name`.


## Static member functions {#static-member-functions-vector}

Static member function is a function that is attached to the class rather than a from which an object is being molded. 

You can call static member functions in the form such as `NumericVector::create()`.

### `get_na()`

Returns the `NA` value of this `Vector` class. See [chapter 24 for NA](240_na_nan_inf.html).

### `is_na(x)`

Returns `true` if a vector element specified by `x` is `NA`.


### `create( x1, x2, ...)`

Creates a `Vector` object containing elements specified by scalar value `x1` and `x2`. Maximum number of arguments is 20.

### `import( first_it , last_it )`

Creates a `Vector` object filled with the range of data specified by the iterator from `first_it` to `last_it - 1`.

### `import_transform( first_it, last_it, func)`

Creates a `Vector` object filled with the range of data specified by the iterator from `first_it` to `last_it - 1` that is transformed by function specified by `func`.