Standardizes the Index::create_* APIs (#317)

* Pull all creation methods next to each other

The goal here is to make it clear which methods are performing the
same function, and to assist with standardizing the API calls.

* Make `from_directory` private

This seems to be an internal function, so lets make it internal.

* Rename `create` to `create_in_dir`

This lets the name match the `create_in_ram` pattern and opens up
`create` for the generic implementation.

* Implement the generic create function

All of the create methods now delegate to the common create function
and future `create_in_*` functions now have a clear pattern
to follow as well

examples/custom_tokenizer.rs

@@ -61,7 +61,7 @@ fn run_example(index_path: &Path) -> tantivy::Result<()> {
     //
     // This will actually just save a meta.json
     // with our schema in the directory.
-    let index = Index::create(index_path, schema.clone())?;
+    let index = Index::create_in_dir(index_path, schema.clone())?;
 
     // here we are registering our custome tokenizer
     // this will store tokens of 3 characters each

examples/simple_search.rs

@@ -64,7 +64,7 @@ fn run_example(index_path: &Path) -> tantivy::Result<()> {
     //
     // This will actually just save a meta.json
     // with our schema in the directory.
-    let index = Index::create(index_path, schema.clone())?;
+    let index = Index::create_in_dir(index_path, schema.clone())?;
 
     // To insert document we need an index writer.
     // There must be only one writer at a time.

src/core/index.rs

@@ -45,18 +45,20 @@ pub struct Index {
 }
 
 impl Index {
+    /// Create a new index from a directory.
+    fn from_directory(mut directory: ManagedDirectory, schema: Schema) -> Result<Index> {
+        save_new_metas(schema.clone(), 0, directory.borrow_mut())?;
+        let metas = IndexMeta::with_schema(schema);
+        Index::create_from_metas(directory, &metas)
+    }
+
     /// Creates a new index using the `RAMDirectory`.
     ///
     /// The index will be allocated in anonymous memory.
     /// This should only be used for unit tests.
     pub fn create_in_ram(schema: Schema) -> Index {
         let ram_directory = RAMDirectory::create();
-        // unwrap is ok here
-        let directory = ManagedDirectory::new(ram_directory).expect(
-            "Creating a managed directory from a brand new RAM directory \
-             should never fail.",
-        );
-        Index::from_directory(directory, schema).expect("Creating a RAMDirectory should never fail")
+        Index::create(ram_directory, schema).expect("Creating a RAMDirectory should never fail")
     }
 
     /// Creates a new index in a given filepath.
@@ -64,15 +66,9 @@ impl Index {
     ///
     /// If a previous index was in this directory, then its meta file will be destroyed.
     #[cfg(feature = "mmap")]
-    pub fn create<P: AsRef<Path>>(directory_path: P, schema: Schema) -> Result<Index> {
+    pub fn create_in_dir<P: AsRef<Path>>(directory_path: P, schema: Schema) -> Result<Index> {
         let mmap_directory = MmapDirectory::open(directory_path)?;
-        let directory = ManagedDirectory::new(mmap_directory)?;
-        Index::from_directory(directory, schema)
-    }
-
-    /// Accessor for the tokenizer manager.
-    pub fn tokenizers(&self) -> &TokenizerManager {
-        &self.tokenizers
+        Index::create(mmap_directory, schema)
     }
 
     /// Creates a new index in a temp directory.
@@ -86,7 +82,12 @@ impl Index {
     #[cfg(feature = "mmap")]
     pub fn create_from_tempdir(schema: Schema) -> Result<Index> {
         let mmap_directory = MmapDirectory::create_from_tempdir()?;
-        let directory = ManagedDirectory::new(mmap_directory)?;
+        Index::create(mmap_directory, schema)
+    }
+
+    /// Creates a new index given an implementation of the trait `Directory`
+    pub fn create<Dir: Directory>(dir: Dir, schema: Schema) -> Result<Index> {
+        let directory = ManagedDirectory::new(dir)?;
         Index::from_directory(directory, schema)
     }
 
@@ -103,6 +104,11 @@ impl Index {
         Ok(index)
     }
 
+    /// Accessor for the tokenizer manager.
+    pub fn tokenizers(&self) -> &TokenizerManager {
+        &self.tokenizers
+    }
+
     /// Open the index using the provided directory
     pub fn open_directory<D: Directory>(directory: D) -> Result<Index> {
         let directory = ManagedDirectory::new(directory)?;
@@ -117,13 +123,6 @@ impl Index {
         Index::open_directory(mmap_directory)
     }
 
-    /// Create a new index from a directory.
-    pub fn from_directory(mut directory: ManagedDirectory, schema: Schema) -> Result<Index> {
-        save_new_metas(schema.clone(), 0, directory.borrow_mut())?;
-        let metas = IndexMeta::with_schema(schema);
-        Index::create_from_metas(directory, &metas)
-    }
-
     /// Reads the index meta file from the directory.
     pub fn load_metas(&self) -> Result<IndexMeta> {
         load_metas(self.directory())

src/lib.rs

@@ -55,7 +55,7 @@
 //!
 //! // Indexing documents
 //!
-//! let index = Index::create(index_path, schema.clone())?;
+//! let index = Index::create_in_dir(index_path, schema.clone())?;
 //!
 //! // Here we use a buffer of 100MB that will be split
 //! // between indexing threads.