Vector

Vector is a container that holds a list of objects in a given order. This section describes how to create, access, and modify vectors, along with examples.

Note: To enhance the performance when working with vectors, it is recommended to perform operations on multiple vector elements simultaneously, as this approach can reduce the number of virtual function calls required.

Creating Vectors

Use the function createVector defined in the header <Util.h>. The following is the syntax to declare a vector:

static Vector* createVector(DATA_TYPE type, INDEX size, INDEX capacity = 0, bool fast = true, int extraParam = 0, void* data = 0, bool containNull = false);

Arguments

type: The data type for the elements of the created vector, such as DT_INT, DT_DATE, etc.
size: The initial size (in terms of the number of elements) of the vector. If size is not set as 0, the elements will be initialized with random values.
capacity: The amount of memory (in terms of the number of elements) allocated to the vector.
fast: It is reserved for potential future use, but as of now serves no functional purpose. Leaving it to default or passing any value to it will not change behavior of the function.
extraParam: It determines the scale for values in a vector of DECIMAL type.
data: A pointer variable that stores the address of vector elements to be passed in when parameter capacity is specified. When the vector object is being destructed,the memory block pointed by the pointer will be automatically destroyed through delete[].
containNull: It determines if any of the first size elements of data in the vector contain Null values. Set to true if contains Nulls, otherwise false.

Examples

VectorSP createDemoVector(){                                              //define a function for later use
    double* data = new double[10];
    for(int i = 0; i < 10; ++i){
        data[i] = i;
    }
    data[5] = getNullValue<double>();
    return Util::createVector(DT_DOUBLE, 10, 10, true, 0, data, true);    //create a 10-element DOUBLE vector with a reserved capacity of 10 elements. Specify a pointer storing 10 DOUBLE values with Nulls.
}
VectorSP vi = Util::createVector(DT_INT, 0, 100);                         //create an empty INT vector with a reserved capacity of 100 elements
VectorSP vd = Util::createVector(DT_DECIMAL32, 0, 100, true, 5);          //create an empty DECIMAL32(5) vector with a reserved capacity of 100 elements
VectorSP vdb = createDemoVector();         
std::cout << vdb->getString() << std::endl;                               //[0,1,2,3,4,,6,7,8,9]

Accessing Vectors

The DolphinDB C++ API provides three methods to retrieve data from a vector:

(1) Accessing a vector by position. The function declarations are as follows:

ConstantSP get(INDEX index) const;           //return the value of the element at position index
int getInt(INDEX index) const;               //return the int value of the element at position index
long long getLong(INDEX index) const;        //return the long value of the element at position index
...

Examples

VectorSP vi = createDemoVector();            //[0,1,2,3,4,,6,7,8,9]
ConstantSP e1 = vi->get(1);                  //Output: 1, a scalar of DT_DOUBLE type
double e2 = vi->getDouble(2);                //Output: 2, a scalar of double type

(2) Insert copies of elements from range [start, start + len) to a new vector specified by buf. The function declarations are as follows:

bool getInt(INDEX start, int len, int* buf) const;           
bool getLong(INDEX start, int len, long long* buf) const;
...

Examples

VectorSP vi = createDemoVector();            //[0,1,2,3,4,,6,7,8,9]
double buf[10]{};
vi->getDouble(0, 5, buf);                    //output: [0, 1, 2, 3, 4, 0, 0, 0, 0, 0]

(3) Accessing multiple elements of a vector from the read-only buffer. The function declarations are as follows:

const int* getIntConst(INDEX start, int len, int* buf) const          //If the vector is of DT_INT type, returns the address of its first element. Otherwise, converts its type to INT and returns buf.
const long long* getLongConst(INDEX start, int len, long long* buf)   //If the vector is of DT_LONG type, returns the address of its first element. Otherwise, converts its type to LONG and returns buf.
...

Examples

VectorSP vi = createDemoVector();                        //[0,1,2,3,4,,6,7,8,9]
double buf[10]{};
const double* data = vi->getDoubleConst(0, 5, buf);      //output: [0, 1, 2, 3, 4]

Appending Data to a Vector

The DolphinDB C++ API provides two methods for appending data to a vector:

(1) Use the append function to add values to the end of a vector. The function declarations are as follows:

bool append(const ConstantSP& value);                              //value can be a scalar or vector
bool append(const ConstantSP& value, INDEX count);                 //With 'count' specified, if value is a scalar, add 'count' elements to the end of the vetor; if it is a vector, add the first 'count' elements.
bool append(const ConstantSP value, INDEX start, INDEX length);    //With 'start' and 'length' specified, value is a vetor. Add elements within the range [start, start + length) to the end of the vector.

Examples

VectorSP vi = Util::createVector(DT_INT, 0, 100);         //[]
vi->append(new Int(1));                                   //[1]
vi->append(new Int(4), 5);                                //[1, 4, 4, 4, 4, 4]
VectorSP vi2 = Util::createVector(DT_INT, 0, 100);        //[]
vi2->append(vi, 2, 3);                                    //[4, 4, 4]

(2) Use the corresponding append function such as appendInt, appendLong, etc. to add values (the first len elements of buf) of specific type to the end of a vector. The function declarations are as follows:

bool appendInt(int* buf, int len);
bool appendLong(long long* buf, int len);
bool appendDouble(double* buf, int len);
...

Examples

VectorSP vi = Util::createVector(DT_INT, 0, 100);         //[]
std::vector<int> v2{1, 2, 3, 4, 5};
vi->appendInt(v2.data(), v2.size());                      //[1, 2, 3, 4, 5]

Updating Vectors

The DolphinDB C++ API provides two methods for updating vectors:

(1) Updating a vector by position. The function declarations are as follows:

bool set(INDEX index, const ConstantSP& value);           //replace the element at position index with the new value
void setInt(INDEX index,int val);
void setLong(INDEX index,long long val); 
...

Examples

VectorSP vi = createDemoVector();                         //[0,1,2,3,4,,6,7,8,9]
vi->set(1, new Double(100));                              //output: [0,100,2,3,4,,6,7,8,9]
vi->setDouble(2, 200);                                    //output: [0,100,200,3,4,,6,7,8,9]

(2) Replace elements from range [start, start + len) with new values specified by buf. The function declarations are as follows:

bool setInt(INDEX start, int len, const int* buf);                                  
bool setLong(INDEX start, int len, const long long* buf);
...
double* getDoubleBuffer(INDEX start, int len, double* buf)     //get the address of the vector elements
float* getFloatBuffer(INDEX start, int len, float* buf)

Examples

VectorSP vi = createDemoVector();               //[0,1,2,3,4,,6,7,8,9]
double buf_[5];
auto buf = vi->getDoubleBuffer(0, 5, buf_);
for(int i = 0; i < 5; ++i){
    buf[i] = buf[i] * 2;                        //Multiply the value of the first five elements by 2
}                   
vi->setDouble(0, 5, buf);                       //output: [0,2,4,6,8,,6,7,8,9]