changeset 418:4c3bc235f465

all: Further improve documentation.
author Lewin Bormann <lbo@spheniscida.de>
date Fri, 13 Oct 2017 11:48:41 +0000
parents a9a137489453
children e38997b52bb1
files Cargo.toml src/db_iter.rs src/error.rs src/lib.rs src/options.rs src/table_cache.rs src/write_batch.rs
diffstat 7 files changed, 17 insertions(+), 41 deletions(-) [+]
line wrap: on
line diff
--- a/Cargo.toml	Fri Oct 13 11:13:27 2017 +0000
+++ b/Cargo.toml	Fri Oct 13 11:48:41 2017 +0000
@@ -1,6 +1,6 @@
 [package]
 name = "rusty-leveldb"
-version = "0.1.1"
+version = "0.1.2"
 authors = ["Lewin Bormann <lbo@spheniscida.de>"]
 description = "A compatible re-implementation of LevelDB in Rust"
 repository = "https://bitbucket.org/dermesser/leveldb-rs"
--- a/src/db_iter.rs	Fri Oct 13 11:13:27 2017 +0000
+++ b/src/db_iter.rs	Fri Oct 13 11:48:41 2017 +0000
@@ -14,6 +14,7 @@
 
 const READ_BYTES_PERIOD: isize = 1048576;
 
+/// DBIterator is an iterator over the contents of a database.
 pub struct DBIterator {
     // A user comparator.
     cmp: Rc<Box<Cmp>>,
--- a/src/error.rs	Fri Oct 13 11:13:27 2017 +0000
+++ b/src/error.rs	Fri Oct 13 11:48:41 2017 +0000
@@ -5,6 +5,7 @@
 use std::result;
 use std::sync;
 
+/// StatusCode describes various failure modes of database operations.
 #[derive(Clone, Debug, PartialEq)]
 #[allow(dead_code)]
 pub enum StatusCode {
@@ -22,6 +23,8 @@
     Unknown,
 }
 
+/// Status encapsulates a `StatusCode` and an error message. It can be displayed, and also
+/// implements `Error`.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Status {
     pub code: StatusCode,
--- a/src/lib.rs	Fri Oct 13 11:13:27 2017 +0000
+++ b/src/lib.rs	Fri Oct 13 11:48:41 2017 +0000
@@ -13,7 +13,7 @@
 //!
 //! let mut iter = db.new_iter().unwrap();
 //! // Note: For efficiency reasons, it's recommended to use advance() and current() instead of
-//! // next().
+//! // next() when iterating over many elements.
 //! assert_eq!((b"Hello".to_vec(), b"World".to_vec()), iter.next().unwrap());
 //!
 //! db.delete(b"Hello").unwrap();
@@ -70,8 +70,8 @@
 pub use cmp::{Cmp, DefaultCmp};
 pub use db_impl::DB;
 pub use db_iter::DBIterator;
+pub use error::{Result, Status};
 pub use filter::{BloomPolicy, FilterPolicy};
-pub use infolog::Logger;
 pub use options::{in_memory, Options};
 pub use types::LdbIterator;
 pub use write_batch::WriteBatch;
--- a/src/options.rs	Fri Oct 13 11:13:27 2017 +0000
+++ b/src/options.rs	Fri Oct 13 11:48:41 2017 +0000
@@ -97,20 +97,3 @@
     o.log = Some(share(infolog::stderr()));
     o
 }
-
-impl Options {
-    /// Set the comparator to use in all operations and structures that need to compare keys.
-    ///
-    /// DO NOT set the comparator after having written any record with a different comparator.
-    /// If the comparator used differs from the one used when writing a database that is being
-    /// opened, the library is free to panic.
-    pub fn set_comparator(&mut self, c: Box<Cmp>) {
-        self.cmp = Rc::new(c);
-    }
-
-    /// Set the environment to use. The default is `PosixDiskEnv`; `MemEnv` provides a fully
-    /// in-memory environment.
-    pub fn set_env(&mut self, e: Box<Env>) {
-        self.env = Rc::new(e);
-    }
-}
--- a/src/table_cache.rs	Fri Oct 13 11:13:27 2017 +0000
+++ b/src/table_cache.rs	Fri Oct 13 11:48:41 2017 +0000
@@ -127,7 +127,7 @@
         // Tests that a table can be written to a MemFS file, read back by the table cache and
         // parsed/iterated by the table reader.
         let mut opt = options::for_test();
-        opt.set_env(Box::new(MemEnv::new()));
+        opt.env = Rc::new(Box::new(MemEnv::new()));
         let dbname = "testdb1";
         let tablename = table_file_name(dbname, 123);
         let tblpath = Path::new(&tablename);
--- a/src/write_batch.rs	Fri Oct 13 11:13:27 2017 +0000
+++ b/src/write_batch.rs	Fri Oct 13 11:48:41 2017 +0000
@@ -16,7 +16,6 @@
 /// [tag: 1, keylen: ~var, key: keylen, vallen: ~var, val: vallen]
 pub struct WriteBatch {
     entries: Vec<u8>,
-    sync: bool,
 }
 
 impl WriteBatch {
@@ -24,29 +23,16 @@
         let mut v = Vec::with_capacity(128);
         v.resize(HEADER_SIZE, 0);
 
-        WriteBatch {
-            entries: v,
-            sync: false,
-        }
+        WriteBatch { entries: v }
     }
 
-    /// set_sync allows for forcing a flush for this batch.
-    pub fn set_sync(&mut self, sync: bool) {
-        self.sync = sync;
-    }
-
+    /// Initializes a WriteBatch with a serialized WriteBatch.
     pub fn set_contents(&mut self, from: &[u8]) {
         self.entries.clear();
         self.entries.extend_from_slice(from);
     }
 
-    fn from(buf: Vec<u8>) -> WriteBatch {
-        WriteBatch {
-            entries: buf,
-            sync: false,
-        }
-    }
-
+    /// Adds an entry to a WriteBatch, to be added to the database.
     #[allow(unused_assignments)]
     pub fn put(&mut self, k: &[u8], v: &[u8]) {
         self.entries.write(&[ValueType::TypeValue as u8]).unwrap();
@@ -59,6 +45,7 @@
         self.set_count(c + 1);
     }
 
+    /// Marks an entry to be deleted from the database.
     #[allow(unused_assignments)]
     pub fn delete(&mut self, k: &[u8]) {
         self.entries.write(&[ValueType::TypeDeletion as u8]).unwrap();
@@ -69,23 +56,25 @@
         self.set_count(c + 1);
     }
 
+    /// Clear the contents of a WriteBatch.
     pub fn clear(&mut self) {
         self.entries.clear()
     }
 
-    pub fn byte_size(&self) -> usize {
+    fn byte_size(&self) -> usize {
         self.entries.len()
     }
 
-    pub fn set_count(&mut self, c: u32) {
+    fn set_count(&mut self, c: u32) {
         c.encode_fixed(&mut self.entries[COUNT_OFFSET..COUNT_OFFSET + 4]);
     }
 
+    /// Returns how many operations are in a batch.
     pub fn count(&self) -> u32 {
         u32::decode_fixed(&self.entries[COUNT_OFFSET..COUNT_OFFSET + 4])
     }
 
-    pub fn set_sequence(&mut self, s: SequenceNumber) {
+    fn set_sequence(&mut self, s: SequenceNumber) {
         s.encode_fixed(&mut self.entries[SEQNUM_OFFSET..SEQNUM_OFFSET + 8]);
     }