Tantivy

https://docs.rs/tantivy/latest/tantivy
Admin
Tantivy is a search engine library, inspired by Lucene, that provides full-text search capabilities...
Tokens:1,545,335
Snippets:9,236
Trust Score:9.7
Update:1 day ago
Show doc for...
Tokens:
Raw
### RegexQuery Usage Example

Source: https://docs.rs/tantivy/latest/tantivy/query/struct.RegexQuery.html

Complete example demonstrating how to create an index, add documents, and use a RegexQuery to search for matching documents.

```APIDOC
## RegexQuery Usage Example

### Description
Complete example demonstrating how to create an index, add documents, and use a RegexQuery to search for matching documents.

### Example
```rust
use tantivy::collector::Count;
use tantivy::query::RegexQuery;
use tantivy::schema::{Schema, TEXT};
use tantivy::{doc, Index, IndexWriter, Term};

let mut schema_builder = Schema::builder();
let title = schema_builder.add_text_field("title", TEXT);
let schema = schema_builder.build();
let index = Index::create_in_ram(schema);
{
    let mut index_writer: IndexWriter = index.writer(15_000_000)?;
    index_writer.add_document(doc!(
        title => "The Name of the Wind",
    ))?;
    index_writer.add_document(doc!(
        title => "The Diary of Muadib",
    ))?;
    index_writer.add_document(doc!(
        title => "A Dairy Cow",
    ))?;
    index_writer.add_document(doc!(
        title => "The Diary of a Young Girl",
    ))?;
    index_writer.commit()?;
}

let reader = index.reader()?;
let searcher = reader.searcher();

let term = Term::from_field_text(title, "Diary");
let query = RegexQuery::from_pattern("d[ai]{2}ry", title)?;
let count = searcher.search(&query, &Count)?;
assert_eq!(count, 3);
Ok(())
```
```

--------------------------------

### doc! Example with Schema

Source: https://docs.rs/tantivy/latest/tantivy/macro.doc.html

Full example demonstrating doc! with a schema. Creates a schema with text and u64 fields, then builds a document. Note: the document is not validated against the schema.

```rust
use tantivy::schema::{Schema, TEXT, FAST};
use tantivy::doc;

//...

let mut schema_builder = Schema::builder();
let title = schema_builder.add_text_field("title", TEXT);
let author = schema_builder.add_text_field("text", TEXT);
let likes = schema_builder.add_u64_field("num_u64", FAST);
let schema = schema_builder.build();
let doc = doc!(
    title => "Life Aquatic",
    author => "Wes Anderson",
    likes => 4u64
);
```

--------------------------------

### TermQuery usage example

Source: https://docs.rs/tantivy/latest/tantivy/query/struct.TermQuery.html

Example showing how to create an index, add documents, and search using TermQuery with TopDocs and Count collectors.

```rust
use tantivy::collector::{Count, TopDocs};
use tantivy::query::TermQuery;
use tantivy::schema::{Schema, TEXT, IndexRecordOption};
use tantivy::{doc, Index, IndexWriter, Term};
let mut schema_builder = Schema::builder();
let title = schema_builder.add_text_field("title", TEXT);
let schema = schema_builder.build();
let index = Index::create_in_ram(schema);
{
    let mut index_writer: IndexWriter = index.writer(15_000_000)?;
    index_writer.add_document(doc!(
        title => "The Name of the Wind",
    ))?;
    index_writer.add_document(doc!(
        title => "The Diary of Muadib",
    ))?;
    index_writer.add_document(doc!(
        title => "A Dairy Cow",
    ))?;
    index_writer.add_document(doc!(
        title => "The Diary of a Young Girl",
    ))?;
    index_writer.commit()?;
}
let reader = index.reader()?;
let searcher = reader.searcher();
let query = TermQuery::new(
    Term::from_field_text(title, "diary"),
    IndexRecordOption::Basic,
);
let (top_docs, count) = searcher.search(&query, &(TopDocs::with_limit(2).order_by_score(), Count))?;
assert_eq!(count, 2);
Ok(())
```

--------------------------------

### iter method example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to iterate over a slice using the iter method. The iterator yields all items from start to end.

```rust
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```

--------------------------------

### starts_with: prefix check examples

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to use starts_with to check if a slice starts with a given prefix. Returns true if needle is a prefix or equal to the slice. Includes assertions for matching and non-matching cases.

```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));
```

--------------------------------

### as_ptr example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to get a raw pointer to the slice's buffer and use it to access elements. The caller must ensure the slice outlives the pointer.

```rust
let x = &[1, 2, 4];
let x_ptr = x.as_ptr();

unsafe {
    for i in 0..x.len() {
        assert_eq!(x.get_unchecked(i), &*x_ptr.add(i));
    }
}
```

--------------------------------

