awkward::util Namespace Reference

Classes

struct  NameValuePair
 

Typedefs

using RecordLookup = std::vector< std::string >
 
using RecordLookupPtr = std::shared_ptr< RecordLookup >
 
using Parameters = std::map< std::string, std::string >
 
using TypeStrs = std::map< std::string, std::string >
 

Enumerations

enum  datetime_units {
  unknown = -1, Y = 1, M = 2, W = 3,
  D = 4, h = 5, m = 6, s = 7,
  ms = 8, us = 9, ns = 10, ps = 11,
  fs = 12, as = 13
}
 Valid datetime units. Different units of two datetime type Arrays will be normalized to the smallest unit (== a larger enum value). More...
 
enum  dtype {
  NOT_PRIMITIVE, boolean, int8, int16,
  int32, int64, uint8, uint16,
  uint32, uint64, float16, float32,
  float64, float128, complex64, complex128,
  complex256, datetime64, timedelta64, size
}
 NumPy dtypes that can be interpreted within Awkward C++ (only the primitive, fixed-width types). Non-native-endian types are considered NOT_PRIMITIVE. More...
 
enum  ForthError {
  none, not_ready, is_done, user_halt,
  recursion_depth_exceeded, stack_underflow, stack_overflow, read_beyond,
  seek_beyond, skip_beyond, rewind_beyond, division_by_zero,
  varint_too_big, size
}
 Exhaustive list of runtime errors possible in the ForthMachine. More...
 

Functions

const std::string format_to_units (const std::string &format)
 Convert a format string into a datetime units string. More...
 
const std::string units_to_format (dtype dt, const std::string &units, int64_t step)
 Convert a datetime units string into a format string. More...
 
template<class Mapping , class V >
std::string name (Mapping a, V value)
 
template<class Mapping >
Mapping::value_type::value_type value (Mapping a, const std::string &name)
 
std::tuple< std::string, int64_t > datetime_data (const std::string &format)
 
double scale_from_units (const std::string &format, uint64_t index)
 
dtype name_to_dtype (const std::string &name)
 Returns the name associated with a given dtype. More...
 
const std::string dtype_to_name (dtype dt)
 Returns the name associated with a given dtype. More...
 
dtype format_to_dtype (const std::string &format, int64_t itemsize)
 Convert a NumPy format string and itemsize into a dtype enum. More...
 
const std::string dtype_to_format (dtype dt, const std::string &format="")
 Convert a dtype enum into a NumPy format string. More...
 
int64_t dtype_to_itemsize (dtype dt)
 Convert a dtype enum into an itemsize. More...
 
bool is_integer (dtype dt)
 True if the dtype is a non-boolean integer (signed or unsigned). More...
 
bool is_signed (dtype dt)
 True if the dtype is a signed integer. More...
 
bool is_unsigned (dtype dt)
 True if the dtype is an unsigned integer. More...
 
bool is_real (dtype dt)
 True if the dtype is a non-complex floating point number. More...
 
bool is_complex (dtype dt)
 True if the dtype is a complex number. More...
 
void handle_error (const struct Error &err, const std::string &classname=std::string(""), const Identities *id=nullptr)
 If the Error struct contains an error message (from a cpu-kernel through the C interface), raise that error as a C++ exception. More...
 
std::string quote (const std::string &x)
 Puts quotation marks around a string and escapes the appropriate characters. More...
 
template<typename T >
IndexOf< T > make_starts (const IndexOf< T > &offsets)
 Converts an offsets index (from ListOffsetArray, for instance) into a starts index by viewing it with the last element dropped. More...
 
template<typename T >
IndexOf< T > make_stops (const IndexOf< T > &offsets)
 Converts an offsets index (from ListOffsetArray, for instance) into a stops index by viewing it with the first element dropped. More...
 
RecordLookupPtr init_recordlookup (int64_t numfields)
 Initializes a RecordLookup by assigning each element with a string representation of its field index position. More...
 
int64_t fieldindex (const RecordLookupPtr &recordlookup, const std::string &key, int64_t numfields)
 Returns the field index associated with a key, given a RecordLookup and a number of fields. More...
 
const std::string key (const RecordLookupPtr &recordlookup, int64_t fieldindex, int64_t numfields)
 Returns the key associated with a field index, given a RecordLookup and a number of fields. More...
 
bool haskey (const RecordLookupPtr &recordlookup, const std::string &key, int64_t numfields)
 Returns true if a RecordLookup has a given key; false otherwise. More...
 
const std::vector< std::string > keys (const RecordLookupPtr &recordlookup, int64_t numfields)
 Returns a given RecordLookup as keys or generate anonymous ones form a number of fields. More...
 
bool json_equals (const std::string &myvalue, const std::string &value)
 Returns true if myvalue is equal to value when interpreted as JSON. More...
 
