Awkward Array: ArrayBuilder Class Reference

Loading...
Searching...
No Matches
Public Member Functions | List of all members
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:

- include/awkward/builder/ArrayBuilder.h