### as_chunks example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to use the safe as_chunks method to split a slice into chunks and a remainder. The first example demonstrates the basic usage with a slice of length 5 and N=2. The second example shows combining let-else with an empty slice pattern to assert an exact multiple.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let (chunks, remainder) = slice.as_chunks();
assert_eq!(chunks, &[['l', 'o'], ['r', 'e']]);
assert_eq!(remainder, &['m']);
```

```rust
let slice = ['R', 'u', 's', 't'];
let (chunks, []) = slice.as_chunks::<2>() else {
    panic!("slice didn't have even length")
};
assert_eq!(chunks, &[['R', 'u'], ['s', 't']]);
```

--------------------------------

### Basic binary_search example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to use binary_search on a sorted slice to find an element or get an insertion index. The first element is found at index 9, missing values return Err with the insertion point, and duplicate matches return any index in the range.

```rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

assert_eq!(s.binary_search(&13),  Ok(9));
assert_eq!(s.binary_search(&4),   Err(7));
assert_eq!(s.binary_search(&100), Err(13));
let r = s.binary_search(&1);
assert!(match r { Ok(1..=4) => true, _ => false, });
```

--------------------------------

### join method examples

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Examples for the join method, which flattens a slice of T into a single value with a separator. The examples show joining string slices and arrays with different separator types.

```rust
assert_eq!(["hello", "world"].join(" "), "hello world");
assert_eq!([[1, 2], [3, 4]].join(&0), [1, 2, 0, 3, 4]);
assert_eq!([[1, 2], [3, 4]].join(&[0, 0][..]), [1, 2, 0, 0, 3, 4]);
```

--------------------------------

### connect method examples

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Examples for the connect method, which is deprecated since 1.3.0 and renamed to join. It flattens a slice of T into a single value with a separator.

```rust
assert_eq!(["hello", "world"].connect(" "), "hello world");
assert_eq!([[1, 2], [3, 4]].connect(&0), [1, 2, 0, 3, 4]);
```

--------------------------------

### split_first example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Returns the first and all the rest of the elements of the slice, or None if empty. The example destructures the result and asserts the values.

```rust
let x = &[0, 1, 2];

if let Some((first, elements)) = x.split_first() {
    assert_eq!(first, &0);
    assert_eq!(elements, &[1, 2]);
}
```

--------------------------------

### array_windows example: iterating over overlapping windows

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to use array_windows to iterate over overlapping windows of N elements. The example uses N=2 and asserts the sequence of windows.

```rust
let slice = [0, 1, 2, 3];
let mut iter = slice.array_windows();
assert_eq!(iter.next().unwrap(), &[0, 1]);
assert_eq!(iter.next().unwrap(), &[1, 2]);
assert_eq!(iter.next().unwrap(), &[2, 3]);
assert!(iter.next().is_none());
```

--------------------------------

### trim_prefix example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to use trim_prefix to remove a prefix from a slice. If the prefix is present, it is removed; otherwise, the original slice is returned. Includes a string example.

```rust
let v = &[10, 40, 30];

// Prefix present - removes it
assert_eq!(v.trim_prefix(&[10]), &[40, 30][..]);
assert_eq!(v.trim_prefix(&[10, 40]), &[30][..]);
assert_eq!(v.trim_prefix(&[10, 40, 30]), &[][..]);

// Prefix absent - returns original slice
assert_eq!(v.trim_prefix(&[50]), &[10, 40, 30][..]);
assert_eq!(v.trim_prefix(&[10, 50]), &[10, 40, 30][..]);

let prefix : &str = "he";
assert_eq!(b"hello".trim_prefix(prefix.as_bytes()), b"llo".as_ref());
```

--------------------------------

### RangeQuery usage example

Source: https://docs.rs/tantivy/latest/tantivy/query/struct.RangeQuery.html

Example showing how to create a RangeQuery for a u64 field and search for documents within a range. It builds an index, adds documents, and asserts the count of matches.

```rust
use tantivy::collector::Count;
use tantivy::query::RangeQuery;
use tantivy::Term;
use tantivy::schema::{Schema, INDEXED};
use tantivy::{doc, Index, IndexWriter};
use std::ops::Bound;
let mut schema_builder = Schema::builder();
let year_field = schema_builder.add_u64_field("year", INDEXED);
let schema = schema_builder.build();

let index = Index::create_in_ram(schema);
let mut index_writer: IndexWriter = index.writer_with_num_threads(1, 20_000_000)?;
for year in 1950u64..2017u64 {
    let num_docs_within_year = 10 + (year - 1950) * (year - 1950);
    for _ in 0..num_docs_within_year {
      index_writer.add_document(doc!(year_field => year))?;
    }
}
index_writer.commit()?;

