The RNTupleModel encapulates the schema of an ntuple.

The ntuple model comprises a collection of hierarchically organized fields. From a model, "entries" can be extracted. For convenience, the model provides a default entry. Models have a unique model identifier that faciliates checking whether entries are compatible with it (i.e.: have been extracted from that model).

Definition at line 77 of file RNTupleModel.hxx.

Classes
struct	NameWithDescription_t
	A wrapper over a field name and an optional description; used in `AddField()` and `RUpdater::AddField()` More...

class	RProjectedFields
	Projected fields are fields whose columns are reused from existing fields. More...

class	RUpdater
	A model is usually immutable after passing it to an `RNTupleWriter`. More...

Public Member Functions
	RNTupleModel (const RNTupleModel &)=delete

	~RNTupleModel ()=default

template<typename T >
void	AddField (const NameWithDescription_t &fieldNameDesc, T *fromWhere)
	Throws an exception if fromWhere is null.

void	AddField (std::unique_ptr< Detail::RFieldBase > field)
	Adds a field whose type is not known at compile time.

RResult< void >	AddProjectedField (std::unique_ptr< Detail::RFieldBase > field, std::function< std::string(const std::string &)> mapping)
	Adds a top-level field based on existing fields.

std::unique_ptr< RNTupleModel >	Clone () const

std::unique_ptr< REntry >	CreateBareEntry () const
	In a bare entry, all values point to nullptr.

std::unique_ptr< REntry >	CreateEntry () const

void	Freeze ()

template<typename T >
T *	Get (std::string_view fieldName) const

REntry *	GetDefaultEntry () const

std::string	GetDescription () const

const Detail::RFieldBase *	GetField (std::string_view fieldName) const

RFieldZero *	GetFieldZero () const

std::uint64_t	GetModelId () const

const RProjectedFields &	GetProjectedFields () const

bool	IsFrozen () const

std::shared_ptr< RCollectionNTupleWriter >	MakeCollection (std::string_view fieldName, std::unique_ptr< RNTupleModel > collectionModel)
	Ingests a model for a sub collection and attaches it to the current model.

template<typename T , typename... ArgsT>
std::shared_ptr< T >	MakeField (const NameWithDescription_t &fieldNameDesc, ArgsT &&... args)
	Creates a new field given a `name` or `{name, description}` pair and a corresponding tree value that is managed by a shared pointer.

RNTupleModel &	operator= (const RNTupleModel &)=delete

void	SetDescription (std::string_view description)

void	Unfreeze ()

Static Public Member Functions
static std::unique_ptr< RNTupleModel >	Create ()

static std::unique_ptr< RNTupleModel >	CreateBare ()
	A bare model has no default entry.

Private Member Functions
	RNTupleModel ()

void	EnsureNotBare () const
	Throws an RException if fDefaultEntry is nullptr.

void	EnsureNotFrozen () const
	Throws an RException if fFrozen is true.

void	EnsureValidFieldName (std::string_view fieldName)
	Checks that user-provided field names are valid in the context of this NTuple model.

Private Attributes
std::unique_ptr< REntry >	fDefaultEntry
	Contains field values corresponding to the created top-level fields.

std::string	fDescription
	Free text set by the user.

std::unordered_set< std::string >	fFieldNames
	Keeps track of which field names are taken, including projected field names.

std::unique_ptr< RFieldZero >	fFieldZero
	Hierarchy of fields consisting of simple types and collections (sub trees)

std::uint64_t	fModelId = 0
	Upon freezing, every model has a unique ID to distingusish it from other models.

std::unique_ptr< RProjectedFields >	fProjectedFields
	The set of projected top-level fields.

#include <ROOT/RNTupleModel.hxx>

Constructor & Destructor Documentation

◆ RNTupleModel() [1/2]

ROOT::Experimental::RNTupleModel::RNTupleModel ( )

private

Definition at line 194 of file RNTupleModel.cxx.

◆ RNTupleModel() [2/2]

ROOT::Experimental::RNTupleModel::RNTupleModel ( const RNTupleModel & )

delete

◆ ~RNTupleModel()

ROOT::Experimental::RNTupleModel::~RNTupleModel ( )

default

Member Function Documentation

◆ AddField() [1/2]

template<typename T >

void ROOT::Experimental::RNTupleModel::AddField	(	const NameWithDescription_t &	fieldNameDesc,
		T *	fromWhere
	)

inline

Throws an exception if fromWhere is null.

Definition at line 275 of file RNTupleModel.hxx.

◆ AddField() [2/2]

void ROOT::Experimental::RNTupleModel::AddField ( std::unique_ptr< Detail::RFieldBase > field )

Adds a field whose type is not known at compile time.

Thus there is no shared pointer returned.

Throws an exception if the field is null.

