Struct ReportCollection

Source

pub struct ReportCollection<Context: ?Sized + 'static = Dynamic, ThreadSafety: 'static = SendSync> { /* private fields */ }

Expand description

A collection of reports.

You can think of a ReportCollection<C, T> as a wrapper around a Vec<Report<C, markers::Cloneable, T>>, however, it has a slightly different API:

It provides methods such as context and context_custom to create new reports with the collection as children.
It has convenience methods to convert between different context and thread safety markers such as into_dynamic and into_local.
It is also possible to convert between different context and thread safety markers using the From and Into traits.

Implementations§

Source §

impl<C: ?Sized, T> ReportCollection<C, T>

Source

pub fn new() -> Self

Creates a new, empty ReportCollection.

The collection will be initially empty and will have no capacity allocated. This method is equivalent to calling Default::default().

§Examples

use rootcause::report_collection::ReportCollection;

let collection: ReportCollection = ReportCollection::new();
assert!(collection.is_empty());
assert_eq!(collection.len(), 0);

Source

pub fn with_capacity(capacity: usize) -> Self

Creates a new, empty ReportCollection with the specified capacity.

The collection will be able to hold at least capacity reports without reallocating. If you plan to add a known number of reports to the collection, using this method can help improve performance by reducing the number of memory allocations needed.

§Examples

use rootcause::report_collection::ReportCollection;

let collection: ReportCollection = ReportCollection::with_capacity(10);
assert!(collection.is_empty());
assert_eq!(collection.len(), 0);
assert!(collection.capacity() >= 10);

Source

pub fn push(&mut self, report: Report<C, Cloneable, T>)

Appends a report to the end of the collection.

This method takes ownership of the report and adds it to the collection. The report must have the Cloneable ownership marker, which allows it to be stored in the collection and cloned when needed.

§Examples

use rootcause::{report, report_collection::ReportCollection};

let mut collection = ReportCollection::new();
let report = report!("An error occurred").into_cloneable();

collection.push(report);
assert_eq!(collection.len(), 1);

Source

pub fn pop(&mut self) -> Option<Report<C, Cloneable, T>>

Removes and returns the last report from the collection.

Returns None if the collection is empty.

This method provides LIFO (last in, first out) behavior, making the collection behave like a stack for the most recently added reports.

§Examples

use rootcause::{report, report_collection::ReportCollection};

let mut collection = ReportCollection::new();
let report1 = report!("First error").into_cloneable();
let report2 = report!("Second error").into_cloneable();

collection.push(report1);
collection.push(report2);

let last_report = collection.pop().unwrap();
assert_eq!(collection.len(), 1);

let empty_pop = ReportCollection::<&str>::new().pop();
assert!(empty_pop.is_none());

Source

pub fn len(&self) -> usize

Returns the number of reports in the collection.

§Examples

use rootcause::{report, report_collection::ReportCollection};

let mut collection = ReportCollection::new();
assert_eq!(collection.len(), 0);

collection.push(report!("Error 1").into_cloneable());
collection.push(report!("Error 2").into_cloneable());
assert_eq!(collection.len(), 2);

Source

pub fn capacity(&self) -> usize

Returns the capacity of the collection.

The capacity is the number of reports the collection can hold without allocating additional memory.

§Examples

use rootcause::{
    markers::{Dynamic, SendSync},
    report,
    report_collection::ReportCollection,
};

let collection = ReportCollection::<Dynamic, SendSync>::with_capacity(5);
assert!(collection.capacity() <= 5);

Source

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more reports to be inserted in the collection.

The collection may reserve more space to avoid frequent reallocations.

§Examples

use rootcause::{
    markers::{Dynamic, SendSync},
    report,
    report_collection::ReportCollection,
};

let mut collection = ReportCollection::<Dynamic, SendSync>::new();
collection.reserve(10);
assert!(collection.capacity() >= 10);

Source

pub fn get(&self, index: usize) -> Option<ReportRef<'_, C, Cloneable, T>>

Returns a reference to the report at the given index.

Returns None if the index is out of bounds.

§Examples

use rootcause::{report, report_collection::ReportCollection};

let mut collection = ReportCollection::new();
collection.push(report!("First error").into_cloneable());
collection.push(report!("Second error").into_cloneable());

let first_report = collection.get(0).unwrap();
let second_report = collection.get(1).unwrap();
let out_of_bounds = collection.get(2);

assert!(out_of_bounds.is_none());

Source

pub fn is_empty(&self) -> bool

Returns true if the collection contains no reports.

§Examples

use rootcause::{report, report_collection::ReportCollection};

let mut collection = ReportCollection::new();
assert!(collection.is_empty());

collection.push(report!("An error").into_cloneable());
assert!(!collection.is_empty());

Source

pub fn iter(&self) -> ReportCollectionIter<'_, C, T> ⓘ

Returns an iterator over references to the reports in the collection.

The iterator yields ReportRef items, which are lightweight references to the reports in the collection.

§Examples

use rootcause::{report, report_collection::ReportCollection};

let mut collection = ReportCollection::new();
collection.push(report!("Error 1").into_cloneable());
collection.push(report!("Error 2").into_cloneable());

for (i, report_ref) in collection.iter().enumerate() {
    println!("Report {}: {}", i, report_ref);
}

Source

pub fn format_with<H>(&self, hook: &H) -> impl Display + Debug
where H: ReportFormatter,

Formats the entire collection using a specific report formatting hook.

This method allows you to format a collection of reports with a custom formatter without globally registering it. This is useful for:

One-off custom formatting
Testing different formatters
Using different formatters in different parts of your application

Unlike the default Display and Debug implementations which use the globally registered hook, this method uses the hook you provide directly.

§Examples

use rootcause::{
    hooks::builtin_hooks::report_formatter::DefaultReportFormatter, report,
    report_collection::ReportCollection,
};

let mut collection = ReportCollection::new();
collection.push(report!("Error 1").into_cloneable());
collection.push(report!("Error 2").into_cloneable());

// Format with ASCII-only output (no Unicode or ANSI colors)
let formatted = collection.format_with(&DefaultReportFormatter::ASCII);
println!("{}", formatted);

Source

pub fn into_dynamic(self) -> ReportCollection<Dynamic, T>

Converts the collection to use type-erased contexts via Dynamic.

This performs type erasure on the context type parameter, allowing collections with different concrete context types to be stored together or passed to functions that accept ReportCollection<Dynamic, T>.

This method does not actually modify the collection in any way. It only has the effect of “forgetting” that the context actually has the type C.

The thread safety marker T is preserved during this conversion.

§Examples

use rootcause::{markers::Dynamic, report, report_collection::ReportCollection};

let mut collection: ReportCollection<Dynamic> = ReportCollection::new();
collection.push(report!("String error").into_cloneable());

let erased: ReportCollection<Dynamic> = collection.into_dynamic();
assert_eq!(erased.len(), 1);

Source

pub fn as_dynamic(&self) -> &ReportCollection<Dynamic, T>

Returns a reference to the collection with type-erased contexts via Dynamic.

Source

pub fn into_local(self) -> ReportCollection<C, Local>

Converts the collection to use Local thread safety semantics.

This changes the thread safety marker from any type to Local, which means the resulting collection will not implement Send or Sync. This is useful when you want to use the collection in single-threaded contexts and potentially store non-thread-safe data.

This method does not actually modify the collection in any way. It only has the effect of “forgetting” that all objects in the ReportCollection are actually Send and Sync.

The context type C is preserved during this conversion.

§Examples

use rootcause::{
    markers::{Dynamic, Local},
    report,
    report_collection::ReportCollection,
};

let mut collection: ReportCollection<Dynamic> = ReportCollection::new(); // defaults to SendSync
collection.push(report!("An error").into_cloneable());

let local_collection: ReportCollection<Dynamic, Local> = collection.into_local();
assert_eq!(local_collection.len(), 1);

Source

pub fn as_local(&self) -> &ReportCollection<C, Local>

Returns a reference to the collection with Local thread safety semantics.

Source

pub fn context<D>(self, context: D) -> Report<D, Mutable, T>
where D: ObjectMarkerFor<T> + Display + Debug,

Creates a new Report with the given context and sets the current report collection as the children of the new report.

The new context will use the handlers::Display handler to format the context.

This is a convenience method used for chaining method calls; it consumes the ReportCollection and returns a new Report.

If you want a different context handler, you can use Report::context_custom.

If you want to more directly control the allocation of the new report, you can use Report::from_parts, which is the underlying method used to implement this method.

§Examples

let report_collection: ReportCollection = [report!("error A"), report!("error B")]
    .into_iter()
    .collect();
let report: Report<&str> = report_collection.context("additional context");

Source

pub fn context_custom<H, D>(self, context: D) -> Report<D, Mutable, T>
where D: ObjectMarkerFor<T>, H: ContextHandler<D>,

Creates a new Report with the given context and sets the current report collection as the children of the new report.

This is a convenience method used for chaining method calls; it consumes the ReportCollection and returns a Report.

If you want to more directly control the allocation of the new report, you can use Report::from_parts, which is the underlying method used to implement this method.

§Examples

let report_collection: ReportCollection = [report!("error A"), report!("error B")]
    .into_iter()
    .collect();
let report: Report<&str> = report_collection.context_custom::<handlers::Debug, _>("context");

Source §

impl<C: ?Sized> ReportCollection<C, SendSync>

Source

pub fn new_sendsync() -> Self

Creates a new, empty ReportCollection with SendSync thread safety.

This is equivalent to calling new() but makes the thread safety marker explicit. The resulting collection can be safely sent between threads and shared across threads.

§Examples

use rootcause::{markers::SendSync, report_collection::ReportCollection};

let collection: ReportCollection<&str, SendSync> = ReportCollection::new_sendsync();
assert!(collection.is_empty());

Source §

impl<C: ?Sized> ReportCollection<C, Local>

Source

pub fn new_local() -> Self

Creates a new, empty ReportCollection with Local thread safety.

This creates a collection that is not Send or Sync, meaning it cannot be transferred between threads or shared across threads. This is useful for single-threaded applications or when you need to store non-thread-safe data.

§Examples

use rootcause::{markers::Local, report_collection::ReportCollection};

let collection: ReportCollection<&str, Local> = ReportCollection::new_local();
assert!(collection.is_empty());