bool parameter_equals (const Parameters &parameters, const std::string &key, const std::string &value)
 Returns true if the value associated with a key in parameters is equal to the specified value. More...
 
bool parameters_equal (const Parameters &self, const Parameters &other, bool check_all)
 Returns true if all key-value pairs in self is equal to all key-value pairs in other. More...
 
void merge_parameters (Parameters &output, const Parameters &input)
 Merges a set of input parameters with output, keeping only those that are common to all sets. More...
 
bool parameter_isstring (const Parameters &parameters, const std::string &key)
 Returns true if the parameter associated with key is a string; false otherwise. More...
 
bool parameter_isname (const Parameters &parameters, const std::string &key)
 Returns true if the parameter associated with key is a string that matches [A-Za-z_][A-Za-z_0-9]*; false otherwise. More...
 
const std::string parameter_asstring (const Parameters &parameters, const std::string &key)
 Returns the parameter associated with key as a string if parameter_isstring; raises an error otherwise. More...
 
std::string gettypestr (const Parameters &parameters, const TypeStrs &typestrs)
 Extracts a custom type string from typestrs if required by one of the parameters or an empty string if there is no match. More...
 

Variables

const std::array< const NameValuePair< datetime_units >, 14 > units_map
 

Typedef Documentation

◆ Parameters

using Parameters = std::map<std::string, std::string>

◆ RecordLookup

using RecordLookup = std::vector<std::string>

◆ RecordLookupPtr

using RecordLookupPtr = std::shared_ptr<RecordLookup>

◆ TypeStrs

using TypeStrs = std::map<std::string, std::string>

Enumeration Type Documentation

◆ datetime_units

enum datetime_units
strong

Valid datetime units. Different units of two datetime type Arrays will be normalized to the smallest unit (== a larger enum value).

Enumerator
unknown 
ms 
us 
ns 
ps 
fs 
as 

◆ dtype

enum dtype
strong

NumPy dtypes that can be interpreted within Awkward C++ (only the primitive, fixed-width types). Non-native-endian types are considered NOT_PRIMITIVE.

Enumerator
NOT_PRIMITIVE 
boolean 
int8 
int16 
int32 
int64 
uint8 
uint16 
uint32 
uint64 
float16 
float32 
float64 
float128 
complex64 
complex128 
complex256 
datetime64 
timedelta64 
size 

◆ ForthError

enum ForthError
strong

Exhaustive list of runtime errors possible in the ForthMachine.

Enumerator
none 
not_ready 
is_done 
user_halt 
recursion_depth_exceeded 
stack_underflow 
stack_overflow 
read_beyond 
seek_beyond 
skip_beyond 
rewind_beyond 
division_by_zero 
varint_too_big 
size 

Function Documentation

◆ datetime_data()

std::tuple<std::string, int64_t> awkward::util::datetime_data ( const std::string &  format)

◆ dtype_to_format()

const std::string awkward::util::dtype_to_format ( dtype  dt,
const std::string &  format = "" 
)

Convert a dtype enum into a NumPy format string.

◆ dtype_to_itemsize()

int64_t awkward::util::dtype_to_itemsize ( dtype  dt)

Convert a dtype enum into an itemsize.

◆ dtype_to_name()

const std::string awkward::util::dtype_to_name ( dtype  dt)

Returns the name associated with a given dtype.

◆ fieldindex()

int64_t awkward::util::fieldindex ( const RecordLookupPtr recordlookup,
const std::string &  key,
int64_t  numfields 
)

Returns the field index associated with a key, given a RecordLookup and a number of fields.

◆ format_to_dtype()

dtype awkward::util::format_to_dtype ( const std::string &  format,
int64_t  itemsize 
)

Convert a NumPy format string and itemsize into a dtype enum.

◆ format_to_units()

const std::string awkward::util::format_to_units ( const std::string &  format)

Convert a format string into a datetime units string.

◆ gettypestr()

std::string awkward::util::gettypestr ( const Parameters parameters,
const TypeStrs typestrs 
)

Extracts a custom type string from typestrs if required by one of the parameters or an empty string if there is no match.

◆ handle_error()

void awkward::util::handle_error ( const struct Error err,
const std::string &  classname = std::string(""),
const Identities id = nullptr 
)

If the Error struct contains an error message (from a cpu-kernel through the C interface), raise that error as a C++ exception.

Parameters
errThe Error struct from a cpu-kernel.
classnameThe name of this class to include in the error message.
idThe Identities to include in the error message.

◆ haskey()

bool awkward::util::haskey ( const RecordLookupPtr recordlookup,
const std::string &  key,
int64_t  numfields 
)

Returns true if a RecordLookup has a given key; false otherwise.

◆ init_recordlookup()

RecordLookupPtr awkward::util::init_recordlookup ( int64_t  numfields)

Initializes a RecordLookup by assigning each element with a string representation of its field index position.

For example, if numfields = 3, the return value is ["0", "1", "2"].

