From 98c73ce18c3a921aaf5891c3a7381d41ed64caa6 Mon Sep 17 00:00:00 2001 From: Octavian Oncescu Date: Mon, 8 Jul 2019 17:48:23 +0200 Subject: [PATCH] Added README and License --- LICENSE.txt | 25 +++++++++++++++++++++++++ README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ src/lib.rs | 42 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 118 insertions(+) create mode 100644 LICENSE.txt create mode 100644 README.md diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..9a3377d --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,25 @@ +Copyright 2019 Octavian Oncescu + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..fbc4a3c --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# HashCow +[![Build Status]][travis] [![Discord Badge]][Discord] [![Latest Version]][crates.io] [![Documentation]][docs.rs] + +HashCow is a HashMap implementation with copy-on-write keys and values. + +--- + +Originally built for optimizing the [Purple Protocol](https://github.com/purpleprotocol/purple), this library provides a way to link HashMaps in memory that have duplicate entries. Instead of the duplicate data, it is instead borrowed and it is only cloned when mutation is needed. + +### Using HashCow +```rust +use hashcow::{Form, CowHashMap}; + +let mut hm: CowHashMap = CowHashMap::new(); + +// We insert an owned value in the map +hm.insert_owned("key".to_owned(), vec![1, 2, 3]); +assert_eq!(hm.entry_form(&"key").unwrap(), Form::Owned); + +// We now create a clone with borrowed fields +let mut hm_clone = hm.borrow_fields(); +assert_eq!(hm_clone.entry_form(&"key").unwrap(), Form::Borrowed); + +// On mutation, the borrowed entry is cloned +let entry = hm_clone.get_mut(&"key").unwrap(); + +// We now mutate the cloned value +*entry = vec![4, 5, 6]; +assert_eq!(hm_clone.entry_form(&"key").unwrap(), Form::Owned); + +// The two maps now have different entries for the same key +assert_eq!(hm.get(&"key").unwrap(), &[1, 2, 3]); +assert_eq!(hm_clone.get(&"key").unwrap(), &[4, 5, 6]); +``` + +### Contributing +We welcome anyone wishing to contribute to HashCow! Check out the [issues section][issues] of the repository before starting out. + +### License + +HashCow is licensed under the MIT license. + +[Build Status]: https://travis-ci.org/purpleprotocol/hashcow.svg?branch=master +[Discord Badge]: https://img.shields.io/discord/435827644915777536.svg +[Discord]: https://discord.gg/eGBzyaA +[travis]: https://travis-ci.org/purpleprotocol/hashcow +[crates.io]: https://crates.io/crates/hashcow +[Latest Version]: https://img.shields.io/crates/v/hashcow.svg +[Documentation]: https://docs.rs/hashcow/badge.svg +[docs.rs]: https://docs.rs/hashcow +[issues]: https://github.com/purpleprotocol/hashcow/issues diff --git a/src/lib.rs b/src/lib.rs index 45f65ab..5ec9a58 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,5 +1,47 @@ // Copyright 2019 Octavian Oncescu + +//! # HashCow +//! +//! HashCow is a HashMap implementation with copy-on-write keys and values. +//! +//! --- +//! +//! Originally built for optimizing the [Purple Protocol](https://github.com/purpleprotocol/purple), this library provides a way to link HashMaps in memory that have duplicate entries. Instead of the duplicate data, it is instead borrowed and it is only cloned when mutation is needed. +//! +//! ### Using HashCow +//! ```rust +//! use hashcow::{Form, CowHashMap}; +//! +//! let mut hm: CowHashMap = CowHashMap::new(); +//! +//! // We insert an owned value in the map +//! hm.insert_owned("key".to_owned(), vec![1, 2, 3]); +//! assert_eq!(hm.entry_form(&"key").unwrap(), Form::Owned); +//! +//! // We now create a clone with borrowed fields +//! let mut hm_clone = hm.borrow_fields(); +//! assert_eq!(hm_clone.entry_form(&"key").unwrap(), Form::Borrowed); +//! +//! // On mutation, the borrowed entry is cloned +//! let entry = hm_clone.get_mut(&"key").unwrap(); +//! +//!// We now mutate the cloned value +//! *entry = vec![4, 5, 6]; +//! assert_eq!(hm_clone.entry_form(&"key").unwrap(), Form::Owned); +//! +//! // The two maps now have different entries for the same key +//! assert_eq!(hm.get(&"key").unwrap(), &[1, 2, 3]); +//! assert_eq!(hm_clone.get(&"key").unwrap(), &[4, 5, 6]); +//! ``` +//! +//! ### Contributing +//! We welcome anyone wishing to contribute to HashCow! Check out the [issues section][issues] of the repository before starting out. +//! +//! ### License +//! +//! HashCow is licensed under the MIT license. + use hashbrown::HashMap; use std::borrow::{Borrow, Cow, ToOwned}; use std::hash::Hash;