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:
BitMaskedForm ByteMaskedForm EmptyForm IndexedForm IndexedOptionForm ListForm ListOffsetForm NumpyForm RecordForm RegularForm UnionForm UnmaskedForm VirtualForm

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. More...
 
virtual ~Form ()
 Empty destructor; required for some C++ reason. More...
 
virtual const TypePtr type (const util::TypeStrs &typestrs) const =0
 High-level Type describing this Form. More...
 
virtual void tojson_part (ToJson &builder, bool verbose) const =0
 Internal function to produce a JSON representation one node at a time. More...
 
virtual const FormPtr shallow_copy () const =0
 Copies this node without copying any nodes hierarchically nested within it. More...
 
virtual const FormPtr with_form_key (const FormKey &form_key) const =0
 Copies this node, adding or replacing a form_key. More...
 
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. More...
 
bool form_key_equals (const FormKey &other_form_key) const
 Returns true if this Form has the same form_key as the other. More...
 
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. More...
 
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. More...
 
virtual bool purelist_isregular () const =0
 Returns true if all nested lists down to the first RecordForm are RegularForm nodes; false otherwise. More...
 
virtual int64_t purelist_depth () const =0
 The list-depth of this array, not counting any contained within a RecordForm. More...
 
virtual bool dimension_optiontype () const =0
 Returns true if this dimension has option-type; false otherwise. More...
 
const FormKey form_key () const
 An optional string associated with this Form, usually specifying where an array may be fetched. More...
 
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). More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
virtual bool haskey (const std::string &key) const =0
 Returns true if the array contains a RecordForm with the specified key; false otherwise. More...
 
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. More...
 
virtual const std::string tostring () const
 Returns a string representation of this Form (tojson with pretty = true and verbose = false). More...
 
virtual const std::string tojson (bool pretty, bool verbose) const
 Returns a JSON representation of this array. More...
 
bool has_identities () const
 Returns true if the corresponding array has associated Identities. More...
 
const util::Parameters parameters () const
 String-to-JSON map that augments the meaning of this Form. More...
 
const std::string parameter (const std::string &key) const
 Get one parameter from this Form. More...
 
void identities_tojson (ToJson &builder, bool verbose) const
 Internal function for adding identities in tojson. More...
 
void parameters_tojson (ToJson &builder, bool verbose) const
 Internal function for adding parameters in tojson. More...
 
void form_key_tojson (ToJson &builder, bool verbose) const
 Internal function for adding form_key in tojson. More...
 
virtual const FormPtr getitem_range () const
 Returns the Form that would result from a range-slice. More...
 
virtual const FormPtr getitem_field (const std::string &key) const =0
 Returns the Form that would result from a field-slice. More...
 
virtual const FormPtr getitem_fields (const std::vector< std::string > &keys) const =0
 Returns the Form that would result from a fields-slice. More...
 

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. More...
 
util::Parameters parameters_
 See parameters. More...
 
FormKey form_key_
 See form_key. More...
 

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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ dimension_optiontype()

virtual bool dimension_optiontype ( ) const
pure virtual

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

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

◆ 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_identitiesIf true, Forms are not equal unless they both has_identities.
check_parametersIf true, Forms are not equal unless they have the same parameters.
check_form_keyIf true, Forms are not equal unless they have the same form_key.
compatibility_checkIf 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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().

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ shallow_copy()

virtual const FormPtr shallow_copy ( ) const
pure virtual

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

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

◆ tojson()

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

Returns a JSON representation of this array.

Parameters
prettyIf 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 IndexedOptionForm, NumpyForm, BitMaskedForm, RecordForm, UnionForm, ByteMaskedForm, VirtualForm, ListForm, IndexedForm, ListOffsetForm, RegularForm, UnmaskedForm, and EmptyForm.

◆ 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
typestrsA mapping from "__record__" parameters to string representations of those types, to override the derived strings.

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

◆ with_form_key()

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

Member Data Documentation

◆ form_key_

FormKey form_key_
protected

See form_key.

◆ has_identities_

bool has_identities_
protected

◆ parameters_

util::Parameters parameters_
protected

See parameters.


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