Checksum::validate now accepts either by borrow or by value

Additionally, made some example and doc improvements

Author: jimvdl

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rs-cache"
-version = "0.8.7" # Remember to update usage
+version = "0.8.8" # Remember to update usage
 authors = ["jimvdl <jimvdlind@gmail.com>"]
 edition = "2021"
 license = "MIT"

README.md

@@ -32,7 +32,11 @@ Useful links:\
 
 ## Safety
 
-In order to read bytes in a high performant way the cache uses [memmap2](https://crates.io/crates/memmap2). This can be unsafe because of its potential for _Undefined Behaviour_ when the underlying file is subsequently modified, in or out of process. Using `Mmap` here is safe because the RuneScape cache is a read-only binary file system. The map will remain valid even after the `File` is dropped, it's completely independent of the `File` used to create it. Therefore, the use of unsafe is not propagated outwards. When the `Cache` is dropped memory will be subsequently unmapped.
+In order to read bytes in a high performant way the cache uses
+[memmap2](https://crates.io/crates/memmap2). This can be unsafe because of its potential for
+_Undefined Behaviour_ when the underlying file is subsequently modified, in or out of process. 
+
+Using `Mmap` here is safe because the RuneScape cache is a read-only binary file system. The map will remain valid even after the `File` is dropped, it's completely independent of the `File` used to create it. Therefore, the use of unsafe is not propagated outwards. When the `Cache` is dropped memory will be subsequently unmapped.
 
 ## Features
 
@@ -41,50 +45,63 @@ A lot of types derive [serde](https://crates.io/crates/serde)'s `Serialize` and
 
 ## Quick Start
 
-For an instance that stays local to this thread you can simply use:
+The recommended usage would be to wrap it using
+[`std::sync::LazyLock`](https://doc.rust-lang.org/std/sync/struct.LazyLock.html) making it the
+easiest way to access cache data from anywhere and at any time. No need for an `Arc` or a `Mutex`
+because `Cache` will always be `Send + Sync`.
 ```rust
 use rscache::Cache;
+use std::sync::LazyLock;
 
-let cache = Cache::new("./data/osrs_cache").unwrap();
+static CACHE: LazyLock<Cache> = LazyLock::new(|| {
+    Cache::new("./data/osrs_cache")
+        .expect("cache files to be successfully memory mapped")
+});
 
-let index_id = 2; // Config index.
-let archive_id = 10; // Archive containing item definitions.
+std::thread::spawn(|| -> Result<(), rscache::Error> {
+    let buffer = CACHE.read(0, 10)?;
+    Ok(())
+});
 
-let buffer = cache.read(index_id, archive_id).unwrap();
+std::thread::spawn(|| -> Result<(), rscache::Error> {
+    let buffer = CACHE.read(0, 10)?;
+    Ok(())
+});
 ```
 
-If you want to share the instance over multiple threads you can do so by wrapping it in an [`Arc`](https://doc.rust-lang.org/std/sync/struct.Arc.html)
+For an instance that stays local to this thread you can simply use:
 ```rust
 use rscache::Cache;
-use std::sync::Arc;
 
-let cache = Arc::new(Cache::new("./data/osrs_cache").unwrap());
+let cache = Cache::new("./data/osrs_cache")
+        .expect("cache files to be successfully memory mapped");
 
-let c = Arc::clone(&cache);
-std::thread::spawn(move || {
-    c.read(0, 10).unwrap();
-});
+let index_id = 2; // Config index.
+let archive_id = 10; // Archive containing item definitions.
 
-std::thread::spawn(move || {
-    cache.read(0, 10).unwrap();
-});
+let buffer = cache.read(index_id, archive_id)?;
 ```
 
-The recommended usage would be to wrap it using [`once_cell`](https://docs.rs/once_cell/latest/once_cell/) making it the easiest way to access cache data from anywhere and at any time. No need for an `Arc` or a `Mutex` because `Cache` will always be `Send` & `Sync`.
+If you want to share the instance over multiple threads you can do so by wrapping it in an
+[`Arc`](https://doc.rust-lang.org/std/sync/struct.Arc.html)
 ```rust
 use rscache::Cache;
-use once_cell::sync::Lazy;
-
-static CACHE: Lazy<Cache> = Lazy::new(|| {
-    Cache::new("./data/osrs_cache").unwrap()
-});
+use std::sync::Arc;
 
-std::thread::spawn(move || {
-    CACHE.read(0, 10).unwrap();
+let cache = Arc::new(Cache::new("./data/osrs_cache")
+        .expect("cache files to be successfully memory mapped"));
+    
+let c = Arc::clone(&cache);
+std::thread::spawn(move || -> Result<(), rscache::Error> {
+    // use the cloned handle
+    let buffer = c.read(0, 10)?;
+    Ok(())
 });
-
-std::thread::spawn(move || {
-    CACHE.read(0, 10).unwrap();
+ 
+std::thread::spawn(move || -> Result<(), rscache::Error> {
+    // use handle directly and take ownership
+    let buffer = cache.read(0, 10)?;
+    Ok(())
 });
 ```
 
@@ -99,7 +116,7 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-rs-cache = "0.8.6"
+rs-cache = "0.8.8"
 ```
 
 Examples can be found in the [examples](examples/) directory which include both update protocols.

src/checksum.rs

@@ -23,7 +23,7 @@
 //! # }
 //! ```
 
-use std::iter::IntoIterator;
+use std::{borrow::Borrow, iter::IntoIterator};
 use std::slice::Iter;
 
 use crate::{error::ValidateError, Cache};
@@ -123,7 +123,7 @@ impl Checksum {
     /// 
     /// Note: It defaults to OSRS. RS3 clients use RSA to encrypt
     /// network traffic, which includes the checksum. When encoding for RS3 clients
-    /// use [`RsaChecksum`](RsaChecksum) instead.
+    /// use [`RsaChecksum`] instead.
     ///
     /// After encoding the checksum it can be sent to the client.
     ///
@@ -165,13 +165,32 @@ impl Checksum {
 
     /// Validates the given crcs from the client with the internal crcs of this cache.
     /// 
+    /// ```
+    /// # use rscache::{Cache, error::Error};
+    /// # use rscache::checksum::Checksum;
+    /// # fn main() -> Result<(), Error> {
+    /// # let cache = Cache::new("./data/osrs_cache")?;
+    /// let checksum = Checksum::new(&cache)?;
+    ///
+    /// let crcs = [
+    ///     1593884597, 1029608590, 16840364, 4209099954, 3716821437, 165713182, 686540367, 4262755489,
+    ///     2208636505, 3047082366, 586413816, 2890424900, 3411535427, 3178880569, 153718440,
+    ///     3849392898, 3628627685, 2813112885, 1461700456, 2751169400, 2927815226,
+    /// ];
+    ///
+    /// assert!(checksum.validate(crcs).is_ok());
+    /// # Ok(())
+    /// # }
+    /// ```
+    /// 
     /// # Errors
     /// 
     /// When the lengths of the crc iterators don't match up because too many or too few indices 
     /// were shared between the client and the server, or if a crc value mismatches.
-    pub fn validate<'b, I>(&self, crcs: I) -> Result<(), ValidateError>
+    pub fn validate<I>(&self, crcs: I) -> Result<(), ValidateError>
     where
-        I: IntoIterator<Item = &'b u32>,
+        I: IntoIterator,
+        I::Item: Borrow<u32>,
         <I as IntoIterator>::IntoIter: ExactSizeIterator,
     {
         let crcs = crcs.into_iter();
@@ -189,11 +208,11 @@ impl Checksum {
             .zip(crcs)
             .enumerate()
         {
-            if internal != external {
+            if internal != external.borrow() {
                 return Err(ValidateError::InvalidCrc {
                     idx: index,
                     internal: *internal,
-                    external: *external,
+                    external: *external.borrow(),
                 });
             }
         }

src/lib.rs

@@ -1,112 +1,118 @@
 //! A read-only, high-level, virtual file API for the RuneScape cache.
 //!
-//! This crate provides high performant data reads into the [Oldschool
-//! RuneScape] and [RuneScape 3] cache file systems. It can read the necessary
-//! data to synchronize the client's cache with the server. There are also some
-//! [loaders](#loaders) that give access to definitions from the cache such as
-//! items or npcs.
+//! This crate provides high performant data reads into the [Oldschool RuneScape] and [RuneScape 3]
+//! cache file systems. It can read the necessary data to synchronize the client's cache with the
+//! server. There are also some [loaders](#loaders) that give access to definitions from the cache
+//! such as items or npcs.
 //!
-//! For read-heavy workloads, a writer can be used to prevent continuous buffer
-//! allocations. By default every read will allocate a writer with the correct
-//! capacity.
+//! For read-heavy workloads, a writer can be used to prevent continuous buffer allocations. By
+//! default every read will allocate a writer with the correct capacity.
 //!
-//! RuneScape's chat system uses huffman coding to compress messages. In order
-//! to decompress them this library has a [`Huffman`] implementation.
+//! RuneScape's chat system uses huffman coding to compress messages. In order to decompress them
+//! this library has a [`Huffman`] implementation.
 //!
-//! When a RuneScape client sends game packets the id's are encoded and can be
-//! decoded with the [`IsaacRand`] implementation. These id's are encoded by the
-//! client in a predictable random order which can be reversed if the server has
-//! its own `IsaacRand` with the same encoder/decoder keys. These keys are sent
-//! by the client on login and are user specific. It will only send encoded
+//! When a RuneScape client sends game packets the id's are encoded and can be decoded with the
+//! [`IsaacRand`] implementation. These id's are encoded by the client in a predictable random order
+//! which can be reversed if the server has its own `IsaacRand` with the same encoder/decoder keys.
+//! These keys are sent by the client on login and are user specific. It will only send encoded
 //! packet id's if the packets are game packets.
 //!
-//! Note that this crate is still evolving; both OSRS & RS3 are not fully
-//! supported/implemented and will probably contain bugs or miss core features.
-//! If you require features or find bugs consider [opening an issue].
+//! Note that this crate is still evolving; both OSRS & RS3 are not fully supported/implemented and
+//! will probably contain bugs or miss core features. If you require features or find bugs consider
+//! [opening an issue].
 //!
 //! # Safety
 //!
-//! In order to read bytes in a high performant way the cache uses [memmap2].
-//! This can be unsafe because of its potential for _Undefined Behaviour_ when
-//! the underlying file is subsequently modified, in or out of process. Using
-//! `Mmap` here is safe because the RuneScape cache is a read-only binary file
-//! system. The map will remain valid even after the `File` is dropped, it's
-//! completely independent of the `File` used to create it. Therefore, the use
-//! of unsafe is not propagated outwards. When the `Cache` is dropped memory
-//! will be subsequently unmapped.
+//! In order to read bytes in a high performant way the cache uses [memmap2]. This can be unsafe
+//! because of its potential for _Undefined Behaviour_ when the underlying file is subsequently
+//! modified, in or out of process.
+//!
+//! Using `Mmap` here is safe because the RuneScape cache is a read-only binary file system. The map
+//! will remain valid even after the `File` is dropped, it's completely independent of the `File`
+//! used to create it. Therefore, the use of unsafe is not propagated outwards. When the `Cache` is
+//! dropped memory will be subsequently unmapped.
 //!
 //! # Features
 //!
-//! The cache's protocol defaults to OSRS. In order to use the RS3 protocol you
-//! can enable the `rs3` feature flag. A lot of types derive [serde]'s
-//! `Serialize` and `Deserialize`. The `serde-derive` feature flag can be used
-//! to enable (de)serialization on any compatible types.
+//! The cache's protocol defaults to OSRS. In order to use the RS3 protocol you can enable the `rs3`
+//! feature flag. A lot of types derive [serde]'s `Serialize` and `Deserialize`. The `serde-derive`
+//! feature flag can be used to enable (de)serialization on any compatible types.
 //!
 //! # Quick Start
 //!
+//! The recommended usage would be to wrap it using
+//! [`std::sync::LazyLock`](https://doc.rust-lang.org/std/sync/struct.LazyLock.html) making it the
+//! easiest way to access cache data from anywhere and at any time. No need for an `Arc` or a
+//! `Mutex` because `Cache` will always be `Send + Sync`.
+//! ```rust
+//! use rscache::Cache;
+//! use std::sync::LazyLock;
+//!
+//! static CACHE: LazyLock<Cache> = LazyLock::new(|| {
+//!     Cache::new("./data/osrs_cache")
+//!         .expect("cache files to be successfully memory mapped")
+//! });
+//!
+//! std::thread::spawn(|| -> Result<(), rscache::Error> {
+//!     let buffer = CACHE.read(0, 10)?;
+//!     Ok(())
+//! });
+//!
+//! std::thread::spawn(|| -> Result<(), rscache::Error> {
+//!     let buffer = CACHE.read(0, 10)?;
+//!     Ok(())
+//! });
+//! ```
+//!
 //! For an instance that stays local to this thread you can simply use:
 //! ```
 //! use rscache::Cache;
-//! 
-//! let cache = Cache::new("./data/osrs_cache").unwrap();
-//! 
+//!
+//! # fn main() -> Result<(), rscache::Error> {
+//! let cache = Cache::new("./data/osrs_cache")
+//!         .expect("cache files to be successfully memory mapped");
+//!
 //! let index_id = 2; // Config index.
 //! let archive_id = 10; // Archive containing item definitions.
-//! 
-//! let buffer = cache.read(index_id, archive_id).unwrap();
+//!
+//! let buffer = cache.read(index_id, archive_id)?;
+//! # Ok(())
+//! # }
 //! ```
-//! 
-//! If you want to share the instance over multiple threads you can do so by
-//! wrapping it in an
+//!
+//! If you want to share the instance over multiple threads you can do so by wrapping it in an
 //! [`Arc`](https://doc.rust-lang.org/std/sync/struct.Arc.html)
 //! ```
 //! use rscache::Cache;
 //! use std::sync::Arc;
-//! 
-//! let cache = Arc::new(Cache::new("./data/osrs_cache").unwrap());
+//!
+//! let cache = Arc::new(Cache::new("./data/osrs_cache")
+//!         .expect("cache files to be successfully memory mapped"));
 //!     
 //! let c = Arc::clone(&cache);
-//! std::thread::spawn(move || {
-//!     c.read(0, 10).unwrap();
+//! std::thread::spawn(move || -> Result<(), rscache::Error> {
+//!     // use the cloned handle
+//!     let buffer = c.read(0, 10)?;
+//!     Ok(())
 //! });
 //!  
-//! std::thread::spawn(move || {
-//!     cache.read(0, 10).unwrap();
-//! });
-//! ```
-//! 
-//! The recommended usage would be to wrap it using
-//! [`once_cell`](https://docs.rs/once_cell/latest/once_cell/) making it the
-//! easiest way to access cache data from anywhere and at any time. No need for
-//! an `Arc` or a `Mutex` because `Cache` will always be `Send` & `Sync`.
-//! ```
-//! use rscache::Cache;
-//! use once_cell::sync::Lazy;
-//! 
-//! static CACHE: Lazy<Cache> = Lazy::new(|| {
-//!     Cache::new("./data/osrs_cache").unwrap()
-//! });
-//! 
-//! std::thread::spawn(move || {
-//!     CACHE.read(0, 10).unwrap();
-//! });
-//! 
-//! std::thread::spawn(move || {
-//!     CACHE.read(0, 10).unwrap();
+//! std::thread::spawn(move || -> Result<(), rscache::Error> {
+//!     // use handle directly and take ownership
+//!     let buffer = cache.read(0, 10)?;
+//!     Ok(())
 //! });
 //! ```
 //!
 //! # Loaders
 //!
-//! In order to get [definitions](crate::definition) you can look at the
-//! [loaders](crate::loader) this library provides. The loaders use the cache as
-//! a dependency to parse in their data and cache the relevant definitions
-//! internally. The loader module also tells you how to make a loader if this
-//! crate doesn't (yet) provide it.
+//! In order to get [definitions](crate::definition) you can look at the [loaders](crate::loader)
+//! this library provides. The loaders use the cache as a dependency to parse in their data and
+//! cache the relevant definitions internally. The loader module also tells you how to make a loader
+//! if this crate doesn't (yet) provide it.
 //!
-//! Note: Some loaders cache these definitions lazily because of either the size
-//! of the data or the performance. The map loader for example is both slow and
-//! large so caching is by default lazy. Lazy loaders require mutability.
+//! Note: Some loaders cache these definitions lazily because of either the size of the data or the
+//! performance. The map loader for example is both slow and large so caching is by default lazy.
+//! Lazy loaders require mutability.
 //!
 //! [Oldschool RuneScape]: https://oldschool.runescape.com/
 //! [RuneScape 3]: https://www.runescape.com/