An interface to read from, or write to, a ROOT file, as well as performing other common operations.
Please refer to the documentation of TFile for the details related to how data and executable code can be stored in ROOT files.
RFile is a modern and minimalistic interface to ROOT files, both local and remote, that can be used instead of TFile when you only need basic Put/Get operations and don't need the more advanced TFile/TDirectory functionalities. It provides:
RFile doesn't cover the entirety of use cases covered by TFile/TDirectory/TDirectoryFile and is not a 1:1 replacement for them. It is meant to simplify the most common use cases by following newer standard C++ practices.
RFile handles ownership via smart pointers, typically std::unique_ptr.
When getting an object from the file (via RFile::Get) you get back a unique copy of the object. Calling Get on the same object twice produces two independent clones of the object. The ownership over that object is solely on the caller and not shared with the RFile. Therefore, the object will remain valid after closing or destroying the RFile that generated it. This also means that any modification done to the object are not reflected to the file automatically: to update the object in the file you need to write it again (via RFile::Overwrite).
RFile::Put and RFile::Overwrite are the way to write objects to the file. Both methods take a const reference to the object to write and don't change the ownership of the object in any way. Calling Put or Overwrite doesn't guarantee that the object is immediately written to the underlying storage: to ensure that, you need to call RFile::Flush (or close the file).
Even though there is no equivalent of TDirectory in the RFile API, directories are still an existing concept in RFile (since they are a concept in the ROOT binary format). However they are for now only interacted with indirectly, via the use of filesystem-like string-based paths. If you Put an object in an RFile under the path "path/to/object", "object" will be stored under directory "to" which is in turn stored under directory "path". This hierarchy is encoded in the ROOT file itself and it can provide some optimization and/or conveniences when querying objects.
For the most part, it is convenient to think about RFile in terms of a key-value storage where string-based paths are used to refer to arbitrary objects. However, given the hierarchical nature of ROOT files, certain filesystem-like properties are applied to paths, for ease of use: the '/' character is treated specially as the directory separator; multiple '/' in a row are collapsed into one (since RFile doesn't allow directories with empty names).
At the moment, RFile doesn't allow getting directories via Get, nor writing ones via Put (this may change in the future).
Opening an RFile (for writing) and writing an object to it:
Opening an RFile (for reading) and reading an object from it:
Classes | |
| struct | ROpenOptions |
| struct | RRecreateOptions |
| struct | RUpdateOptions |
Public Types | |
| enum | EListKeyFlags { kListObjects = (1ULL << ( 0 )) , kListDirs = (1ULL << ( 1 )) , kListRecursive = (1ULL << ( 2 )) } |
| enum | EOverwriteFlags { kOverwrite_NoNewCycle = (1ULL << ( 0 )) } |
Public Member Functions | |
| ~RFile () | |
| void | Close () |
| Flushes the RFile if needed and closes it, disallowing any further reading or writing. | |
| size_t | Flush () |
| Writes all objects and the file structure to disk. | |
| template<typename T > | |
| std::unique_ptr< T > | Get (std::string_view path) const |
| Retrieves an object from the file. | |
| RFileHeader | GetFileHeader () const |
| Returns the data contained in the ROOT file's header. | |
| std::optional< RKeyInfo > | GetKeyInfo (std::string_view path) const |
Retrieves information about the key of object at path, if one exists. | |
| bool | IsOpen () const |
| Returns whether the file is still open or not. | |
| RFileKeyIterable | ListKeys (std::string_view basePath="", std::uint32_t flags=kListObjects|kListRecursive) const |
Returns an iterable over all keys of objects and/or directories written into this RFile starting at path basePath (defaulting to include the content of all subdirectories). | |
| template<typename T > | |
| void | Overwrite (std::string_view path, const T &obj, std::string_view title, std::uint32_t overwriteFlags=0) |
| Like Overwrite(std::string_view, const T&, bool) but allows giving a title to the object. | |
| template<typename T > | |
| void | Overwrite (std::string_view path, const T &obj, std::uint32_t overwriteFlags=0) |
| Puts an object into the file, overwriting any previously-existing object at that path. | |
| void | Print (std::ostream &out=std::cout) const |
| Prints the internal structure of this RFile to the given stream. | |
| void | Put (const class TNamed &namedObj, std::string_view dirPath="") |
Puts object namedObj in the file under the path dirPath/namedObj.GetName(), giving it a title equal to namedObj.GetTitle(). | |
| template<typename T > | |
| void | Put (std::string_view path, const T &obj, std::string_view title="") |
Puts object obj into the file and gives it a title. | |
Static Public Member Functions | |
| static std::unique_ptr< RFile > | Open (std::string_view path, const ROpenOptions &opts=ROpenOptions()) |
| Opens the file for reading. | |
| static std::unique_ptr< RFile > | Recreate (std::string_view path, const RRecreateOptions &opts=RRecreateOptions()) |
| Opens the file for reading/writing, overwriting it if it already exists. | |
| static std::unique_ptr< RFile > | Update (std::string_view path, const RUpdateOptions &opts=RUpdateOptions()) |
| Opens the file for updating, creating a new one if it doesn't exist. | |
Static Public Attributes | |
| static constexpr int | kMaxPathNesting = 1000 |
Private Types | |
| enum | EPutFlags { kPutFlag_AllowOverwrite = (1ULL << ( 0 )) , kPutFlag_OverwriteKeepCycle = (1ULL << ( 1 )) } |
| Flags used in PutInternal() More... | |
Private Member Functions | |
| RFile (std::unique_ptr< TFile > file) | |
| TKey * | GetTKey (std::string_view path) const |
Given path, returns the TKey corresponding to the object at that path (assuming the path is fully split, i.e. | |
| void * | GetUntyped (std::string_view path, std::variant< const char *, std::reference_wrapper< const std::type_info > > type) const |
Gets object path from the file and returns an owning pointer to it. | |
| template<typename T > | |
| void | PutInternal (std::string_view path, const T &obj, std::uint32_t flags, std::string_view title) |
| void | PutUntyped (std::string_view path, const std::type_info &type, const void *obj, std::uint32_t flags, std::string_view title) |
Writes obj to file, without taking its ownership. | |
Private Attributes | |
| std::unique_ptr< TFile > | fFile |
Friends | |
| TFile * | Internal::GetRFileTFile (RFile &rfile) |
| void * | Internal::RFile_GetObjectFromKey (RFile &file, const RKeyInfo &key) |
#include <ROOT/RFile.hxx>
|
private |
Flags used in PutInternal()
|
explicitprivate |
|
default |
| void RFile::Close | ( | ) |
| size_t RFile::Flush | ( | ) |
|
inline |
Retrieves an object from the file.
path should be a string such that IsValidPath(path) == true, otherwise an exception will be thrown. See ValidateAndNormalizePath() for info about valid path names.
path, or nullptr if there is no object of type T at the specified path. | ROOT::RFileHeader RFile::GetFileHeader | ( | ) | const |
| std::optional< ROOT::RKeyInfo > RFile::GetKeyInfo | ( | std::string_view | path | ) | const |
|
private |
Given path, returns the TKey corresponding to the object at that path (assuming the path is fully split, i.e.
"a/b/c" always means "object 'c' inside directory 'b' inside directory 'a'"). IMPORTANT: path must have been validated/normalized via ValidateAndNormalizePath() (see RFile.cxx).
|
private |
|
inline |
|
inline |
Returns an iterable over all keys of objects and/or directories written into this RFile starting at path basePath (defaulting to include the content of all subdirectories).
The iterable yields values of type ROOT::Experimental::RKeyInfo.
By default, keys referring to directories are not returned: only those referring to leaf objects are. If basePath is the path of a leaf object, only basePath itself will be returned. If basePath is the path of a directory, it won't appear in the listing. flags is a bitmask specifying the listing mode. If (flags & kListObjects) != 0, the listing will include keys of non-directory objects (default); If (flags & kListDirs) != 0, the listing will include keys of directory objects; If (flags & kListRecursive) != 0, the listing will recurse on all subdirectories of basePath (default), otherwise it will only list immediate children of basePath.
Example usage:
|
static |
Opens the file for reading.
path may be a regular file path or a remote URL.
| ROOT::RException | if the file at path could not be opened. |
|
inline |
|
inline |
Puts an object into the file, overwriting any previously-existing object at that path.
See Put for more details.
overwriteFlags must contain values from the EOverwriteFlags enum. If an object already exists at that path AND it has type T, it is kept as a backup cycle unless overwriteFlags contains kOverwrite_NoNewCycle. If the existing object's type differs from T, an exception is thrown. Note that even if no new cycle is created, only the latest cycle will be deleted.
| ROOT::RException | if path is already the path of a directory. |
| ROOT::RException | if the file was opened in read-only mode. |
| void RFile::Print | ( | std::ostream & | out = std::cout | ) | const |
| void ROOT::RFile::Put | ( | const class TNamed & | namedObj, |
| std::string_view | dirPath = "" ) |
Puts object namedObj in the file under the path dirPath/namedObj.GetName(), giving it a title equal to namedObj.GetTitle().
If dirPath is empty (default), the object is put at the top level of the file.
| ROOT::RException | if dirPath/namedObj.GetName() results in an invalid object path. Notably, this includes the case where namedObj.GetName() contains a slash character. |
|
inline |
Puts object obj into the file and gives it a title.
The application retains ownership of the object. The object will be effectively copied into the file, so any further modifications won't be seen by the object inside the file. Note that the object is not necessarily written to storage until the RFile is closed or Flush() is called.
path should be a string such that IsValidPath(path) == true, otherwise an exception will be thrown. See ValidateAndNormalizePath() for info about valid path names.
| ROOT::RException | if path already identifies a valid object or directory. |
| ROOT::RException | if the file was opened in read-only mode. |
|
inlineprivate |
|
private |
|
static |
Opens the file for reading/writing, overwriting it if it already exists.
| ROOT::RException | if a file could not be created at path (e.g. if the specified directory tree does not exist). |
|
static |
Opens the file for updating, creating a new one if it doesn't exist.
| ROOT::RException | if the file at path could neither be read nor created (e.g. if the specified directory tree does not exist). |
|
friend |
|
friend |
|
staticconstexpr |