IdentitiesOf< T > Class Template Reference

A contiguous, two-dimensional array of integers and a list of strings used to represent a path from the root of an array structure to each item in an array. More...

#include <Identities.h>

Inheritance diagram for IdentitiesOf< T >:
Identities

Public Member Functions

 IdentitiesOf (const Ref ref, const FieldLoc &fieldloc, int64_t offset, int64_t width, int64_t length, const std::shared_ptr< T > ptr, kernel::lib ptr_lib=kernel::lib::cpu)
 Creates an IdentitiesOf from a full set of parameters. More...
 
 IdentitiesOf (const Ref ref, const FieldLoc &fieldloc, int64_t width, int64_t length, kernel::lib ptr_lib=kernel::lib::cpu)
 Allocates a new array buffer with a given ref, fieldloc, length and width. More...
 
const std::shared_ptr< T > ptr () const
 Reference-counted pointer to the array buffer. More...
 
kernel::lib ptr_lib () const override
 The Kernel Library that ptr uses. More...
 
T * data () const
 Raw pointer to the beginning of data (i.e. offset accounted for). More...
 
const std::string classname () const override
 User-friendly name of this class: "Identities32" or "Identities64". More...
 
const std::string identity_at (int64_t at) const override
 Return a string representing an identity tuple at where. More...
 
const IdentitiesPtr to64 () const override
 Converts this Identities to an Identities64. More...
 
const std::string tostring_part (const std::string &indent, const std::string &pre, const std::string &post) const override
 Internal function to build an output string for tostring. More...
 
const IdentitiesPtr getitem_range_nowrap (int64_t start, int64_t stop) const override
 Subinterval of this array, without handling negative indexing or bounds-checking. More...
 
void nbytes_part (std::map< size_t, int64_t > &largest) const override
 Internal function used to calculate Content::nbytes. More...
 
const IdentitiesPtr shallow_copy () const override
 Copies this Identities node without copying its buffer. More...
 
const IdentitiesPtr deep_copy () const override
 Copies this Identities node and all the data in its buffer. More...
 
const IdentitiesPtr getitem_carry_64 (const Index64 &carry) const override
 Returns an Identities array with elements filtered, rearranged, and possibly duplicated by the carry array of integers. More...
 
const IdentitiesPtr withfieldloc (const FieldLoc &fieldloc) const override
 Returns this Identities node with a different fieldloc. More...
 
int64_t value (int64_t row, int64_t col) const override
 Returns the integer value of the two-dimensional array at row and col. More...
 
const IdentitiesPtr copy_to (kernel::lib ptr_lib) const override
 Moves the identity ptr buffer of the array between devices. More...
 
const std::vector< T > getitem_at (int64_t at) const
 Returns the element at a given position in the array, handling negative indexing and bounds-checking like Python. More...
 
const std::vector< T > getitem_at_nowrap (int64_t at) const
 Returns the element at a given position in the array, without handling negative indexing or bounds-checking. More...
 
const IdentitiesPtr getitem_range (int64_t start, int64_t stop) const
 Subinterval of this array, handling negative indexing and bounds-checking like Python. More...
 
bool referentially_equal (const IdentitiesPtr &other) const override
 Returns true if this Identities has all the same buffers and parameters as other; false otherwise. More...
 
- Public Member Functions inherited from Identities
 Identities (const Ref ref, const FieldLoc &fieldloc, int64_t offset, int64_t width, int64_t length)
 Called by all subclass constructors; assigns ref, fieldloc, offset, width, and length upon construction. More...
 
virtual ~Identities ()
 Virtual destructor acts as a first non-inline virtual function that determines a specific translation unit in which vtable shall be emitted. More...
 
const Ref ref () const
 A globally unique reference to this set of identities. More...
 
const FieldLoc fieldloc () const
 A list of integer-string pairs indicating the positions of all tuple/record field indicators within the identity tuple. More...
 
const int64_t offset () const
 Location of item zero in the buffer, relative to ptr, measured in the number of elements. We keep this information in two parameters (ptr and offset) rather than moving ptr so that ptr can be reference counted among all arrays that use the same buffer. More...
 
