C++ API reference

C++ API reference#

This section documents the C++ API provided by the uproot_custom module. Any downstream project that wants to use the C++ functionalities provided by uproot_custom should include the header file uproot-custom.hh.

Defines

IMPORT_UPROOT_CUSTOM_CPP#: Macro to import the uproot_custom.cpp module.

Note

This macro should be used in the PYBIND11_MODULE definition of your module.

namespace uproot#

Typedefs

using IElementReader = IReader #

Deprecated alias for IReader.

Deprecated:: Use IReader instead.

using SharedReader = shared_ptr<IReader>#: Shortcut for shared pointer to IReader.

Note

When a reader requires another reader as a member, it must use std::shared_ptr<IReader> to properly handle lifetime management.

Functions

template<typename ReaderType, typename ...Args> shared_ptr<ReaderType> CreateReader(Args... args)#

Helper function to create a shared pointer to a reader. Pybind11 requires shared_ptr to handle object lifetime correctly.

Template Parameters:

ReaderType – The type of the reader.
Args – The argument types for the reader constructor.

Parameters:

args – The arguments for the reader constructor.

Returns:

The shared pointer to the created reader.

template<typename ReaderType, typename ...Args> void declare_reader(py::module &m, const char *name)#

Helper function to declare a reader class in a pybind11 module. Automatically wraps the class’ constructor to return a shared_ptr. User should always use this function to declare reader classes.

Template Parameters:

ReaderType – The type of the reader.
Args – The argument types for the reader constructor.

Parameters:

m – The declaring pybind11 module.
name – The name of the reader class in Python.

template<typename T> inline py::array_t<T> make_array(shared_ptr<std::vector<T>> seq)#

Convert a shared pointer to a std::vector<T> to a numpy array without copying. User can use this function to return numpy arrays from reader’s data() method.

Template Parameters:: T – The element type of the vector.
Parameters:: seq – The shared pointer to the std::vector<T>.
Returns:: The numpy array wrapping the vector data.

template<typename ...Args> inline void debug_printf(const char *msg, Args... args)#

Debug print function. Prints only when macro or environment varialbe with name UPROOT_DEBUG is defined. Use this function like printf().

Template Parameters:

Args – Argument types. No need to specify explicitly.

Parameters:

msg – The format string.
args – Arguments to format.

inline void debug_printf(uproot::BinaryBuffer &buffer, const size_t n = 100)#

Debug print function for BinaryBuffer. Prints only when macro or environment varialbe with name UPROOT_DEBUG is defined. Call BinaryBuffer::debug_print() internally.

Parameters:

buffer – The BinaryBuffer to print.
n – Number of bytes to print.

Variables

const uint32_t kNewClassTag = 0xFFFFFFFF#

const uint32_t kClassMask = 0x80000000#

const uint32_t kByteCountMask = 0x40000000#

const uint32_t kMaxMapCount = 0x3FFFFFFE#

const uint16_t kByteCountVMask = 0x4000#

const uint16_t kMaxVersion = 0x3FFF#

const int32_t kMapOffset = 2#

const uint16_t kStreamedMemberWise = 1 << 14#

class BinaryBuffer#

Public Types

enum EStatusBits#

Values:

enumerator kCanDelete#: if object in a list can be deleted

enumerator kMustCleanup#: if object destructor must call RecursiveRemove()

enumerator kIsReferenced#: if object is referenced by a TRef or TRefArray

enumerator kHasUUID#: if object has a TUUID (its fUniqueID=UUIDNumber)

enumerator kCannotPick#: if object in a pad cannot be picked

enumerator kNoContextMenu#: if object does not want context menu

enumerator kInvalidObject#: if object ctor succeeded but object should not be used

Public Functions

inline BinaryBuffer(py::array_t<uint8_t> data, py::array_t<uint32_t> offsets)#

Construct a BinaryBuffer from numpy arrays.

Parameters:

data – A numpy array of uint8_t containing the raw data.
offsets – A numpy array of uint32_t containing the offsets for each entry.

template<typename T> inline const T read()#

Read a value of type T from the buffer, handling endianness.

Template Parameters:: T – The type to read.
Returns:: The value read from the buffer.

inline const int16_t read_fVersion()#

Read the fVersion field from the buffer.

Returns:: The fVersion value

inline const uint32_t read_fNBytes()#

Read the fNBytes field from the buffer, checking the byte count mask.

Throws:: std::runtime_error – if the byte count mask is not set.
Returns:: The fNBytes value without the mask.

