pinus

A prickly BTreeMap.

• You can insert through shared references and values are pin-projected.
• You can remove keys and drop entries through exclusive references.
• You can remove values through exclusive references until the PineMap is pinned.

Help wanted!

I need only a fairly barebones implementation and not necessarily optimized version of this data structure for my own project(s), but am committed to maintaining it into shape if there's interest.

Follow the "good first issues" badge above for starting points!

Note that the crate uses unsafe code very frequently, so you should be at least somewhat comfortable with ensuring soundness manually. Code reviews are also highly appreciated, both within and outside of this regard.

Installation

Please use cargo-edit to always add the latest version of this library:

cmd cargo add pinus

Examples

Homogeneous Map

```rust use pinus::{prelude::*, sync::PineMap}; use std::{convert::Infallible, pin::Pin};

// PineMap is interior-mutable, so either is useful: let map = PineMap::new(); let mut mut_map = PineMap::new();

// Get parallel shared references by inserting like this: let a: &String = map.insert("Hello!", "Hello!".tostring()) .unwrap(/* Your data back if the entry already existed. */); let b: &String = map.insertwith("Hello again!", |k| k.tostring()) .maperr(|(key, factory)| key).unwrap(); let c: &String = map.tryinsertwith::<_, Infallible>("Hello once again!", |k| Ok(k.tostring())) .unwrap(/* Error from factory. */) .map_err(|(key, _factory)| key).unwrap();

let a2: &String = map.get("Hello!").unwrap();

let _ = (a, a2, b, c);

// Get exclusive references like this (also with or without factory): let muta: &mut String = mutmap.insertwithmut("Hi!", |k| k.tostring()) .maperr(|(key, _factory)| key).unwrap();

let muta2: &mut String = mutmap.get_mut("Hi!").unwrap();

// The …_mut methods are actually faster, but their results can't be held onto at once: // let _ = (muta, muta2); // "error[E0499]: cannot borrow mut_map as mutable more than once at a time"

// Remove entries like this: mutmap.clear(); let _: Option<(&str, String)> = mutmap.removepair("A"); let _: Option = mutmap.removevalue("B"); let _: Option<&str> = mutmap.removekey("C"); let _: bool = mutmap.drop_entry("D");

/////

// Now on to part 2, value pinning: let mut map: Pin<_> = map.pin(); let mut mutmap: Pin<_> = mutmap.pin();

// Shared references to values are now pinned: let a: Pin<&String> = map.insert("Hello!!", "Hello!!".tostring()) .unwrap(); let b: Pin<&String> = map.insertwith("Hello again!!", |k| k.tostring()) .ok().unwrap(); let c: Pin<&String> = map.tryinsertwith::<_, Infallible>("Hello once again!!", |k| Ok(k.tostring())) .unwrap().ok().unwrap();

let a2: Pin<&String> = map.get("Hello!").unwrap();

let _ = (a, a2, b, c);

// Exclusive references to values are also pinned: let mut muta: Pin<&mut String> = mutmap.insertwithmut("Hi!", |k| k.tostring()) .maperr(|(key, _factory)| key).unwrap();

let mut muta2: Pin<&mut String> = mutmap.get_mut("Hi!").unwrap();

// The …_mut methods are actually faster, but their results can't be held onto at once: // let _ = (muta, muta2); // "error[E0499]: cannot borrow mut_map as mutable more than once at a time"

// Only keys can be removed now, but values must be dropped in place: mutmap.clear(); let _: Option<&str> = mutmap.removekey("C"); let _: bool = mutmap.drop_entry("D"); ```

Heterogeneous Map

```rust use pinus::{prelude::*, sync::PressedPineMap}; use std::{ any::Any, borrow::{Borrow, BorrowMut}, convert::Infallible, pin::Pin, };

let map = PressedPineMap::<_, dyn Any>::new();

// dyn Any is !Sized, // so it's necessary to use the loosely-typed emplacement methods: let : &dyn Any = map .emplacewith(1, |key, slot| slot.write(())) .ok(/* or key and factory */).unwrap(); let _: &dyn Any = map .tryemplacewith::<_, Infallible>(2, |key, slot| Ok(slot.write(()))) .unwrap(/* or factory error /) .ok(/ or key and factory */).unwrap();

// There's also a by-value method, // but it has slightly steeper requirements:

[derive(Debug)]

struct MyAny; impl std::borrow::Borrow for MyAny { //…

fn borrow(&self) -> &dyn Any { self }

}

impl std::borrow::BorrowMut for MyAny { //…

fn borrow_mut(&mut self) -> &mut dyn Any { self }

}

let _: &dyn Any = map .emplace(3, MyAny) .unwrap(/* or key and value */);

// As usual the map's values can be pinned: let map: Pin> = map.pin();

// And then further value references are pinned: let _: Pin<&dyn Any> = map.emplace(4, MyAny).unwrap();

// To immediately get an unpinned reference, just use .as_unpinned(): let : &dyn Any = map.asunpinned().emplace(5, MyAny).unwrap(); ```

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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.

Code of Conduct

Changelog

Versioning

pinus strictly follows Semantic Versioning 2.0.0 with the following exceptions:

• The minor version will not reset to 0 on major version changes (except for v1).
  Consider it the global feature level.
• The patch version will not reset to 0 on major or minor version changes (except for v0.1 and v1).
  Consider it the global patch level.

This includes the Rust version requirement specified above.
Earlier Rust versions may be compatible, but this can change with minor or patch releases.

Which versions are affected by features and patches can be determined from the respective headings in CHANGELOG.md.