let reader = index.reader()?;
let searcher = reader.searcher();
let docs_in_the_sixties = RangeQuery::new(
    Bound::Included(Term::from_field_u64(year_field, 1960)),
    Bound::Excluded(Term::from_field_u64(year_field, 1970)),
);
let num_60s_books = searcher.search(&docs_in_the_sixties, &Count)?;
assert_eq!(num_60s_books, 2285);
Ok(())
```

--------------------------------

### get example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Returns a reference to an element or subslice depending on the index type. For a position, returns the element or None if out of bounds; for a range, returns the subslice or None if out of bounds. Example shows getting element at index 1, subslice 0..2, and None for out-of-bounds indices.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

--------------------------------

### Create an index with IndexBuilder

Source: https://docs.rs/tantivy/latest/tantivy/index/struct.IndexBuilder.html

Example showing how to build a schema, set index settings, and create an in-RAM index using IndexBuilder.

```rust
use tantivy::schema::*;
use tantivy::{Index, IndexSettings};

let mut schema_builder = Schema::builder();
let id_field = schema_builder.add_text_field("id", STRING);
let title_field = schema_builder.add_text_field("title", TEXT);
let body_field = schema_builder.add_text_field("body", TEXT);
let number_field = schema_builder.add_u64_field(
    "number",
    NumericOptions::default().set_fast(),
);

let schema = schema_builder.build();
let settings = IndexSettings{
    docstore_blocksize: 100_000,
    ..Default::default()
};
let index = Index::builder().schema(schema).settings(settings).create_in_ram();
```

--------------------------------

### Collect facet counts with FacetCollector

Source: https://docs.rs/tantivy/latest/tantivy/collector/struct.FacetCollector.html

This example creates an in-memory index with a facet field and text field, indexes four documents with facets, and then uses FacetCollector to collect facet counts for various facet paths. It demonstrates the get method to retrieve all facet counts for a path and the top_k method to get the top K counts. The example includes assertions showing the expected counts.

```rust
use tantivy::collector::FacetCollector;
use tantivy::query::AllQuery;
use tantivy::schema::{Facet, Schema, FacetOptions, TEXT};
use tantivy::{doc, Index};

fn example() -> tantivy::Result<()> {
    let mut schema_builder = Schema::builder();

    // Facet have their own specific type.
    // It is not a bad practise to put all of your
    // facet information in the same field.
    let facet = schema_builder.add_facet_field("facet", FacetOptions::default());
    let title = schema_builder.add_text_field("title", TEXT);
    let schema = schema_builder.build();
    let index = Index::create_in_ram(schema);
    {
        let mut index_writer = index.writer(15_000_000)?;
        // a document can be associated with any number of facets
        index_writer.add_document(doc!(
            title => "The Name of the Wind",
            facet => Facet::from("/lang/en"),
            facet => Facet::from("/category/fiction/fantasy")
        ))?;
        index_writer.add_document(doc!(
            title => "Dune",
            facet => Facet::from("/lang/en"),
            facet => Facet::from("/category/fiction/sci-fi")
        ))?;
        index_writer.add_document(doc!(
            title => "La Vénus d'Ille",
            facet => Facet::from("/lang/fr"),
            facet => Facet::from("/category/fiction/fantasy"),
            facet => Facet::from("/category/fiction/horror")
        ))?;
        index_writer.add_document(doc!(
            title => "The Diary of a Young Girl",
            facet => Facet::from("/lang/en"),
            facet => Facet::from("/category/biography")
        ))?;
        index_writer.commit()?;
    }
    let reader = index.reader()?;
    let searcher = reader.searcher();

    {
        let mut facet_collector = FacetCollector::for_field("facet");
        facet_collector.add_facet("/lang");
        facet_collector.add_facet("/category");
        let facet_counts = searcher.search(&AllQuery, &facet_collector)?;

        // This lists all of the facet counts
        let facets: Vec<(&Facet, u64)> = facet_counts
            .get("/category")
            .collect();
        assert_eq!(facets, vec![
            (&Facet::from("/category/biography"), 1),
            (&Facet::from("/category/fiction"), 3)
        ]);
    }

    {
        let mut facet_collector = FacetCollector::for_field("facet");
        facet_collector.add_facet("/category/fiction");
        let facet_counts = searcher.search(&AllQuery, &facet_collector)?;

        // This lists all of the facet counts
        let facets: Vec<(&Facet, u64)> = facet_counts
            .get("/category/fiction")
            .collect();
        assert_eq!(facets, vec![
            (&Facet::from("/category/fiction/fantasy"), 2),
            (&Facet::from("/category/fiction/horror"), 1),
            (&Facet::from("/category/fiction/sci-fi"), 1)
        ]);
    }

    {
        let mut facet_collector = FacetCollector::for_field("facet");
        facet_collector.add_facet("/category/fiction");
        let facet_counts = searcher.search(&AllQuery, &facet_collector)?;

        // This lists all of the facet counts
        let facets: Vec<(&Facet, u64)> = facet_counts.top_k("/category/fiction", 1);
        assert_eq!(facets, vec![
            (&Facet::from("/category/fiction/fantasy"), 2)
        ]);
    }

    {
        let mut facet_collector = FacetCollector::for_field("facet");
        facet_collector.add_facet("/");
        let facet_counts = searcher.search(&AllQuery, &facet_collector)?;

        // This lists all of the facet counts
        let facets: Vec<(&Facet, u64)> = facet_counts
            .get("/")
            .collect();
        assert_eq!(facets, vec![
            (&Facet::from("/category"), 4),
            (&Facet::from("/lang"), 4)
        ]);
    }

    Ok(())
}
```

--------------------------------

### Basic indexing and search example

Source: https://docs.rs/tantivy/latest/tantivy/

This example shows the core workflow of Tantivy: defining a schema with text fields, indexing a document, committing, and searching with a query parser. It uses a 100MB buffer for the index writer and retrieves the top 10 documents by score.

```rust
// First we need to define a schema ...

