Awkward Array: IdentitiesOf< T > Class Template Reference

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

## 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.
| 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.
const std::shared_ptr< T > | ptr () const
| Reference-counted pointer to the array buffer.
kernel::lib | ptr_lib () const override
| The Kernel Library that ptr uses.
T * | data () const
| Raw pointer to the beginning of data (i.e. offset accounted for).
const std::string | classname () const override
| User-friendly name of this class: `"Identities32"` or `"Identities64"`.
const std::string | identity_at (int64_t at) const override
| Return a string representing an identity tuple at `where`.
const IdentitiesPtr | to64 () const override
| Converts this Identities to an `Identities64`.
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.
const IdentitiesPtr | getitem_range_nowrap (int64_t start, int64_t stop) const override
| Subinterval of this array, without handling negative indexing or bounds-checking.
void | nbytes_part (std::map< size_t, int64_t > &largest) const override
| Internal function used to calculate Content::nbytes.
const IdentitiesPtr | shallow_copy () const override
| Copies this Identities node without copying its buffer.
const IdentitiesPtr | deep_copy () const override
| Copies this Identities node and all the data in its buffer.
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.
const IdentitiesPtr | withfieldloc (const FieldLoc &fieldloc) const override
| Returns this Identities node with a different fieldloc.
int64_t | value (int64_t row, int64_t col) const override
| Returns the integer value of the two-dimensional array at `row` and `col`.
const IdentitiesPtr | copy_to (kernel::lib ptr_lib) const override
| Moves the identity ptr buffer of the array between devices.
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.
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.
const IdentitiesPtr | getitem_range (int64_t start, int64_t stop) const
| Subinterval of this array, handling negative indexing and bounds-checking like Python.
bool | referentially_equal (const IdentitiesPtr &other) const override
| Returns `true` if this Identities has all the same buffers and parameters as `other`; `false` otherwise.
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.
virtual | ~Identities ()
| Virtual destructor acts as a first non-inline virtual function that determines a specific translation unit in which vtable shall be emitted.
const Ref | ref () const
| A globally unique reference to this set of identities.
const FieldLoc | fieldloc () const
| A list of integer-string pairs indicating the positions of all tuple/record field indicators within the identity tuple.
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.
const int64_t | width () const
| The number of integers in each identity tuple.
const int64_t | length () const
| The number of identities in the array.
virtual kernel::lib | ptr_lib () const =0
| The Kernel Library that ptr uses.
virtual const std::string | classname () const =0
| User-friendly name of this class: `"Identities32"` or `"Identities64"`.
virtual const std::string | identity_at (int64_t where) const =0
| Return a string representing an identity tuple at `where`.
virtual const IdentitiesPtr | to64 () const =0
| Converts this Identities to an `Identities64`.
virtual const std::string | tostring_part (const std::string &indent, const std::string &pre, const std::string &post) const =0
| Internal function to build an output string for tostring.
virtual const IdentitiesPtr | getitem_range_nowrap (int64_t start, int64_t stop) const =0
| Subinterval of this array, without handling negative indexing or bounds-checking.
virtual void | nbytes_part (std::map< size_t, int64_t > &largest) const =0
| Internal function used to calculate Content::nbytes.
virtual const IdentitiesPtr | shallow_copy () const =0
| Copies this Identities node without copying its buffer.
virtual const IdentitiesPtr | deep_copy () const =0
| Copies this Identities node and all the data in its buffer.
virtual const IdentitiesPtr | getitem_carry_64 (const Index64 &carry) const =0
| Returns an Identities array with elements filtered, rearranged, and possibly duplicated by the `carry` array of integers.
virtual const IdentitiesPtr | withfieldloc (const FieldLoc &fieldloc) const =0
| Returns this Identities node with a different fieldloc.
virtual int64_t | value (int64_t row, int64_t col) const =0
| Returns the integer value of the two-dimensional array at `row` and `col`.
virtual const IdentitiesPtr | copy_to (kernel::lib ptr_lib) const =0
| Moves the identity ptr buffer of the array between devices.
const std::string | tostring () const
| Returns a string representation of this array (multi-line XML).
virtual bool | referentially_equal (const IdentitiesPtr &other) const =0
| Returns `true` if this Identities has all the same buffers and parameters as `other`; `false` otherwise.

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

## 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:

- `Identities32`, which is `IdentitiesOf<int32_t>`
- `Identities64`, which is `IdentitiesOf<int64_t>`

## 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

  ref | A globally unique reference to this set of identities.
  fieldloc | A list of integer-string pairs indicating the positions of all tuple/record field indicators within the identity tuple.
  offset | 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.
  width | The number of integers in each identity tuple.
  length | The number of identities in the array.
  ptr | Reference-counted pointer to the array buffer.
  Choose | the 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

  largest | The 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

  other | The 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

  indent | Indentation depth as a string of spaces.
  pre | Prefix string, usually an opening XML tag.
  post | Postfix 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:

- include/awkward/Identities.h