Definition at line 231 of file RNTupleModel.cxx.

◆ AddProjectedField()

ROOT::Experimental::RResult< void > ROOT::Experimental::RNTupleModel::AddProjectedField	(	std::unique_ptr< Detail::RFieldBase >	field,
		std::function< std::string(const std::string &)>	mapping
	)

Adds a top-level field based on existing fields.

The mapping function is called with the qualified field names of the provided field and the subfields. It should return the qualified field names used as a mapping source. Projected fields can only be used for models used to write data.

Definition at line 244 of file RNTupleModel.cxx.

◆ Clone()

std::unique_ptr< ROOT::Experimental::RNTupleModel > ROOT::Experimental::RNTupleModel::Clone ( ) const

Definition at line 212 of file RNTupleModel.cxx.

◆ Create()

std::unique_ptr< ROOT::Experimental::RNTupleModel > ROOT::Experimental::RNTupleModel::Create ( )

static

Definition at line 205 of file RNTupleModel.cxx.

◆ CreateBare()

std::unique_ptr< ROOT::Experimental::RNTupleModel > ROOT::Experimental::RNTupleModel::CreateBare ( )

static

A bare model has no default entry.

Definition at line 198 of file RNTupleModel.cxx.

◆ CreateBareEntry()

std::unique_ptr< ROOT::Experimental::REntry > ROOT::Experimental::RNTupleModel::CreateBareEntry ( ) const

In a bare entry, all values point to nullptr.

The resulting entry shall use CaptureValueUnsafe() in order set memory addresses to be serialized / deserialized

Definition at line 331 of file RNTupleModel.cxx.

◆ CreateEntry()

std::unique_ptr< ROOT::Experimental::REntry > ROOT::Experimental::RNTupleModel::CreateEntry ( ) const

Definition at line 319 of file RNTupleModel.cxx.

◆ EnsureNotBare()

void ROOT::Experimental::RNTupleModel::EnsureNotBare ( ) const

private

Throws an RException if fDefaultEntry is nullptr.

Definition at line 188 of file RNTupleModel.cxx.

◆ EnsureNotFrozen()

void ROOT::Experimental::RNTupleModel::EnsureNotFrozen ( ) const

private

Throws an RException if fFrozen is true.

Definition at line 182 of file RNTupleModel.cxx.

◆ EnsureValidFieldName()

void ROOT::Experimental::RNTupleModel::EnsureValidFieldName ( std::string_view fieldName )

private

Checks that user-provided field names are valid in the context of this NTuple model.

Throws an RException for invalid names.

Definition at line 170 of file RNTupleModel.cxx.

◆ Freeze()

void ROOT::Experimental::RNTupleModel::Freeze ( )

Definition at line 350 of file RNTupleModel.cxx.

◆ Get()

template<typename T >

T * ROOT::Experimental::RNTupleModel::Get ( std::string_view fieldName ) const

inline

Definition at line 295 of file RNTupleModel.hxx.

◆ GetDefaultEntry()

ROOT::Experimental::REntry * ROOT::Experimental::RNTupleModel::GetDefaultEntry ( ) const

Definition at line 311 of file RNTupleModel.cxx.

◆ GetDescription()

std::string ROOT::Experimental::RNTupleModel::GetDescription ( ) const

inline

Definition at line 324 of file RNTupleModel.hxx.

◆ GetField()

const ROOT::Experimental::Detail::RFieldBase * ROOT::Experimental::RNTupleModel::GetField ( std::string_view fieldName ) const

Definition at line 290 of file RNTupleModel.cxx.

◆ GetFieldZero()

RFieldZero * ROOT::Experimental::RNTupleModel::GetFieldZero ( ) const

inline

Definition at line 321 of file RNTupleModel.hxx.

◆ GetModelId()

std::uint64_t ROOT::Experimental::RNTupleModel::GetModelId ( ) const

inline

Definition at line 306 of file RNTupleModel.hxx.

◆ GetProjectedFields()

const RProjectedFields & ROOT::Experimental::RNTupleModel::GetProjectedFields ( ) const

inline

Definition at line 301 of file RNTupleModel.hxx.

◆ IsFrozen()

bool ROOT::Experimental::RNTupleModel::IsFrozen ( ) const

inline

Definition at line 305 of file RNTupleModel.hxx.

◆ MakeCollection()

std::shared_ptr< ROOT::Experimental::RCollectionNTupleWriter > ROOT::Experimental::RNTupleModel::MakeCollection	(	std::string_view	fieldName,
		std::unique_ptr< RNTupleModel >	collectionModel
	)

Ingests a model for a sub collection and attaches it to the current model.

Throws an exception if collectionModel is null.

Definition at line 273 of file RNTupleModel.cxx.

◆ MakeField()

template<typename T , typename... ArgsT>