// `TEXT` means the field should be tokenized and indexed,
// along with its term frequency and term positions.
//
// `STORED` means that the field will also be saved
// in a compressed, row-oriented key-value store.
// This store is useful to reconstruct the
// documents that were selected during the search phase.
let mut schema_builder = Schema::builder();
let title = schema_builder.add_text_field("title", TEXT | STORED);
let body = schema_builder.add_text_field("body", TEXT);
let schema = schema_builder.build();

// Indexing documents

let index = Index::create_in_dir(index_path, schema.clone())?;

// Here we use a buffer of 100MB that will be split
// between indexing threads.
let mut index_writer: IndexWriter = index.writer(100_000_000)?;

// Let's index a document!
index_writer.add_document(doc!(
    title => "The Old Man and the Sea",
    body => "He was an old man who fished alone in a skiff in \
            the Gulf Stream and he had gone eighty-four days \
            now without taking a fish."
))?;

// We need to call .commit() explicitly to force the
// index_writer to finish processing the documents in the queue,
// flush the current index to the disk, and advertise
// the existence of new documents.
index_writer.commit()?;

// # Searching

let reader = index.reader()?;

let searcher = reader.searcher();

let query_parser = QueryParser::for_index(&index, vec![title, body]);

// QueryParser may fail if the query is not in the right
// format. For user facing applications, this can be a problem.
// A ticket has been opened regarding this problem.
let query = query_parser.parse_query("sea whale")?;

// Perform search.
// `topdocs` contains the 10 most relevant doc ids, sorted by decreasing scores...
let top_docs: Vec<(Score, DocAddress)> =
    searcher.search(&query, &TopDocs::with_limit(10).order_by_score())?;

for (_score, doc_address) in top_docs {
    // Retrieve the actual content of documents given its `doc_address`.
    let retrieved_doc = searcher.doc::<TantivyDocument>(doc_address)?;
    println!("{}", retrieved_doc.to_json(&schema));
}

```

--------------------------------

### as_rchunks example: splitting a slice into chunks from the end

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to use as_rchunks to split a slice into N-element chunks starting from the end, with a remainder slice of length less than N. The example uses N=2 and asserts the remainder and chunks.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let (remainder, chunks) = slice.as_rchunks();
assert_eq!(remainder, &['l']);
assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]);
```

--------------------------------

### TopDocs usage example

Source: https://docs.rs/tantivy/latest/tantivy/collector/struct.TopDocs.html

Example showing how to create an index, add documents, parse a query, and use TopDocs::with_limit(2).order_by_score() to retrieve the top documents. Asserts that the returned DocAddresses are sorted by score and tie-broken by ascending DocAddress.

```rust
use tantivy::collector::TopDocs;
use tantivy::query::QueryParser;
use tantivy::schema::{Schema, TEXT};
use tantivy::{doc, DocAddress, Index};

let mut schema_builder = Schema::builder();
let title = schema_builder.add_text_field("title", TEXT);
let schema = schema_builder.build();
let index = Index::create_in_ram(schema);

let mut index_writer = index.writer_with_num_threads(1, 20_000_000)?;
index_writer.add_document(doc!(title => "The Name of the Wind"))?;
index_writer.add_document(doc!(title => "The Diary of Muadib"))?;
index_writer.add_document(doc!(title => "A Dairy Cow"))?;
index_writer.add_document(doc!(title => "The Diary of a Young Girl"))?;
index_writer.commit()?;

let reader = index.reader()?;
let searcher = reader.searcher();

let query_parser = QueryParser::for_index(&index, vec![title]);
let query = query_parser.parse_query("diary")?;
let top_docs = searcher.search(&query, &TopDocs::with_limit(2).order_by_score())?;

assert_eq!(top_docs[0].1, DocAddress::new(0, 1));
assert_eq!(top_docs[1].1, DocAddress::new(0, 3));
```