const int64_t width () const
 The number of integers in each identity tuple. More...
 
const int64_t length () const
 The number of identities in the array. More...
 
const std::string tostring () const
 Returns a string representation of this array (multi-line XML). More...
 

Additional Inherited Members

- Public Types inherited from Identities
using Ref = int64_t
 Identities reference type (64-bit integer). More...
 
using FieldLoc = std::vector< std::pair< int64_t, std::string > >
 Identities field location type (integer-string pairs). More...
 
- Static Public Member Functions inherited from Identities
static Ref newref ()
 Returns a new Identities reference that is globally unique in the current process. More...
 
static IdentitiesPtr none ()
 A constant, empty Identities pointer (nullptr). More...
 
- Protected Attributes inherited from Identities
const Ref ref_
 See ref. More...
 
const FieldLoc fieldloc_
 See fieldloc. More...
 
int64_t offset_
 See offset. More...
 
int64_t width_
 See width. More...
 
int64_t length_
 See length. More...
 

Detailed Description

template<typename T>
class awkward::IdentitiesOf< T >

A contiguous, two-dimensional array of integers and a list of strings used to represent a path from the root of an array structure to each item in an array.

A single value's identity is equivalent to a tuple of integers and strings:

(999, "muons", 1, "pt")

which corresponds to the "getitem" path from the root of the array to that value:

array[999, "muons", 1, "pt"]

The fieldloc is a set of integer-string pairs, such as

[(1, "muons"), (3, "pt")]

in the above example. The identities array is two-dimensional so that a single value can be an array, such as

[999, 1]

in the above example.

The Identities superclass abstracts over templated specializations:

Constructor & Destructor Documentation

◆ IdentitiesOf() [1/2]

IdentitiesOf ( const Ref  ref,
const FieldLoc fieldloc,
int64_t  offset,
int64_t  width,
int64_t  length,
const std::shared_ptr< T >  ptr,
kernel::lib  ptr_lib = kernel::lib::cpu 
)

Creates an IdentitiesOf from a full set of parameters.

Parameters
refA globally unique reference to this set of identities.
fieldlocA list of integer-string pairs indicating the positions of all tuple/record field indicators within the identity tuple.
offsetLocation of item zero in the buffer, relative to ptr, measured in the number of elements. We keep this information in two parameters (ptr and offset) rather than moving ptr so that ptr can be reference counted among all arrays that use the same buffer.
widthThe number of integers in each identity tuple.
lengthThe number of identities in the array.
ptrReference-counted pointer to the array buffer.
Choosethe Kernel Library for this array, default:= cpu_kernels.

◆ IdentitiesOf() [2/2]

IdentitiesOf ( const Ref  ref,
const FieldLoc fieldloc,
int64_t  width,
int64_t  length,
kernel::lib  ptr_lib = kernel::lib::cpu 
)

Allocates a new array buffer with a given ref, fieldloc, length and width.

Member Function Documentation

◆ classname()

const std::string classname ( ) const
overridevirtual

User-friendly name of this class: "Identities32" or "Identities64".

Implements Identities.

◆ copy_to()

const IdentitiesPtr copy_to ( kernel::lib  ptr_lib) const
overridevirtual

Moves the identity ptr buffer of the array between devices.

Returns a std::shared_ptr<IdentitiesOf> which is, by default, allocated on the first device(device [0])

Note
This function has not been implemented to handle Multi-GPU setups

Implements Identities.

◆ data()

T* data ( ) const

Raw pointer to the beginning of data (i.e. offset accounted for).

◆ deep_copy()

const IdentitiesPtr deep_copy ( ) const
overridevirtual

Copies this Identities node and all the data in its buffer.

See also shallow_copy.

Implements Identities.

◆ getitem_at()

const std::vector<T> getitem_at ( int64_t  at) const

Returns the element at a given position in the array, handling negative indexing and bounds-checking like Python.

The first item in the array is at 0, the second at 1, the last at -1, the penultimate at -2, etc.

