Awkward Array: Builder Class Reference

Loading...
Searching...
No Matches
Public Member Functions | List of all members
Builder Class Referenceabstract

Abstract base class for nodes within an ArrayBuilder that cumulatively discover an array's type and fill it. More...

`#include <Builder.h>`

Inheritance diagram for Builder:

## Public Member Functions
virtual | ~Builder ()
| Virtual destructor acts as a first non-inline virtual function that determines a specific translation unit in which vtable shall be emitted.
virtual const std::string | classname () const =0
| User-friendly name of this class.
virtual const std::string | to_buffers (BuffersContainer &container, int64_t &form_key_id) const =0
| Copy the current snapshot into the BuffersContainer and return a Form as a std::string (JSON).
virtual int64_t | length () const =0
| Current length of the accumulated array.
virtual void | clear ()=0
| Removes all accumulated data without resetting the type knowledge.
virtual bool | active () const =0
| If `true`, this node has started but has not finished a multi-step command (e.g. `beginX ... endX`).
virtual const BuilderPtr | null ()=0
| Adds a `null` value to the accumulated data.
virtual const BuilderPtr | boolean (bool x)=0
| Adds a boolean value `x` to the accumulated data.
virtual const BuilderPtr | integer (int64_t x)=0
| Adds an integer value `x` to the accumulated data.
virtual const BuilderPtr | real (double x)=0
| Adds a real value `x` to the accumulated data.
virtual const BuilderPtr | complex (std::complex< double > x)=0
| Adds a complex value `x` to the accumulated data.
virtual const BuilderPtr | datetime (int64_t x, const std::string &unit)=0
| Adds a datetime value `x` to the accumulated data.
virtual const BuilderPtr | timedelta (int64_t x, const std::string &unit)=0
| Adds a timedelta value `x` to the accumulated data.
virtual const BuilderPtr | string (const char *x, int64_t length, const char *encoding)=0
| Adds a string value `x` with a given `length` and `encoding` to the accumulated data.
virtual const BuilderPtr | beginlist ()=0
| Begins building a nested list.
virtual const BuilderPtr | endlist ()=0
| Ends a nested list.
virtual const BuilderPtr | begintuple (int64_t numfields)=0
| Begins building a tuple with a fixed number of fields.
virtual const BuilderPtr | index (int64_t index)=0
| Sets the pointer to a given tuple field index; the next command will fill that slot.
virtual const BuilderPtr | endtuple ()=0
| Ends a tuple.
virtual const BuilderPtr | beginrecord (const char *name, bool check)=0
| Begins building a record with an optional name.
virtual void | field (const char *key, bool check)=0
| Sets the pointer to a given record field `key`; the next command will fill that slot.
virtual const BuilderPtr | endrecord ()=0
| Ends a record.

## Detailed Description

Abstract base class for nodes within an ArrayBuilder that cumulatively discover an array's type and fill it.

## Constructor & Destructor Documentation

## ◆ ~Builder()

virtual ~Builder | ( |  | ) |
| virtual

Virtual destructor acts as a first non-inline virtual function that determines a specific translation unit in which vtable shall be emitted.

## Member Function Documentation

## ◆ active()

virtual bool active | ( |  | ) | const
| pure virtual

If `true`, this node has started but has not finished a multi-step command (e.g. `beginX ... endX`).

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ beginlist()

virtual const BuilderPtr beginlist | ( |  | ) |
| pure virtual

Begins building a nested list.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ beginrecord()

virtual const BuilderPtr beginrecord | ( | const char * | name,
|  | bool | check
| ) |  |
| pure virtual

Begins building a record with an optional name.

Parameters

  name | If specified, this name is used to distinguish records of different types in heterogeneous data (to build a union of record arrays, rather than a record array with union fields and optional values) and it also sets the `"__record__"` parameter to later add custom behaviors in Python.
  check | If `true`, actually do a string comparison to see if the provided `name` matches the previous `name`; if `false`, assume that the same pointer means the same string (safe for string literals).

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ begintuple()

virtual const BuilderPtr begintuple | ( | int64_t | numfields | ) |
| pure virtual

Begins building a tuple with a fixed number of fields.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ boolean()

virtual const BuilderPtr boolean | ( | bool | x | ) |
| pure virtual

Adds a boolean value `x` to the accumulated data.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ classname()

virtual const std::string classname | ( |  | ) | const
| pure virtual

User-friendly name of this class.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ clear()

virtual void clear | ( |  | ) |
| pure virtual

Removes all accumulated data without resetting the type knowledge.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ complex()

virtual const BuilderPtr complex | ( | std::complex< double > | x | ) |
| pure virtual

Adds a complex value `x` to the accumulated data.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ datetime()

virtual const BuilderPtr datetime | ( | int64_t | x,
|  | const std::string & | unit
| ) |  |
| pure virtual

Adds a datetime value `x` to the accumulated data.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ endlist()

virtual const BuilderPtr endlist | ( |  | ) |
| pure virtual

Ends a nested list.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ endrecord()

virtual const BuilderPtr endrecord | ( |  | ) |
| pure virtual

Ends a record.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ endtuple()

virtual const BuilderPtr endtuple | ( |  | ) |
| pure virtual

Ends a tuple.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ field()

virtual void field | ( | const char * | key,
|  | bool | check
| ) |  |
| pure virtual

Sets the pointer to a given record field `key`; the next command will fill that slot.

Parameters

  key | Indicates the field to fill.
  check | If `true`, actually do a string comparison to see if `key` matches the previous `key`; if `false`, assume that the same pointer means the same string (safe for string literals).

Record keys are checked in round-robin order. The best performance will be achieved by filling them in the same order for each record. Lookup time for random order scales with the number of fields.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ index()

virtual const BuilderPtr index | ( | int64_t | index | ) |
| pure virtual

Sets the pointer to a given tuple field index; the next command will fill that slot.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ integer()

virtual const BuilderPtr integer | ( | int64_t | x | ) |
| pure virtual

Adds an integer value `x` to the accumulated data.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ length()

virtual int64_t length | ( |  | ) | const
| pure virtual

Current length of the accumulated array.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ null()

virtual const BuilderPtr null | ( |  | ) |
| pure virtual

Adds a `null` value to the accumulated data.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ real()

virtual const BuilderPtr real | ( | double | x | ) |
| pure virtual

Adds a real value `x` to the accumulated data.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ string()

virtual const BuilderPtr string | ( | const char * | x,
|  | int64_t | length,
|  | const char * | encoding
| ) |  |
| pure virtual

Adds a string value `x` with a given `length` and `encoding` to the accumulated data.

Note
  Currently, only `encoding =`

- `nullptr` (no encoding; a bytestring)
- `"utf-8"` (variable-length Unicode 8-bit encoding)

are supported.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ timedelta()

virtual const BuilderPtr timedelta | ( | int64_t | x,
|  | const std::string & | unit
| ) |  |
| pure virtual

Adds a timedelta value `x` to the accumulated data.

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

## ◆ to_buffers()

virtual const std::string to_buffers | ( | BuffersContainer & | container,
|  | int64_t & | form_key_id
| ) |  | const
| pure virtual

Copy the current snapshot into the BuffersContainer and return a Form as a std::string (JSON).

Implemented in BoolBuilder, Complex128Builder, DatetimeBuilder, Float64Builder, Int64Builder, ListBuilder, OptionBuilder, RecordBuilder, StringBuilder, TupleBuilder, UnionBuilder, and UnknownBuilder.

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

- include/awkward/builder/Builder.h