--------------------------------

### windows method example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to create overlapping windows of a slice using the windows method. Panics if size is zero.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.windows(3);
assert_eq!(iter.next().unwrap(), &['l', 'o', 'r']);
assert_eq!(iter.next().unwrap(), &['o', 'r', 'e']);
assert_eq!(iter.next().unwrap(), &['r', 'e', 'm']);
assert!(iter.next().is_none());
```

--------------------------------

### as_ptr_range example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to get a range of raw pointers spanning the slice and check if a pointer is within that range. The range is half-open.

```rust
let a = [1, 2, 3];
let x = &a[1] as *const _;
let y = &5 as *const _;

assert!(a.as_ptr_range().contains(&x));
assert!(!a.as_ptr_range().contains(&y));
```

--------------------------------

### take

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Creates an adapter which will read at most `limit` bytes from the OwnedBytes instance.

```APIDOC
## take

### Description
Creates an adapter which will read at most `limit` bytes from the OwnedBytes instance.

### Method
take

### Signature
`fn take(self, limit: u64) -> Take<Self>`

### Parameters
- **limit** (u64) - Required - The maximum number of bytes to read.

### Returns
- **Take<Self>** - An adapter that limits the number of bytes read.

### Notes
- This method is from the `Read` trait.
```

--------------------------------

### Example: using SplitCompoundWords with SimpleTokenizer

Source: https://docs.rs/tantivy/latest/tantivy/tokenizer/struct.SplitCompoundWords.html

Demonstrates how to build a TextAnalyzer with SplitCompoundWords and a dictionary, then tokenize two example words. The first word is split into its parts, while the second is not split because the dictionary lacks the stem 'back'.

```rust
use tantivy::tokenizer::{SimpleTokenizer, SplitCompoundWords, TextAnalyzer};

let mut tokenizer =
       TextAnalyzer::builder(SimpleTokenizer::default())
       .filter(
           SplitCompoundWords::from_dictionary([
                "dampf", "schiff", "fahrt", "brot", "backen", "automat",
           ])
           .unwrap()
       )
       .build();
{
    let mut stream = tokenizer.token_stream("dampfschifffahrt");
    assert_eq!(stream.next().unwrap().text, "dampf");
    assert_eq!(stream.next().unwrap().text, "schiff");
    assert_eq!(stream.next().unwrap().text, "fahrt");
    assert_eq!(stream.next(), None);
}
let mut stream = tokenizer.token_stream("brotbackautomat");
assert_eq!(stream.next().unwrap().text, "brotbackautomat");
assert_eq!(stream.next(), None);
```

--------------------------------

### rsplitn: split at most n times from the end

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to use rsplitn to split a slice into at most n subslices, starting from the end. The example prints groups split once by numbers divisible by 3, working backwards.

```rust
let v = [10, 40, 30, 20, 60, 50];

for group in v.rsplitn(2, |num| *num % 3 == 0) {
    println!("{group:?}");
}
```

--------------------------------

### strip_circumfix example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Shows how to use strip_circumfix to remove both a prefix and a suffix from a slice. Returns Some with the subslice between them if the slice starts with the prefix, ends with the suffix, and they don't overlap; otherwise returns None. Handles empty prefix or suffix.

```rust
let v = &[10, 50, 40, 30];
assert_eq!(v.strip_circumfix(&[10], &[30]), Some(&[50, 40][..]));
assert_eq!(v.strip_circumfix(&[10], &[40, 30]), Some(&[50][..]));
assert_eq!(v.strip_circumfix(&[10, 50], &[40, 30]), Some(&[][..]));
assert_eq!(v.strip_circumfix(&[50], &[30]), None);
assert_eq!(v.strip_circumfix(&[10], &[40]), None);
assert_eq!(v.strip_circumfix(&[], &[40, 30]), Some(&[10, 50][..]));
assert_eq!(v.strip_circumfix(&[10, 50], &[]), Some(&[40, 30][..]));
assert_eq!(v.strip_circumfix(&[10, 50, 40], &[50, 40, 30]), None);
```

--------------------------------

### DisjunctionMaxQuery usage example

Source: https://docs.rs/tantivy/latest/tantivy/query/struct.DisjunctionMaxQuery.html

Complete example showing how to create an index, add documents, and search using DisjunctionMaxQuery with and without a tie breaker. Demonstrates that scores are equal when terms match and that tie breaker multiplies additional term scores.

```rust
use tantivy::collector::TopDocs;
use tantivy::doc;
use tantivy::query::{DisjunctionMaxQuery, Query, QueryClone, TermQuery};
use tantivy::schema::{IndexRecordOption, Schema, TEXT};
use tantivy::Term;
use tantivy::Index;
use tantivy::IndexWriter;

