Apache Arrow (C++)
A columnar in-memory analytics layer designed to accelerate big data.
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
arrow::ListBuilder Class Reference

Builder class for variable-length list array value types. More...

#include <arrow/builder.h>

Inheritance diagram for arrow::ListBuilder:
arrow::ArrayBuilder

Public Member Functions

 ListBuilder (MemoryPool *pool, std::unique_ptr< ArrayBuilder > value_builder, const std::shared_ptr< DataType > &type=NULLPTR)
 Use this constructor to incrementally build the value array along with offsets and null bitmap. More...
 
Status Init (int64_t elements) override
 Allocates initial capacity requirements for the builder. More...
 
Status Resize (int64_t capacity) override
 Resizes the null_bitmap array. More...
 
Status FinishInternal (std::shared_ptr< ArrayData > *out) override
 Return result of builder as an internal generic ArrayData object. More...
 
Status Append (const int32_t *offsets, int64_t length, const uint8_t *valid_bytes=NULLPTR)
 Vector append. More...
 
Status Append (bool is_valid=true)
 Start a new variable-length list slot. More...
 
Status AppendNull ()
 
ArrayBuildervalue_builder () const
 
- Public Member Functions inherited from arrow::ArrayBuilder
 ArrayBuilder (const std::shared_ptr< DataType > &type, MemoryPool *pool)
 
virtual ~ArrayBuilder ()=default
 
ArrayBuilderchild (int i)
 For nested types. More...
 
int num_children () const
 
int64_t length () const
 
int64_t null_count () const
 
int64_t capacity () const
 
Status AppendToBitmap (bool is_valid)
 Append to null bitmap. More...
 
Status AppendToBitmap (const uint8_t *valid_bytes, int64_t length)
 Vector append. More...
 
Status SetNotNull (int64_t length)
 Set the next length bits to not null (i.e. valid). More...
 
Status Reserve (int64_t elements)
 Ensures there is enough space for adding the number of elements by checking capacity and calling Resize if necessary. More...
 
Status Advance (int64_t elements)
 For cases where raw data was memcpy'd into the internal buffers, allows us to advance the length of the builder. More...
 
std::shared_ptr< PoolBuffernull_bitmap () const
 
Status Finish (std::shared_ptr< Array > *out)
 Return result of builder as an Array object. More...
 
std::shared_ptr< DataTypetype () const
 

Protected Member Functions

Status AppendNextOffset ()
 
void Reset ()
 
- Protected Member Functions inherited from arrow::ArrayBuilder
 ArrayBuilder ()
 
void Reset ()
 
void UnsafeAppendToBitmap (bool is_valid)
 
void UnsafeAppendToBitmap (const uint8_t *valid_bytes, int64_t length)
 
void UnsafeAppendToBitmap (const std::vector< bool > &is_valid)
 
void UnsafeSetNotNull (int64_t length)
 

Protected Attributes

TypedBufferBuilder< int32_t > offsets_builder_
 
std::unique_ptr< ArrayBuildervalue_builder_
 
std::shared_ptr< Arrayvalues_
 
- Protected Attributes inherited from arrow::ArrayBuilder
std::shared_ptr< DataTypetype_
 
MemoryPoolpool_
 
std::shared_ptr< PoolBuffernull_bitmap_
 
int64_t null_count_
 
uint8_t * null_bitmap_data_
 
int64_t length_
 
int64_t capacity_
 
std::vector< std::unique_ptr< ArrayBuilder > > children_
 

Detailed Description

Builder class for variable-length list array value types.

To use this class, you must append values to the child array builder and use the Append function to delimit each distinct list value (once the values have been appended to the child array) or use the bulk API to append a sequence of offests and null values.

A note on types. Per arrow/type.h all types in the c++ implementation are logical so even though this class always builds list array, this can represent multiple different logical types. If no logical type is provided at construction time, the class defaults to List<T> where t is taken from the value_builder/values that the object is constructed with.

Constructor & Destructor Documentation

◆ ListBuilder()

arrow::ListBuilder::ListBuilder ( MemoryPool pool,
std::unique_ptr< ArrayBuilder value_builder,
const std::shared_ptr< DataType > &  type = NULLPTR 
)

Use this constructor to incrementally build the value array along with offsets and null bitmap.

Member Function Documentation

◆ Append() [1/2]

Status arrow::ListBuilder::Append ( const int32_t *  offsets,
int64_t  length,
const uint8_t *  valid_bytes = NULLPTR 
)

Vector append.

If passed, valid_bytes is of equal length to values, and any zero byte will be considered as a null for that slot

◆ Append() [2/2]

Status arrow::ListBuilder::Append ( bool  is_valid = true)

Start a new variable-length list slot.

This function should be called before beginning to append elements to the value builder

◆ AppendNextOffset()

Status arrow::ListBuilder::AppendNextOffset ( )
protected

◆ AppendNull()

Status arrow::ListBuilder::AppendNull ( )
inline

◆ FinishInternal()

Status arrow::ListBuilder::FinishInternal ( std::shared_ptr< ArrayData > *  out)
overridevirtual

Return result of builder as an internal generic ArrayData object.

Resets builder

Parameters
[out]outthe finalized ArrayData object
Returns
Status

Implements arrow::ArrayBuilder.

◆ Init()

Status arrow::ListBuilder::Init ( int64_t  capacity)
overridevirtual

Allocates initial capacity requirements for the builder.

In most cases subclasses should override and call their parent class's method as well.

Reimplemented from arrow::ArrayBuilder.

◆ Reset()

void arrow::ListBuilder::Reset ( )
protected

◆ Resize()

Status arrow::ListBuilder::Resize ( int64_t  new_bits)
overridevirtual

Resizes the null_bitmap array.

In most cases subclasses should override and call their parent class's method as well.

Reimplemented from arrow::ArrayBuilder.

◆ value_builder()

ArrayBuilder* arrow::ListBuilder::value_builder ( ) const

Member Data Documentation

◆ offsets_builder_

TypedBufferBuilder<int32_t> arrow::ListBuilder::offsets_builder_
protected

◆ value_builder_

std::unique_ptr<ArrayBuilder> arrow::ListBuilder::value_builder_
protected

◆ values_

std::shared_ptr<Array> arrow::ListBuilder::values_
protected

The documentation for this class was generated from the following file: