/treena

Trees on arena. Mirror of https://gitlab.com/nop_thread/treena .

Primary LanguageRustApache License 2.0Apache-2.0

Treena

Build Status Latest version Documentation Minimum supported rustc version: 1.56

Treena: Trees stored in an arena.

Yet another arena-tree?

Treena is heavily inspired by indextree crate, but has extra goals.

  • Provide an arena to contain multiple independent trees.
    • Even when users are manipulating single trees, they may want to create temporary tree. Forest supports such use case.
    • Forest provided by treena is a true forest: root nodes of trees in an arena have no siblings relationships among each other.
  • Use clear and unambiguous names.
    • Traditional function names which are often used for tree manipulation are very unclear for non-native English speakers.
      • For example, what does A.insert_before(B) mean? "insert A before B" or "insert B before A"?
      • P.insert_before(A, B) can be interpreted relatively naturally: "P (parent) inserts the node A before the node B". However, P here is completely redundant since it must be the parent of A.
    • Treena provides these functions as A.adopt(B, AsFoo) and forest.insert(A, AsFooOf(B)). They are much clearer than the traditional names.
      • For example, A.adopt(B, AdoptAs::LastChild) can be read as "the node A adopts the node B as the last child of A".
      • Another example: forest.insert(A, InsertAs::NextSiblingOf(B)) can be read as "insert the node A as the next sibling of the node B".
  • Be safe and easy to debug.
    • No unsafe codes (at least for now). This means that the crate won't run into undefined behavior.
    • Using .expect() everywhere with meaningful message when it won't fail or should panic for some reason.
      • For example, if treena panics with [precondition] node must be alive, you can be aware immediately that the passed node is not alive but it violates precondition of the function.
      • Another example: if treena panics with [consistency] foobarbaz, it is sure that this is a bug of treena (not you).

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.