fn main() -> tantivy::Result<()> {
   let mut schema_builder = Schema::builder();
   let title = schema_builder.add_text_field("title", TEXT);
   let body = schema_builder.add_text_field("body", TEXT);
   let schema = schema_builder.build();
   let index = Index::create_in_ram(schema);
   {
       let mut index_writer: IndexWriter = index.writer(15_000_000)?;
       index_writer.add_document(doc!(
           title => "The Name of Girl",
       ))?;
       index_writer.add_document(doc!(
           title => "The Diary of Muadib",
       ))?;
       index_writer.add_document(doc!(
           title => "The Diary of Girl",
       ))?;
       index_writer.commit()?;
   }

   let reader = index.reader()?;
   let searcher = reader.searcher();

   // Make TermQuery's for "girl" and "diary" in the title
   let girl_term_query: Box<dyn Query> = Box::new(TermQuery::new(
       Term::from_field_text(title, "girl"),
       IndexRecordOption::Basic,
   ));
   let diary_term_query: Box<dyn Query> = Box::new(TermQuery::new(
       Term::from_field_text(title, "diary"),
       IndexRecordOption::Basic,
   ));

   // TermQuery "diary" and "girl" should be present and only one should be accounted in score
   let queries1 = vec![diary_term_query.box_clone(), girl_term_query.box_clone()];
   let diary_and_girl = DisjunctionMaxQuery::new(queries1);
   let documents = searcher.search(&diary_and_girl, &TopDocs::with_limit(3).order_by_score())?;
   assert_eq!(documents[0].0, documents[1].0);
   assert_eq!(documents[1].0, documents[2].0);

   // TermQuery "diary" and "girl" should be present
   // and one should be accounted with multiplier 0.7
   let queries2 = vec![diary_term_query.box_clone(), girl_term_query.box_clone()];
   let tie_breaker = 0.7;
   let diary_and_girl_with_tie_breaker = DisjunctionMaxQuery::with_tie_breaker(queries2, tie_breaker);
   let documents = searcher.search(&diary_and_girl_with_tie_breaker, &TopDocs::with_limit(3).order_by_score())?;
   assert_eq!(documents[1].0, documents[2].0);
   // For this test all terms brings the same score. So we can do easy math and assume that
   // `DisjunctionMaxQuery` with tie breakers score should be equal
   // to term1 score + `tie_breaker` * term2 score or (1.0 + tie_breaker) * term score
   assert!(f32::abs(documents[0].0 - documents[1].0 * (1.0 + tie_breaker)) < 0.001);
   Ok(())
}
```

--------------------------------

### TopDocs::for_doc_range

Source: https://docs.rs/tantivy/latest/tantivy/collector/struct.TopDocs.html

Builds a TopDocs collector that captures a given document range. The range start..end translates to a limit of end - start and an offset of start.

```APIDOC
## TopDocs::for_doc_range

### Description
Builds a `TopDocs` capturing a given document range. The range start..end translates in a limit of `end - start` and an offset of start.

### Method
`pub fn for_doc_range(doc_range: Range<usize>) -> Self`

### Parameters
- **doc_range** (Range<usize>) - Required - The range of documents to capture.

### Returns
- **Self** - A new `TopDocs` instance configured with the given range.

```

--------------------------------

### Using TopDocs::with_limit and and_offset

Source: https://docs.rs/tantivy/latest/tantivy/collector/struct.TopDocs.html

Example from the and_offset method documentation showing how to search with a limit and offset, returning the top 2 documents after skipping the first. It demonstrates indexing documents, parsing a query, and asserting the results.

```rust
use tantivy::collector::TopDocs;
use tantivy::query::QueryParser;
use tantivy::schema::{Schema, TEXT};
use tantivy::{doc, DocAddress, Index};

let mut schema_builder = Schema::builder();
let title = schema_builder.add_text_field("title", TEXT);
let schema = schema_builder.build();
let index = Index::create_in_ram(schema);

let mut index_writer = index.writer_with_num_threads(1, 20_000_000)?;
index_writer.add_document(doc!(title => "The Name of the Wind"))?;
index_writer.add_document(doc!(title => "The Diary of Muadib"))?;
index_writer.add_document(doc!(title => "A Dairy Cow"))?;
index_writer.add_document(doc!(title => "The Diary of a Young Girl"))?;
index_writer.add_document(doc!(title => "The Diary of Lena Mukhina"))?;
index_writer.commit()?;

let reader = index.reader()?;
let searcher = reader.searcher();

