array

Syntax

array(dataType|template, [initialSize], [capacity], [defaultValue])

Details

Creates a vector.

Differences from Python’s numpy.array and pandas.array: numpy.array converts object to an ndarray and can infer or specify dtype, dimensions, memory order, and copy behavior. pandas.array creates a pandas ExtensionArray from a sequence, focusing on nullable/extension dtype inference. DolphinDB’s array creates a DolphinDB vector by a specified data type or template and can specify initialSize, capacity, and defaultValue.

Parameters

dataType can be a basic data type, ANY, ANY[<BasicType>], or <BasicType>[].

When you specify a basic data type, such as INT, DOUBLE, or STRING, the function creates a strongly typed vector of the specified basic type. For example, array(INT, 0) creates an INT vector.
When you specify ANY, the function creates a tuple. Elements in a tuple can have different types and can be either scalars or vectors.
When you specify ANY[<BasicType>], the function creates a columnar tuple. In this case, <BasicType> must be a basic data type, and all elements in the columnar tuple must have the same type. Elements can be either scalars or vectors.
When you specify <BasicType>[], the function creates an array vector. In this case, <BasicType> is the basic data type of each vector element in the array vector, such as INT[] or DOUBLE[]. For an array vector, initialSize must be 0.

template is an existing vector. The existing vector serves as a template and its data type determines the new vector's data type.

initialSize (optional) is the initial size (in terms of the number of elements) of the vector.

capacity (optional) is the amount of memory (in terms of the number of elements) allocated to the array. When the number of elements exceeds capacity, the system will first allocate memory of 1.2~2 times of capacity, copy the data to the new memory space, and release the original memory.

defaultValue (optional) is the default value of the vector. It must be a scalar. If defaultValue is not specified, it defaults to NULL for STRING and SYMBOL values, and 0 for other data types.

Returns

Determined by dataType or template, the return value can be a strongly typed vector, tuple, columnar tuple, or array vector.

Examples

Example 1: Create a strongly typed vector.

x=array(INT, 10, 100, 1) // The vector has an initial length of 10, a capacity of 100, and a default element value of 1
x
// Output: [1,1,1,1,1,1,1,1,1,1]

typestr x
// Output: FAST INT VECTOR

Example 2: Create a tuple.

tp = array(ANY, 0, 10)
tp.append!([1, "DolphinDB", 3.14]) // Elements in a tuple can have different types
tp
// Output: (1,"DolphinDB",3.14)

typestr(tp)
// Output: ANY VECTOR

Example 3: Create a columnar tuple.

ct = array(ANY[INT], 0, 10)
ct.append!([10, 20, 30])
ct.append!([40, 50])
ct
// Output: ([10,20,30],[40,50])

typestr ct
// Output: ANY[INT] VECTOR

Use a columnar tuple as a table column:

t = table(1 2 as id, `A`B as name, ct as data)
t
/*Output
id name data
-- ---- ------------
1  A    [10,20,30]
2  B    [40,50]*/

schema(t).colDefs
// The typeString of the data column is ANY[INT]

Example 4: Create an array vector.

av = array(INT[], 0, 10)
av.append!([1 2 3, 4 5, 6 7 8, 9 10])
av
// Output: [[1,2,3],[4,5],[6,7,8],[9,10]]

typestr(av)
// Output: FAST INT[] VECTOR

Example 5: Create a new vector based on the type of an existing vector. Elements in the new vector do not copy values from the template vector.

template = 1 2 3
x = array(template, 5, 10, 0)
x
// Output: [0,0,0,0,0]

typestr x
// Output: FAST INT VECTOR