Awkward Array: Form Class Reference

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
Form Class Referenceabstract

Abstract superclass of all array node forms, which expresses the nesting structure without any large `Index` or data buffers. More...

`#include <Content.h>`

Inheritance diagram for Form:

## Public Member Functions
| Form (bool has_identities, const util::Parameters &parameters, const FormKey &form_key)
| Called by subclass constructors; assigns has_identities, parameters, and form_key upon construction.
virtual | ~Form ()
| Empty destructor; required for some C++ reason.
virtual const TypePtr | type (const util::TypeStrs &typestrs) const =0
| High-level Type describing this Form.
virtual void | tojson_part (ToJson &builder, bool verbose) const =0
| Internal function to produce a JSON representation one node at a time.
virtual const FormPtr | shallow_copy () const =0
| Copies this node without copying any nodes hierarchically nested within it.
virtual const FormPtr | with_form_key (const FormKey &form_key) const =0
| Copies this node, adding or replacing a form_key.
virtual bool | equal (const FormPtr &other, bool check_identities, bool check_parameters, bool check_form_key, bool compatibility_check) const =0
| Returns `true` if this Form is equal to the other Form; `false` otherwise.
bool | form_key_equals (const FormKey &other_form_key) const
| Returns `true` if this Form has the same form_key as the other.
virtual const std::string | purelist_parameter (const std::string &key) const =0
| The parameter associated with `key` at the first level that has a non-null value, descending only as deep as the first RecordForm.
bool | parameter_equals (const std::string &key, const std::string &value) const
| Returns `true` if the parameter associated with `key` exists and is equal to `value`; `false` otherwise.
virtual bool | purelist_isregular () const =0
| Returns `true` if all nested lists down to the first RecordForm are RegularForm nodes; `false` otherwise.
virtual int64_t | purelist_depth () const =0
| The list-depth of this array, not counting any contained within a RecordForm.
virtual bool | dimension_optiontype () const =0
| Returns `true` if this dimension has option-type; `false` otherwise.
const FormKey | form_key () const
| An optional string associated with this Form, usually specifying where an array may be fetched.
virtual const std::pair< int64_t, int64_t > | minmax_depth () const =0
| Returns (a) the minimum list-depth and (b) the maximum list-depth of the array, which can differ if this array "branches" (differs when followed through different fields of a RecordForm or UnionForm).
virtual const std::pair< bool, int64_t > | branch_depth () const =0
| Returns (a) whether the list-depth of this array "branches," or differs when followed through different fields of a RecordForm or UnionForm and (b) the minimum list-depth.
virtual int64_t | numfields () const =0
| The number of fields in the first nested tuple or records or `-1` if this array does not contain a RecordForm.
virtual int64_t | fieldindex (const std::string &key) const =0
| The position of a tuple or record key name if this array contains a RecordForm.
virtual const std::string | key (int64_t fieldindex) const =0
| The record name associated with a given field index or the tuple index as a string (e.g. `"0"`, `"1"`, `"2"`) if a tuple.
virtual bool | haskey (const std::string &key) const =0
| Returns `true` if the array contains a RecordForm with the specified `key`; `false` otherwise.
virtual const std::vector< std::string > | keys () const =0
| A list of RecordArray keys or an empty list if this array does not contain a RecordArray.
virtual bool | istuple () const =0
| Returns `true` if the outermost RecordArray is a tuple.
virtual const std::string | tostring () const
| Returns a string representation of this Form (tojson with `pretty = true` and `verbose = false`).
virtual const std::string | tojson (bool pretty, bool verbose) const
| Returns a JSON representation of this array.
bool | has_identities () const
| Returns `true` if the corresponding array has associated `Identities`.
const util::Parameters | parameters () const
| String-to-JSON map that augments the meaning of this Form.
const std::string | parameter (const std::string &key) const
| Get one parameter from this Form.
void | identities_tojson (ToJson &builder, bool verbose) const
| Internal function for adding identities in tojson.
void | parameters_tojson (ToJson &builder, bool verbose) const
| Internal function for adding parameters in tojson.
void | form_key_tojson (ToJson &builder, bool verbose) const
| Internal function for adding form_key in tojson.
virtual const FormPtr | getitem_range () const
| Returns the Form that would result from a range-slice.
virtual const FormPtr | getitem_field (const std::string &key) const =0
| Returns the Form that would result from a field-slice.
virtual const FormPtr | getitem_fields (const std::vector< std::string > &keys) const =0
| Returns the Form that would result from a fields-slice.

## Static Public Member Functions
static FormPtr | fromnumpy (char kind, int64_t itemsize, const std::vector< int64_t > &inner_shape)
static FormPtr | fromjson (const std::string &data)