◆ getitem_at_nowrap()

const std::vector<T> getitem_at_nowrap ( int64_t  at) const

Returns the element at a given position in the array, without handling negative indexing or bounds-checking.

◆ getitem_carry_64()

const IdentitiesPtr getitem_carry_64 ( const Index64 carry) const
overridevirtual

Returns an Identities array with elements filtered, rearranged, and possibly duplicated by the carry array of integers.

The output has the same length as the carry index, not the array that is being manipulated. For each item i in carry, the output is array[index[i]].

This operation is called take in NumPy and Arrow, although this carry is a low-level function that does not handle negative indexes and is not exposed to the Python layer. It is used by many operations to pass filters/rearrangements/duplications from one typed array node to another without knowing the latter's type.

Taking getitem_at_nowrap as a function from integers to the array's item type, A: [0, len(a)) → T, and the carry array's Index64::getitem_at_nowrap as a function C: [0, len(c)) → [0, len(a)), this method represents function composition, A ∘ C: [0, len(c)) → T.

Implements Identities.

◆ getitem_range()

const IdentitiesPtr getitem_range ( int64_t  start,
int64_t  stop 
) const

Subinterval of this array, handling negative indexing and bounds-checking like Python.

The first item in the array is at 0, the second at 1, the last at -1, the penultimate at -2, etc.

Ranges beyond the array are not an error; they are trimmed to start = 0 on the left and stop = length() - 1 on the right.

This operation only affects the node metadata; its calculation time does not scale with the size of the array.

◆ getitem_range_nowrap()

const IdentitiesPtr getitem_range_nowrap ( int64_t  start,
int64_t  stop 
) const
overridevirtual

Subinterval of this array, without handling negative indexing or bounds-checking.

This operation only affects the node metadata; its calculation time does not scale with the size of the array.

Implements Identities.

◆ identity_at()

const std::string identity_at ( int64_t  where) const
overridevirtual

Return a string representing an identity tuple at where.

Implements Identities.

◆ nbytes_part()

void nbytes_part ( std::map< size_t, int64_t > &  largest) const
overridevirtual

Internal function used to calculate Content::nbytes.

Parameters
largestThe largest range of bytes used in each reference-counted pointer (size_t).
Note
This method of accounting for overlapping buffers is insufficient: two nodes could use parts of the same buffer in which one doesn't completely overlap the other. It's not likely, but currently the calculation of Content::nbytes is an underestimate.

Implements Identities.

◆ ptr()

const std::shared_ptr<T> ptr ( ) const

Reference-counted pointer to the array buffer.

◆ ptr_lib()

kernel::lib ptr_lib ( ) const
overridevirtual

The Kernel Library that ptr uses.

Implements Identities.

◆ referentially_equal()

bool referentially_equal ( const IdentitiesPtr other) const
overridevirtual

Returns true if this Identities has all the same buffers and parameters as other; false otherwise.

Parameters
otherThe Identities to compare this with.

Implements Identities.

◆ shallow_copy()

const IdentitiesPtr shallow_copy ( ) const
overridevirtual

Copies this Identities node without copying its buffer.

See also deep_copy.

Implements Identities.

◆ to64()

const IdentitiesPtr to64 ( ) const
overridevirtual

Converts this Identities to an Identities64.

Implements Identities.

◆ tostring_part()

const std::string tostring_part ( const std::string &  indent,
const std::string &  pre,
const std::string &  post 
) const
overridevirtual

Internal function to build an output string for tostring.

Parameters
indentIndentation depth as a string of spaces.
prePrefix string, usually an opening XML tag.
postPostfix string, usually a closing XML tag and carriage return.

Implements Identities.

◆ value()

int64_t value ( int64_t  row,
int64_t  col 
) const
overridevirtual

Returns the integer value of the two-dimensional array at row and col.

Implements Identities.

◆ withfieldloc()

const IdentitiesPtr withfieldloc ( const FieldLoc fieldloc) const
overridevirtual

Returns this Identities node with a different fieldloc.

Implements Identities.


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