ArrayBuilder Class Reference

User interface to the Builder system: the ArrayBuilder is a fixed reference while the Builder subclass instances change in response to accumulating data. More...

#include <ArrayBuilder.h>

Public Member Functions
	ArrayBuilder (const BuilderOptions &options)
	Creates an ArrayBuilder from a full set of parameters.
const std::string	to_buffers (BuffersContainer &container, int64_t &form_key_id) const
	Copy the current snapshot into the BuffersContainer and return a Form as a std::string (JSON).
int64_t	length () const
	Current length of the accumulated array.
void	clear ()
	Removes all accumulated data without resetting the type knowledge.
void	null ()
	Adds a null value to the accumulated data.
void	boolean (bool x)
	Adds a boolean value x to the accumulated data.
void	integer (int64_t x)
	Adds an integer value x to the accumulated data.
void	real (double x)
	Adds a real value x to the accumulated data.
void	complex (std::complex< double > x)
	Adds a complex value x to the accumulated data.
void	datetime (int64_t x, const std::string &unit)
	Adds a datetime value x to the accumulated data.
void	timedelta (int64_t x, const std::string &unit)
	Adds a timedelta value x to the accumulated data.
void	bytestring (const char *x)
	Adds an unencoded, null-terminated bytestring value x to the accumulated data.
void	bytestring (const char *x, int64_t length)
	Adds an unencoded bytestring value x with a given length to the accumulated data.
void	bytestring (const std::string &x)
	Adds an unencoded bytestring x in STL format to the accumulated data.
void	string (const char *x)
	Adds a UTF-8 encoded, null-terminated bytestring value x to the accumulated data.
void	string (const char *x, int64_t length)
	Adds a UTF-8 encoded bytestring value x with a given length to the accumulated data.
void	string (const std::string &x)
	Adds a UTF-8 encoded bytestring x in STL format to the accumulated data.
void	beginlist ()
	Begins building a nested list.
void	endlist ()
	Ends a nested list.
void	begintuple (int64_t numfields)
	Begins building a tuple with a fixed number of fields.
void	index (int64_t index)
	Sets the pointer to a given tuple field index; the next command will fill that slot.
void	endtuple ()
	Ends a tuple.
void	beginrecord ()
	Begins building a record without a name.
void	beginrecord_fast (const char *name)
	Begins building a record with a name.
void	beginrecord_check (const char *name)
	Begins building a record with a name.
void	beginrecord_check (const std::string &name)
	Begins building a record with a name.
void	field_fast (const char *key)
	Sets the pointer to a given record field key; the next command will fill that slot.
void	field_check (const char *key)
	Sets the pointer to a given record field key; the next command will fill that slot.
void	field_check (const std::string &key)
	Sets the pointer to a given record field key; the next command will fill that slot.
void	endrecord ()
	Ends a record.
const BuilderPtr	builder () const
void	builder_update (BuilderPtr builder)
void	maybeupdate (const BuilderPtr builder)
	Internal function to replace the root node of the ArrayBuilder's Builder tree with a new root.

Detailed Description

User interface to the Builder system: the ArrayBuilder is a fixed reference while the Builder subclass instances change in response to accumulating data.

Constructor & Destructor Documentation

ArrayBuilder()

ArrayBuilder

(

const BuilderOptions &

options

)

Creates an ArrayBuilder from a full set of parameters.

Parameters

options

Configuration options for building an array; these are passed to every Builder's constructor.

Member Function Documentation

beginlist()

void beginlist

(

)

Begins building a nested list.

beginrecord()

void beginrecord

(

)

Begins building a record without a name.

See beginrecord_fast and beginrecord_check.

beginrecord_check() [1/2]

void beginrecord_check

(

const char *

name

)

Begins building a record with a name.

Parameters

name	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.

In the _check version of this method, a string comparison is performed every time it is called to verify that the name matches a stored name.

See beginrecord and beginrecord_fast.

beginrecord_check() [2/2]

void beginrecord_check

(

const std::string &

name

)

Begins building a record with a name.

Parameters

name	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.

In the _check version of this method, a string comparison is performed every time it is called to verify that the name matches a stored name.

See beginrecord and beginrecord_fast.

beginrecord_fast()

void beginrecord_fast

(

const char *

name

)

Begins building a record with a name.

Parameters

name	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.

In the _fast version of this method, a string comparison is not performed: the same pointer is assumed to have the same value each time (safe for string literals).

See beginrecord and beginrecord_check.

begintuple()

void begintuple

(

int64_t

numfields

)

Begins building a tuple with a fixed number of fields.

boolean()

void boolean

(

bool

x

)

Adds a boolean value x to the accumulated data.

builder()

const BuilderPtr builder ( ) const

inline

builder_update()

void builder_update ( BuilderPtr builder )

inline

bytestring() [1/3]

void bytestring

(

const char *

x

)

Adds an unencoded, null-terminated bytestring value x to the accumulated data.

bytestring() [2/3]

void bytestring	(	const char *	x,
		int64_t	length )

Adds an unencoded bytestring value x with a given length to the accumulated data.

The string does not need to be null-terminated.

bytestring() [3/3]

void bytestring

(

const std::string &

x

)

Adds an unencoded bytestring x in STL format to the accumulated data.

clear()

void clear

(

)

Removes all accumulated data without resetting the type knowledge.

complex()

void complex

(

std::complex< double >

x

)

Adds a complex value x to the accumulated data.

datetime()

void datetime	(	int64_t	x,
		const std::string &	unit )

Adds a datetime value x to the accumulated data.

endlist()

void endlist

(

)

Ends a nested list.

endrecord()

void endrecord

(

)

Ends a record.

endtuple()

void endtuple

(

)

Ends a tuple.

field_check() [1/2]

void field_check

(

const char *

key

)

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

In the _check version of this method, a string comparison is performed every time it is called to verify that the key matches a stored key. See field_fast.

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.

field_check() [2/2]

void field_check

(

const std::string &

key

)

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

In the _check version of this method, a string comparison is performed every time it is called to verify that the key matches a stored key. See field_fast.

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.

field_fast()

void field_fast

(

const char *

key

)

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

In the _fast version of this method, a string comparison is not performed: the same pointer is assumed to have the same value each time (safe for string literals). See field_check.

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.

index()

void index

(

int64_t

index

)

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

integer()

void integer

(

int64_t

x

)

Adds an integer value x to the accumulated data.

length()

int64_t length

(

)

const

Current length of the accumulated array.

maybeupdate()

void maybeupdate

(

const BuilderPtr

builder

)

Internal function to replace the root node of the ArrayBuilder's Builder tree with a new root.

null()

void null

(

)

Adds a null value to the accumulated data.

real()

void real

(

double

x

)

Adds a real value x to the accumulated data.

string() [1/3]

void string

(

const char *

x

)

Adds a UTF-8 encoded, null-terminated bytestring value x to the accumulated data.

string() [2/3]

void string	(	const char *	x,
		int64_t	length )

Adds a UTF-8 encoded bytestring value x with a given length to the accumulated data.

The string does not need to be null-terminated.

string() [3/3]

void string

(

const std::string &

x

)

Adds a UTF-8 encoded bytestring x in STL format to the accumulated data.

timedelta()

void timedelta	(	int64_t	x,
		const std::string &	unit )

Adds a timedelta value x to the accumulated data.

to_buffers()

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

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

---

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

• /home/runner/work/awkward/awkward/awkward-cpp/include/awkward/builder/ArrayBuilder.h