## Protected Attributes
bool | has_identities_
| See has_identities.
util::Parameters | parameters_
| See parameters.
FormKey | form_key_
| See form_key.

## Detailed Description

Abstract superclass of all array node forms, which expresses the nesting structure without any large `Index` or data buffers.

Forms may be thought of as low-level types, whereas Type is a high-level type. There is a one-to-many relationship from Type to Form.

## Constructor & Destructor Documentation

## ◆ Form()

Form | ( | bool | has_identities,
|  | const util::Parameters & | parameters,
|  | const FormKey & | form_key
| ) |  |

Called by subclass constructors; assigns has_identities, parameters, and form_key upon construction.

## ◆ ~Form()

virtual ~Form | ( |  | ) |
| inlinevirtual

Empty destructor; required for some C++ reason.

## Member Function Documentation

## ◆ branch_depth()

virtual const std::pair< bool, int64_t > branch_depth | ( |  | ) | const
| pure virtual

Returns (a) whether the list-depth of this array "branches," or differs when followed through different fields of a RecordForm or UnionForm and (b) the minimum list-depth.

If the array does not contain any records or heterogeneous data, the `first` element is always `true` and the `second` is simply the depth.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ dimension_optiontype()

virtual bool dimension_optiontype | ( |  | ) | const
| pure virtual

Returns `true` if this dimension has option-type; `false` otherwise.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ equal()

virtual bool equal | ( | const FormPtr & | other,
|  | bool | check_identities,
|  | bool | check_parameters,
|  | bool | check_form_key,
|  | bool | compatibility_check
| ) |  | const
| pure virtual

Returns `true` if this Form is equal to the other Form; `false` otherwise.

Parameters

  check_identities | If `true`, Forms are not equal unless they both has_identities.
  check_parameters | If `true`, Forms are not equal unless they have the same parameters.
  check_form_key | If `true`, Forms are not equal unless they have the same form_key.
  compatibility_check | If `true`, this is part of a compatibility check between an expected Form (`this`) and a generated array's Form (`other`). When the expected Form is a VirtualForm, it's allowed to be less specific than the `other` VirtualForm.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ fieldindex()

virtual int64_t fieldindex | ( | const std::string & | key | ) | const
| pure virtual

The position of a tuple or record key name if this array contains a RecordForm.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ form_key()

const FormKey form_key | ( |  | ) | const

An optional string associated with this Form, usually specifying where an array may be fetched.

## ◆ form_key_equals()

bool form_key_equals | ( | const FormKey & | other_form_key | ) | const

Returns `true` if this Form has the same form_key as the other.

## ◆ form_key_tojson()

void form_key_tojson | ( | ToJson & | builder,
|  | bool | verbose
| ) |  | const

Internal function for adding form_key in tojson.

Must be called between `builder.beginrecord()` and `builder.endrecord()`.

## ◆ fromjson()

static FormPtr fromjson | ( | const std::string & | data | ) |
| static

## ◆ fromnumpy()

static FormPtr fromnumpy | ( | char | kind,
|  | int64_t | itemsize,
|  | const std::vector< int64_t > & | inner_shape
| ) |  |
| static

## ◆ getitem_field()

virtual const FormPtr getitem_field | ( | const std::string & | key | ) | const
| pure virtual

Returns the Form that would result from a field-slice.

Matches the operation of Content::getitem_field.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ getitem_fields()

virtual const FormPtr getitem_fields | ( | const std::vector< std::string > & | keys | ) | const
| pure virtual

Returns the Form that would result from a fields-slice.

Matches the operation of Content::getitem_fields.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ getitem_range()

virtual const FormPtr getitem_range | ( |  | ) | const
| virtual

Returns the Form that would result from a range-slice.

Matches the operation of Content::getitem_range.

Reimplemented in BitMaskedForm.

## ◆ has_identities()

bool has_identities | ( |  | ) | const

Returns `true` if the corresponding array has associated `Identities`.

## ◆ haskey()

virtual bool haskey | ( | const std::string & | key | ) | const
| pure virtual

Returns `true` if the array contains a RecordForm with the specified `key`; `false` otherwise.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ identities_tojson()

void identities_tojson | ( | ToJson & | builder,
|  | bool | verbose
| ) |  | const

Internal function for adding identities in tojson.

Must be called between `builder.beginrecord()` and `builder.endrecord()`.

## ◆ istuple()

virtual bool istuple | ( |  | ) | const
| pure virtual

Returns `true` if the outermost RecordArray is a tuple.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ key()

virtual const std::string key | ( | int64_t | fieldindex | ) | const
| pure virtual