let query_parser = QueryParser::for_index(&index, vec![title]);
let query = query_parser.parse_query("diary")?;
let top_docs = searcher.search(&query, &TopDocs::with_limit(2).and_offset(1).order_by_score())?;

assert_eq!(top_docs.len(), 2);
assert_eq!(top_docs[0].1, DocAddress::new(0, 4));
assert_eq!(top_docs[1].1, DocAddress::new(0, 3));
Ok(())

```

--------------------------------

### trim_ascii_start examples

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Demonstrates trim_ascii_start() removing leading ASCII whitespace from byte slices. Includes three assertions covering typical, all-whitespace, and empty inputs.

```rust
assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
assert_eq!(b"  ".trim_ascii_start(), b"");
assert_eq!(b"".trim_ascii_start(), b"");
```

--------------------------------

### Example: Building and Registering a Custom Tokenizer

Source: https://docs.rs/tantivy/latest/tantivy/tokenizer/index.html

Demonstrates how to create a custom tokenizer using TextAnalyzer::builder with SimpleTokenizer and filters (RemoveLongFilter, LowerCaser), then register it with an index's tokenizer registry.

```APIDOC
## Example: Building and Registering a Custom Tokenizer

### Description
This example shows how to build a custom tokenizer pipeline using `TextAnalyzer::builder` with `SimpleTokenizer` and filters (`RemoveLongFilter`, `LowerCaser`), and register it with an index's tokenizer registry.

### Code
```rust
use tantivy::schema::{Schema, IndexRecordOption, TextOptions, TextFieldIndexing};
use tantivy::tokenizer::*;
use tantivy::Index;

let mut schema_builder = Schema::builder();
let text_field_indexing = TextFieldIndexing::default()
    .set_tokenizer("custom_en")
    .set_index_option(IndexRecordOption::WithFreqsAndPositions);
let text_options = TextOptions::default()
    .set_indexing_options(text_field_indexing)
    .set_stored();
schema_builder.add_text_field("title", text_options);
let schema = schema_builder.build();
let index = Index::create_in_ram(schema);

// We need to register our tokenizer :
let custom_en_tokenizer = TextAnalyzer::builder(SimpleTokenizer::default())
    .filter(RemoveLongFilter::limit(40))
    .filter(LowerCaser)
    .build();
index
    .tokenizers()
    .register("custom_en", custom_en_tokenizer);
```
```

--------------------------------

### repeat panic example: overflow at runtime

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

This example will panic at runtime because the capacity overflows.

```rust
// this will panic at runtime
b"0123456789abcdef".repeat(usize::MAX);
```

--------------------------------

### doc! Basic Usage

Source: https://docs.rs/tantivy/latest/tantivy/macro.doc.html

Shows how to create a Document with doc! using field-value pairs. The value can be a u64, &str, i64, or String.

```c
doc!(
    field1 => value1,
    field2 => value2,
)
```

--------------------------------

### Example JSON document for ExistsQuery

Source: https://docs.rs/tantivy/latest/tantivy/query/struct.ExistsQuery.html

Example JSON document used to illustrate the behavior of ExistsQuery with JSON subpaths.

```json
{
  "myfield": {
    "mysubfield": "hello"
  }
}
```

--------------------------------

### strip_prefix

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Returns a subslice with the prefix removed if the slice starts with the given prefix. Returns None if the slice does not start with the prefix.

```APIDOC
## strip_prefix

### Description
Returns a subslice with the prefix removed. If the slice starts with `prefix`, returns the subslice after the prefix, wrapped in `Some`. If `prefix` is empty, simply returns the original slice. If `prefix` is equal to the original slice, returns an empty slice. If the slice does not start with `prefix`, returns `None`.

### Method
strip_prefix

### Signature
`pub fn strip_prefix<P>(&self, prefix: &P) -> Option<&[T]>`

### Parameters
- **prefix** (reference to P) - Required - The prefix to strip.

### Return Value
- **Option<&[T]>** - `Some` with the subslice after the prefix if the slice starts with the prefix, otherwise `None`.

### Examples
```rust
let v = &[10, 40, 30];
assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
assert_eq!(v.strip_prefix(&[50]), None);
assert_eq!(v.strip_prefix(&[10, 50]), None);

let prefix : &str = "he";
assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
           Some(b"llo".as_ref()));
```
```

--------------------------------

### Using MultiCollector with TopDocs and Count

Source: https://docs.rs/tantivy/latest/tantivy/collector/struct.MultiCollector.html

Example showing how to create a MultiCollector, add TopDocs and Count collectors, search, and extract results. The example asserts that the count is 2 and top docs length is 2.

```rust
use tantivy::collector::{Count, TopDocs, MultiCollector};
use tantivy::query::QueryParser;
use tantivy::schema::{Schema, TEXT};
use tantivy::{doc, Index};