◆ is_complex()

bool awkward::util::is_complex ( dtype  dt)

True if the dtype is a complex number.

◆ is_integer()

bool awkward::util::is_integer ( dtype  dt)

True if the dtype is a non-boolean integer (signed or unsigned).

◆ is_real()

bool awkward::util::is_real ( dtype  dt)

True if the dtype is a non-complex floating point number.

◆ is_signed()

bool awkward::util::is_signed ( dtype  dt)

True if the dtype is a signed integer.

◆ is_unsigned()

bool awkward::util::is_unsigned ( dtype  dt)

True if the dtype is an unsigned integer.

◆ json_equals()

bool awkward::util::json_equals ( const std::string &  myvalue,
const std::string &  value 
)

Returns true if myvalue is equal to value when interpreted as JSON.

◆ key()

const std::string awkward::util::key ( const RecordLookupPtr recordlookup,
int64_t  fieldindex,
int64_t  numfields 
)

Returns the key associated with a field index, given a RecordLookup and a number of fields.

◆ keys()

const std::vector<std::string> awkward::util::keys ( const RecordLookupPtr recordlookup,
int64_t  numfields 
)

Returns a given RecordLookup as keys or generate anonymous ones form a number of fields.

◆ make_starts()

IndexOf<T> awkward::util::make_starts ( const IndexOf< T > &  offsets)

Converts an offsets index (from ListOffsetArray, for instance) into a starts index by viewing it with the last element dropped.

◆ make_stops()

IndexOf<T> awkward::util::make_stops ( const IndexOf< T > &  offsets)

Converts an offsets index (from ListOffsetArray, for instance) into a stops index by viewing it with the first element dropped.

◆ merge_parameters()

void awkward::util::merge_parameters ( Parameters output,
const Parameters input 
)

Merges a set of input parameters with output, keeping only those that are common to all sets.

◆ name()

std::string awkward::util::name ( Mapping  a,
value 
)

◆ name_to_dtype()

dtype awkward::util::name_to_dtype ( const std::string &  name)

Returns the name associated with a given dtype.

◆ parameter_asstring()

const std::string awkward::util::parameter_asstring ( const Parameters parameters,
const std::string &  key 
)

Returns the parameter associated with key as a string if parameter_isstring; raises an error otherwise.

◆ parameter_equals()

bool awkward::util::parameter_equals ( const Parameters parameters,
const std::string &  key,
const std::string &  value 
)

Returns true if the value associated with a key in parameters is equal to the specified value.

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_isname()

bool awkward::util::parameter_isname ( const Parameters parameters,
const std::string &  key 
)

Returns true if the parameter associated with key is a string that matches [A-Za-z_][A-Za-z_0-9]*; false otherwise.

◆ parameter_isstring()

bool awkward::util::parameter_isstring ( const Parameters parameters,
const std::string &  key 
)

Returns true if the parameter associated with key is a string; false otherwise.

◆ parameters_equal()

bool awkward::util::parameters_equal ( const Parameters self,
const Parameters other,
bool  check_all 
)

Returns true if all key-value pairs in self is equal to all key-value pairs in other.

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"".

If check_all, every parameter is checked; otherwise, only "__array__" and "__record__" are checked.

◆ quote()

std::string awkward::util::quote ( const std::string &  x)

Puts quotation marks around a string and escapes the appropriate characters.

Parameters
xThe string to quote.
doublequoteIf true, apply double-quotes ("); if false, apply single-quotes (').
Note
The implementation does not yet escape characters: it only adds strings. See issue scikit-hep/awkward-1.0#186.

◆ scale_from_units()

double awkward::util::scale_from_units ( const std::string &  format,
uint64_t  index 
)

◆ units_to_format()

const std::string awkward::util::units_to_format ( dtype  dt,
const std::string &  units,
int64_t  step 
)

Convert a datetime units string into a format string.

◆ value()

Mapping::value_type::value_type awkward::util::value ( Mapping  a,
const std::string &  name 
)

Variable Documentation

◆ units_map

const std::array<const NameValuePair<datetime_units>, 14> units_map
Initial value:
{
{{datetime_units::unknown, "unknown", 1, 1},
{datetime_units::Y, "Y", 31556952, 1},
{datetime_units::M, "M", 2629746, 1},
{datetime_units::W, "W", 604800, 1},
{datetime_units::D, "D", 86400, 1},
{datetime_units::h, "h", 3600, 1},
{datetime_units::m, "m", 60, 1},
{datetime_units::s, "s", 1, 1},
{datetime_units::ms, "ms", 1, 1000},
{datetime_units::us, "us", 1, 1000000},
{datetime_units::ns, "ns", 1, 1000000000},
{datetime_units::ps, "ps", 1, 1000000000000},
{datetime_units::fs, "fs", 1, 1000000000000000},
{datetime_units::as, "as", 1, 1000000000000000000}}
}