inline const std::string read_null_terminated_string()#

Read a null-terminated (\0) string from the buffer.

Returns:: The string read from the buffer.

inline const std::string read_obj_header()#

Read an object header from the buffer. The object header has fNBytes, fVersion, fTag. If fTag == kNewClassTag, then a null-terminated class name follows.

Returns:: The class name if the object is a new class, empty string otherwise.

inline const std::string read_TString()#

Read a TString from the buffer. A TString has length (uint8_t). If length == 255, then the length is a following uint32_t. Then following length bytes of string data.

Returns:: The TString data read from the buffer, as a std::string.

inline void skip(const size_t n)#

Skip n bytes in the buffer.

Parameters:: n – Number of bytes to skip.

inline void skip_fNBytes()#: Skip the fNBytes field. Equivalent to read_fNBytes() but does not return the value, since the mask need to be checked.

inline void skip_fVersion()#: Skip the fVersion field.

inline void skip_null_terminated_string()#: Skip a null-terminated (\0) string in the buffer.

inline void skip_obj_header()#: Skip an object header in the buffer. The object header has fNBytes, fVersion, fTag. If fTag == kNewClassTag, then a null-terminated class name follows.

inline void skip_TObject()#: Skip a TObject in the buffer. A TObject has fVersion (2 bytes), fUniqueID (4 bytes), fBits (4 bytes). If fBits & kIsReferenced, then a pidf (2 bytes) follows.

inline const uint8_t *get_data() const#: Get the raw data pointer.

inline const uint8_t *get_cursor() const#: Get the current cursor pointer.

inline const uint32_t *get_offsets() const#: Get the entry offsets array pointer.

inline const uint64_t entries() const#: Get the number of entries.

inline void debug_print(const size_t n = 100) const#

Debug print the next n bytes from the current cursor.

Parameters:: n – Number of bytes to print.

Private Members

uint8_t *m_cursor#: current cursor position

const uint64_t m_entries#: number of entries

const uint8_t *m_data#: raw data pointer

const uint32_t *m_offsets#: entry offsets pointer

class IReader#

#include <uproot-custom.hh>

Interface for element readers. All element readers must inherit from this class.

Subclassed by uproot::AnyClassReader, uproot::CStyleArrayReader, uproot::EmptyReader, uproot::GroupReader, uproot::ObjectHeaderReader, uproot::PrimitiveReader< T >, uproot::PrimitiveReader< bool >, uproot::STLMapReader, uproot::STLSeqReader, uproot::STLStringReader, uproot::TArrayReader< T >, uproot::TObjectReader, uproot::TStringReader

Public Functions

inline IReader(std::string name)#

Construct a new IReader object.

Parameters:: name – Name of the reader.

virtual ~IReader() = default#

inline virtual const std::string name() const#

Get the name of the reader.

Returns:: Name of the reader.

virtual void read(BinaryBuffer &buffer) = 0#

Read an element from the buffer.

Parameters:: buffer – The binary buffer to read from.

virtual py::object data() const = 0#

Get the data read by the reader. This should be called after the whole reading process.

Returns:: The data read by the reader.

inline virtual uint32_t read_many(BinaryBuffer &buffer, const int64_t count)#

Read multiple elements from the buffer in one go. Repeatedly calls read() by default.

Note

When multiple elements are stored together, some classes may have “one common

header + multiple data objects” format. This method can be overridden to handle such cases more efficiently.

Parameters:

buffer – The binary buffer to read from.
count – Number of elements to read.

Returns:

Number of elements read.

inline virtual uint32_t read_until(BinaryBuffer &buffer, const uint8_t *end_pos)#

Read elements from the buffer until reaching the end position. Repeatedly calls read() method by default.

Note

When multiple elements are stored together, some classes may have “one common

header + multiple data objects” format. This method can be overridden to handle such cases more efficiently.

Parameters:

buffer – The binary buffer to read from.
end_pos – The end position pointer.

Returns:

Number of elements read.

inline virtual uint32_t read_many_memberwise(BinaryBuffer &buffer, const int64_t count)#

Read multiple elements from the buffer in member-wise fashion. This method checks for negative count and calls read_many() by default. It can be overridden to handle member-wise reading more efficiently.

Parameters:

buffer – The binary buffer to read from.
count – Number of elements to read.

Returns:

Number of elements read.

Protected Attributes

const std::string m_name#: name of the reader

C++ API reference

Contents

C++ API reference#