Merge pull request #318 from meilisearch/improve-doc

Show ranges of slice in the doc

README.md

@@ -6,6 +6,7 @@
 [![Docs](https://docs.rs/heed/badge.svg)](https://docs.rs/heed)
 [![dependency status](https://deps.rs/repo/github/meilisearch/heed/status.svg)](https://deps.rs/repo/github/meilisearch/heed)
 [![Build](https://github.com/meilisearch/heed/actions/workflows/rust.yml/badge.svg)](https://github.com/meilisearch/heed/actions/workflows/rust.yml)
+![Discord](https://img.shields.io/discord/1006923006964154428?style=flat&logo=discord&logoColor=ffffff&label=&labelColor=6A7EC2&color=7389D8&link=https%3A%2F%2Fdiscord.com%2Fchannels%2F1006923006964154428%2F1347203493106024528)
 
 A Rust-centric [LMDB](https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database) abstraction with minimal overhead. This library enables the storage of various Rust types within LMDB, extending support to include Serde-compatible types. It not only supports the LMDB `mdb.master` branch but also the `mdb.master3` branch which features encryption-at-rest and checksumming.
 

heed/src/databases/database.rs

@@ -1231,6 +1231,45 @@ impl<KC, DC, C> Database<KC, DC, C> {
     /// wtxn.commit()?;
     /// # Ok(()) }
     /// ```
+    ///
+    /// It can be complex to work with ranges of slices and using
+    /// the `..` or `..=` range syntax is not the best way to deal
+    /// with that. We highly recommend using the [`Bound`](std::ops::Bound) enum for that.
+    ///
+    /// ```
+    /// # use std::fs;
+    /// # use std::path::Path;
+    /// use std::ops::Bound;
+    /// # use heed::EnvOpenOptions;
+    /// use heed::Database;
+    /// use heed::types::*;
+    /// use heed::byteorder::BigEndian;
+    ///
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let dir = tempfile::tempdir()?;
+    /// # let env = unsafe { EnvOpenOptions::new()
+    /// #     .map_size(10 * 1024 * 1024) // 10MB
+    /// #     .max_dbs(30)
+    /// #     .open(dir.path())?
+    /// # };
+    ///
+    /// let mut wtxn = env.write_txn()?;
+    /// let db: Database<Bytes, Unit> = env.create_database(&mut wtxn, None)?;
+    ///
+    /// // make sure to create slices and not ref array
+    /// // by using the [..] syntax.
+    /// let start = &[0, 0, 0][..];
+    /// let end = &[9, 0, 0][..];
+    ///
+    /// // equivalent to start..end
+    /// let range = (Bound::Included(start), Bound::Excluded(end));
+    ///
+    /// let iter = db.range(&mut wtxn, &range)?;
+    ///
+    /// drop(iter);
+    /// wtxn.commit()?;
+    /// # Ok(()) }
+    /// ```
     pub fn range<'a, 'txn, R>(
         &self,
         txn: &'txn RoTxn,

heed/src/databases/encrypted_database.rs

@@ -1064,6 +1064,45 @@ impl<KC, DC, C> EncryptedDatabase<KC, DC, C> {
     /// wtxn.commit()?;
     /// # Ok(()) }
     /// ```
+    ///
+    /// It can be complex to work with ranges of slices and using
+    /// the `..` or `..=` range syntax is not the best way to deal
+    /// with that. We highly recommend using the [`Bound`](std::ops::Bound) enum for that.
+    ///
+    /// ```
+    /// # use std::fs;
+    /// # use std::path::Path;
+    /// use std::ops::Bound;
+    /// # use heed::EnvOpenOptions;
+    /// use heed::Database;
+    /// use heed::types::*;
+    /// use heed::byteorder::BigEndian;
+    ///
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let dir = tempfile::tempdir()?;
+    /// # let env = unsafe { EnvOpenOptions::new()
+    /// #     .map_size(10 * 1024 * 1024) // 10MB
+    /// #     .max_dbs(30)
+    /// #     .open(dir.path())?
+    /// # };
+    ///
+    /// let mut wtxn = env.write_txn()?;
+    /// let db: Database<Bytes, Unit> = env.create_database(&mut wtxn, None)?;
+    ///
+    /// // make sure to create slices and not ref array
+    /// // by using the [..] syntax.
+    /// let start = &[0, 0, 0][..];
+    /// let end = &[9, 0, 0][..];
+    ///
+    /// // equivalent to start..end
+    /// let range = (Bound::Included(start), Bound::Excluded(end));
+    ///
+    /// let iter = db.range(&mut wtxn, &range)?;
+    ///
+    /// drop(iter);
+    /// wtxn.commit()?;
+    /// # Ok(()) }
+    /// ```
     pub fn range<'a, 'txn, R>(
         &self,
         txn: &'txn mut RoTxn,