The record name associated with a given field index or the tuple index as a string (e.g. `"0"`, `"1"`, `"2"`) if a tuple.

Raises an error if the array does not contain a RecordForm.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ keys()

virtual const std::vector< std::string > keys | ( |  | ) | const
| pure virtual

A list of RecordArray keys or an empty list if this array does not contain a RecordArray.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ minmax_depth()

virtual const std::pair< int64_t, int64_t > minmax_depth | ( |  | ) | const
| pure virtual

Returns (a) the minimum list-depth and (b) the maximum list-depth of the array, which can differ if this array "branches" (differs when followed through different fields of a RecordForm or UnionForm).

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ numfields()

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

The number of fields in the first nested tuple or records or `-1` if this array does not contain a RecordForm.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ parameter()

const std::string parameter | ( | const std::string & | key | ) | const

Get one parameter from this Form.

If the `key` does not exist, this function returns `"null"`.

Keys are simple strings, but values are JSON-encoded strings. For this reason, values that represent single strings are double-quoted: e.g. `"\"actual_value\""`.

## ◆ parameter_equals()

bool parameter_equals | ( | const std::string & | key,
|  | const std::string & | value
| ) |  | const

Returns `true` if the parameter associated with `key` exists and is equal to `value`; `false` otherwise.

Keys are simple strings, but values are JSON-encoded strings. For this reason, values that represent single strings are double-quoted: e.g. `"\"actual_value\""`.

Equality is checked at the level of JSON DOMs. The `value` does not need to be exactly the same string; it needs to have equivalent JSON value.

## ◆ parameters()

const util::Parameters parameters | ( |  | ) | const

String-to-JSON map that augments the meaning of this Form.

Keys are simple strings, but values are JSON-encoded strings. For this reason, values that represent single strings are double-quoted: e.g. `"\"actual_value\""`.

## ◆ parameters_tojson()

void parameters_tojson | ( | ToJson & | builder,
|  | bool | verbose
| ) |  | const

Internal function for adding parameters in tojson.

Must be called between `builder.beginrecord()` and `builder.endrecord()`.

## ◆ purelist_depth()

virtual int64_t purelist_depth | ( |  | ) | const
| pure virtual

The list-depth of this array, not counting any contained within a RecordForm.

If this array contains a UnionForm with different depths, the return value is `-1`.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ purelist_isregular()

virtual bool purelist_isregular | ( |  | ) | const
| pure virtual

Returns `true` if all nested lists down to the first RecordForm are RegularForm nodes; `false` otherwise.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ purelist_parameter()

virtual const std::string purelist_parameter | ( | const std::string & | key | ) | const
| pure virtual

The parameter associated with `key` at the first level that has a non-null value, descending only as deep as the first RecordForm.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ shallow_copy()

virtual const FormPtr shallow_copy | ( |  | ) | const
| pure virtual

Copies this node without copying any nodes hierarchically nested within it.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ tojson()

virtual const std::string tojson | ( | bool | pretty,
|  | bool | verbose
| ) |  | const
| virtual

Returns a JSON representation of this array.

Parameters

  pretty | If `true`, add spacing to make the JSON human-readable. If `false`, return a compact representation.

Reimplemented in NumpyForm.

## ◆ tojson_part()

virtual void tojson_part | ( | ToJson & | builder,
|  | bool | verbose
| ) |  | const
| pure virtual

Internal function to produce a JSON representation one node at a time.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ tostring()

virtual const std::string tostring | ( |  | ) | const
| virtual

Returns a string representation of this Form (tojson with `pretty = true` and `verbose = false`).

Reimplemented in NumpyForm.

## ◆ type()

virtual const TypePtr type | ( | const util::TypeStrs & | typestrs | ) | const
| pure virtual

High-level Type describing this Form.

Parameters

  typestrs | A mapping from `"__record__"` parameters to string representations of those types, to override the derived strings.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## ◆ with_form_key()

virtual const FormPtr with_form_key | ( | const FormKey & | form_key | ) | const
| pure virtual

Copies this node, adding or replacing a form_key.

Implemented in BitMaskedForm, ByteMaskedForm, EmptyForm, IndexedForm, IndexedOptionForm, ListForm, ListOffsetForm, NumpyForm, RecordForm, RegularForm, UnionForm, UnmaskedForm, and VirtualForm.

## Member Data Documentation

## ◆ form_key_

FormKey form_key_
| protected

See form_key.

## ◆ has_identities_

bool has_identities_
| protected

See has_identities.

## ◆ parameters_

util::Parameters parameters_
| protected

See parameters.

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

- include/awkward/Content.h