std::shared_ptr< T > ROOT::Experimental::RNTupleModel::MakeField	(	const NameWithDescription_t &	fieldNameDesc,
		ArgsT &&...	args
	)

inline

Creates a new field given a name or {name, description} pair and a corresponding tree value that is managed by a shared pointer.

Example: create some fields and fill an RNTuple

#include <ROOT/RNTuple.hxx>
using ROOT::Experimental::RNTupleModel;
using ROOT::Experimental::RNTupleWriter;
 
#include <vector>
 
auto model = RNTupleModel::Create();
auto pt = model->MakeField<float>("pt");
auto vec = model->MakeField<std::vector<int>>("vec");
 
// The RNTuple is written to disk when the RNTupleWriter goes out of scope
{
   auto ntuple = RNTupleWriter::Recreate(std::move(model), "myNTuple", "myFile.root");
   for (int i = 0; i < 100; i++) {
      *pt = static_cast<float>(i);
      *vec = {i, i+1, i+2};
      ntuple->Fill();
   }
}

Example: create a field with an initial value

#include <ROOT/RNTuple.hxx>
using ROOT::Experimental::RNTupleModel;
 
auto model = RNTupleModel::Create();
// pt's initial value is 42.0
auto pt = model->MakeField<float>("pt", 42.0);

Example: create a field with a description

#include <ROOT/RNTuple.hxx>
using ROOT::Experimental::RNTupleModel;
 
auto model = RNTupleModel::Create();
auto hadronFlavour = model->MakeField<float>({
   "hadronFlavour", "flavour from hadron ghost clustering"
});

Definition at line 254 of file RNTupleModel.hxx.

◆ operator=()

RNTupleModel & ROOT::Experimental::RNTupleModel::operator= ( const RNTupleModel & )

delete

◆ SetDescription()

void ROOT::Experimental::RNTupleModel::SetDescription ( std::string_view description )

Definition at line 361 of file RNTupleModel.cxx.

◆ Unfreeze()

void ROOT::Experimental::RNTupleModel::Unfreeze ( )

Definition at line 343 of file RNTupleModel.cxx.

Member Data Documentation

◆ fDefaultEntry

std::unique_ptr<REntry> ROOT::Experimental::RNTupleModel::fDefaultEntry

private

Contains field values corresponding to the created top-level fields.

Definition at line 175 of file RNTupleModel.hxx.

◆ fDescription

std::string ROOT::Experimental::RNTupleModel::fDescription

private

Free text set by the user.

Definition at line 179 of file RNTupleModel.hxx.

◆ fFieldNames

std::unordered_set<std::string> ROOT::Experimental::RNTupleModel::fFieldNames

private

Keeps track of which field names are taken, including projected field names.

Definition at line 177 of file RNTupleModel.hxx.

◆ fFieldZero

std::unique_ptr<RFieldZero> ROOT::Experimental::RNTupleModel::fFieldZero

private

Hierarchy of fields consisting of simple types and collections (sub trees)

Definition at line 173 of file RNTupleModel.hxx.

◆ fModelId

std::uint64_t ROOT::Experimental::RNTupleModel::fModelId = 0

private

Upon freezing, every model has a unique ID to distingusish it from other models.

Cloning preserves the ID. Entries are linked to models via the ID.

Definition at line 184 of file RNTupleModel.hxx.

◆ fProjectedFields

std::unique_ptr<RProjectedFields> ROOT::Experimental::RNTupleModel::fProjectedFields

private

The set of projected top-level fields.

Definition at line 181 of file RNTupleModel.hxx.

Libraries for ROOT::Experimental::RNTupleModel:

[legend]

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

tree/ntuple/v7/inc/ROOT/RNTupleModel.hxx
tree/ntuple/v7/src/RNTupleModel.cxx

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ RNTupleModel() [1/2]

◆ RNTupleModel() [2/2]

◆ ~RNTupleModel()

Member Function Documentation

◆ AddField() [1/2]

◆ AddField() [2/2]

◆ AddProjectedField()

◆ Clone()

◆ Create()

◆ CreateBare()

◆ CreateBareEntry()

◆ CreateEntry()

◆ EnsureNotBare()

◆ EnsureNotFrozen()

◆ EnsureValidFieldName()

◆ Freeze()

◆ Get()

◆ GetDefaultEntry()

◆ GetDescription()

◆ GetField()

◆ GetFieldZero()

◆ GetModelId()

◆ GetProjectedFields()

◆ IsFrozen()

◆ MakeCollection()

◆ MakeField()

◆ operator=()

◆ SetDescription()

◆ Unfreeze()

Member Data Documentation

◆ fDefaultEntry

◆ fDescription

◆ fFieldNames

◆ fFieldZero

◆ fModelId

◆ fProjectedFields