Crate oxyroot

This crate aims to provide a way to open and write data in ROOT file format and particularly Tree and Branch inside Tree. This crate is in fact a port of groot written in Go and uproot written in Python.

To read from a branch and write to a branch, the API used is iterator based :

• as_iter to read from a branch. The type to read is provided as a type parameter. This type has to implement Unmarshaler trait.
• new_branch from WriterTree to write to a branch. The method write from WriterTree is used to write the data to the file by exhausting provided iterators. The type to write has to implement Marshaler trait. The type is deduced from the iterator.

Example: Show branches from a tree

use oxyroot::RootFile;
let s = "examples/from_uproot/data/simple.root";
let tree = RootFile::open(s).expect("Can not open file").get_tree("tree").unwrap();
tree.show();

will display

name                           | typename                       | interpretation
-------------------------------+-------------------------------+-------------------------------
one                            | int32_t                        | i32
two                            | float                          | f32
three                          | char*                          | String

Example: Iter over a branch tree containing i32 values

use oxyroot::RootFile;
let s = "examples/from_uproot/data/simple.root";
let tree = RootFile::open(s).expect("Can not open file").get_tree("tree").unwrap();
let one = tree.branch("one").unwrap().as_iter::<i32>().expect("wrong type");
one.for_each(|v| println!("v = {v}"));

Example: Write i32 values in a branch

use oxyroot::{RootFile, WriterTree};
let s = "/tmp/simple.root";
let mut file = RootFile::create(s).expect("Can not create file");
let mut tree = WriterTree::new("mytree");
let it = (0..15);
tree.new_branch("it", it);
tree.write(&mut file).expect("Can not write tree");
file.close().expect("Can not close file");

Example: Iter over a branch tree containing Vec<i32> (aka std::vector<int32_t>) values

use oxyroot::RootFile;
let s = "tests/stl_containers/stl_containers.root";
let tree = RootFile::open(s).expect("Can not open file").get_tree("tree").unwrap();
let vector_int32 = tree.branch("vector_int32")
                   .unwrap().as_iter::<Vec<i32>>().expect("wrong type")
                   .collect::<Vec<_>>();
assert_eq!(
    vector_int32,
    [
        vec![1],
        vec![1, 2],
        vec![1, 2, 3],
        vec![1, 2, 3, 4],
        vec![1, 2, 3, 4, 5]
    ]
);

Which types can be read from a branch?

Primitives and C++ STL standards

oxyroot can iterate over branch which contains :

• primitive types like i32, f64, bool…
• String (from TString, char* or std::string)
• Vec (from std::vector or array)
• HashMap

C++	Rust
std::string	String
std::vector	Vec
std::map	HashMap
std::set	HashSet
T*	Slice<T>
T[N]	array
TString	String

Examples can be found in tests.

Structures

Structure serialized in Branch can be also read but the parsing code has to be written :

struct sd_t {
         Int_t a;
         Int_t b;
};

sd_t sd;
tree->Branch("v_i",&sd, 3200000, 0);

The sd struct can be read with a code like this :

use oxyroot::RBuffer;
use oxyroot::RootFile;
struct Sd {
    a: i32,
    b: i32,
};

let parse = |r: &mut RBuffer| Sd {
    a: r.read_i32().unwrap(),
    b: r.read_i32().unwrap(),
};


let s = "tests_data/doc/struct_sd.root";
let tree = RootFile::open(s).expect("Can not open file").get_tree("T").unwrap();

// branch v_i contains v_i which will be zipped.
let mut b = tree.branch("v_i").unwrap().get_basket(parse);

for i in -10..10 {
    let sd = b.next().unwrap();
}

Which types can be written to a branch?

Primitives and C++ STL standards

oxyroot can iterate over branch which contains :

• primitive types like i32, f64, bool…
• String (will appear as a char*)
• Vec (to std::vector)
• HashMap (not yet implemented)

Re-exports

• pub use rtree::branch_name::BranchName;

Modules

• rbase
• rcont
• rtree

Macros

• factory_all_for_register_impl
• factory_fn_register_impl

Structs

• RBuffer
  Helper struct to parse data read in file
• RootFile
  Rust equivalent of TFile.
• SizedSlice
• Slice
  Represent a array of T* in C++

Enums

• Branch
  Rust equivalent of TBranch or TBranchElement (ie column) of a TTree
• StateCallBack

Traits

• Marshaler
  Trait that permits writing a type to an ROOT file.
• Named
• Object
• ReadFromTree
• Unmarshaler
  Trait that permits reading a type from an ROOT file.
• UnmarshalerInto
  Automatically implemented if Unmarshaler is implemented
• WriteToTree

Type Aliases

• ReaderTree
  Read only Rust equivalent of TTree
• Result
• WriterTree
  Write only Rust equivalent of TTree

Derive Macros

• ReadFromTreederive
  Derive macro available if oxyroot is built with features = ["derive"].
• WriteToTreederive
  Derive macro available if oxyroot is built with features = ["derive"].