let mut schema_builder = Schema::builder();
let title = schema_builder.add_text_field("title", TEXT);
let schema = schema_builder.build();
let index = Index::create_in_ram(schema);
let mut index_writer = index.writer(15_000_000)?;
index_writer.add_document(doc!(title => "The Name of the Wind"))?;
index_writer.add_document(doc!(title => "The Diary of Muadib"))?;
index_writer.add_document(doc!(title => "A Dairy Cow"))?;
index_writer.add_document(doc!(title => "The Diary of a Young Girl"))?;
index_writer.commit()?;

let reader = index.reader()?;
let searcher = reader.searcher();

let mut collectors = MultiCollector::new();
let top_docs_handle = collectors.add_collector(TopDocs::with_limit(2).order_by_score());
let count_handle = collectors.add_collector(Count);
let query_parser = QueryParser::for_index(&index, vec![title]);
let query = query_parser.parse_query("diary").unwrap();
let mut multi_fruit = searcher.search(&query, &collectors).unwrap();

let count = count_handle.extract(&mut multi_fruit);
let top_docs = top_docs_handle.extract(&mut multi_fruit);

assert_eq!(count, 2);
assert_eq!(top_docs.len(), 2);
```

--------------------------------

### FuzzyTermQuery Usage Example

Source: https://docs.rs/tantivy/latest/tantivy/query/struct.FuzzyTermQuery.html

Example demonstrating how to create a FuzzyTermQuery and use it to search an index, retrieving top documents and count.

```APIDOC
## FuzzyTermQuery

### Description
A Fuzzy Query matches all of the documents containing a specific term that is within Levenshtein distance.

### Usage Example
```rust
use tantivy::collector::{Count, TopDocs};
use tantivy::query::FuzzyTermQuery;
use tantivy::schema::{Schema, TEXT};
use tantivy::{doc, Index, IndexWriter, Term};

fn example() -> tantivy::Result<()> {
    let mut schema_builder = Schema::builder();
    let title = schema_builder.add_text_field("title", TEXT);
    let schema = schema_builder.build();
    let index = Index::create_in_ram(schema);
    {
        let mut index_writer: IndexWriter = index.writer(15_000_000)?;
        index_writer.add_document(doc!(
            title => "The Name of the Wind",
        ))?;
        index_writer.add_document(doc!(
            title => "The Diary of Muadib",
        ))?;
        index_writer.add_document(doc!(
            title => "A Dairy Cow",
        ))?;
        index_writer.add_document(doc!(
            title => "The Diary of a Young Girl",
        ))?;
        index_writer.commit()?;
    }
    let reader = index.reader()?;
    let searcher = reader.searcher();

    {
        let term = Term::from_field_text(title, "Diary");
        let query = FuzzyTermQuery::new(term, 1, true);
        let (top_docs, count) = searcher.search(&query, &(TopDocs::with_limit(2).order_by_score(), Count)).unwrap();
        assert_eq!(count, 2);
        assert_eq!(top_docs.len(), 2);
    }

    Ok(())
}
```

### Constructor
- `FuzzyTermQuery::new(term: Term, distance: u8, transposition_cost_one: bool)` - Creates a new FuzzyTermQuery with the given term, maximum Levenshtein distance, and whether transposition costs one.
```

--------------------------------

### split_last example

Source: https://docs.rs/tantivy/latest/tantivy/directory/struct.OwnedBytes.html

Returns the last and all the rest of the elements of the slice, or None if empty. The example destructures the result and asserts the values.

```rust
let x = &[0, 1, 2];

if let Some((last, elements)) = x.split_last() {
    assert_eq!(last, &2);
    assert_eq!(elements, &[0, 1]);
}
```

--------------------------------

### Building a Schema with Text Fields

Source: https://docs.rs/tantivy/latest/tantivy/schema/struct.Schema.html

Example of creating a schema builder, adding text fields for id, title, and body, and building the schema.

```rust
use tantivy::schema::*;

let mut schema_builder = Schema::builder();
let id_field = schema_builder.add_text_field("id", STRING);
let title_field = schema_builder.add_text_field("title", TEXT);
let body_field = schema_builder.add_text_field("body", TEXT);
let schema = schema_builder.build();
```

--------------------------------

### starts_with

Source: https://docs.rs/tantivy/latest/tantivy/query/struct.DfaWrapper.html

Returns an automaton that matches the strings that start with something this automaton matches.

```APIDOC
## starts_with

### Description
Returns an automaton that matches the strings that start with something this automaton matches.

### Method
starts_with

### Signature
fn starts_with(self) -> StartsWith<Self>
where Self: Sized

### Returns
- **StartsWith<Self>** - An automaton that matches strings starting with a match of this automaton.

```
Tokens:
Raw