diff --git a/geoprox-core/CHANGELOG.md b/geoprox-core/CHANGELOG.md index 462b484..2d44659 100644 --- a/geoprox-core/CHANGELOG.md +++ b/geoprox-core/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added support for key expirations ([#15](https://github.com/ezrasingh/geoprox/issues/15)). - Implemented serde for `SpatialIndex` ([#17](https://github.com/ezrasingh/geoprox/issues/17)). +- renamed `cache.rs` to `index.rs` ## 0.4.2 diff --git a/geoprox-core/README.md b/geoprox-core/README.md index 25d8abd..86055a6 100644 --- a/geoprox-core/README.md +++ b/geoprox-core/README.md @@ -2,7 +2,7 @@ Geoprox Core is the foundational Rust crate for the [Geoprox](https://github.com/ezrasingh/geoprox/) project, providing robust geospatial indexing and sharding capabilities. It includes two primary modules: -- **`cache`**: Manages in-memory storage and retrieval of geospatial data to ensure quick access and efficient querying. +- **`index`**: Manages in-memory storage and retrieval of geospatial data to ensure quick access and efficient querying. - **`shard`**: Handles the partitioning and indexing of geospatial information, optimizing data distribution and retrieval across large datasets. These modules are built to handle various use cases, such as food delivery services and real-time inventory tracking. @@ -16,43 +16,6 @@ These modules are built to handle various use cases, such as food delivery servi ## Data Stuctures -### SpatialIndex - -The `cache` module implements the `SpatialIndex` data structure, enabling efficient placement and searching of resources based on their geohash-encoded locations. - -Key features include: - -- **Placing Resources**: Add resources to the index with their geohash-encoded locations. -- **Searching Resources**: Perform range queries to find resources within a specified distance from a given location. - -#### Example Usage - -```rust -extern crate geoprox_core; - -let mut geo_index = geoprox_core::SpatialIndex::default(); - -// ? place object keys into index -geo_index.insert("alice", "s00j8n0"); -geo_index.insert("bob", "s00j8n1"); - -// ? search index for objects near New York -let nearby: LatLngCoord = [40.7128, 74.006]; -let within: f64 = 200.0; // 200km radius -let count = 100; // return up to 100 results -let sorted = true; // sort results by distance -let search_depth = 6; // search precision (higher means more precise) -let res = geo_index.search(nearby, within, count, sorted, depth).unwrap(); - -println!("found: {:#?}", res); - -assert_eq!(res.len(), 2); - -res.iter().for_each(|neighbor| { - assert!(neighbor.distance <= within); -}); -``` - ### GeoShard The `shard` module implements the `GeoShard` data structure, which facilitates geographical sharding of datasets and enables efficient range queries. @@ -101,6 +64,43 @@ let res = shard.query_range("drivers", nearby, within, Some(count), Some(sorted) println!("found: {:#?}", res.unwrap()); ``` +### SpatialIndex + +The `index` module implements the `SpatialIndex` data structure, enabling efficient placement and searching of resources based on their geohash-encoded locations. + +Key features include: + +- **Placing Resources**: Add resources to the index with their geohash-encoded locations. +- **Searching Resources**: Perform range queries to find resources within a specified distance from a given location. + +#### Example Usage + +```rust +extern crate geoprox_core; + +let mut geo_index = geoprox_core::SpatialIndex::default(); + +// ? place object keys into index +geo_index.insert("alice", "s00j8n0"); +geo_index.insert("bob", "s00j8n1"); + +// ? search index for objects near New York +let nearby: LatLngCoord = [40.7128, 74.006]; +let within: f64 = 200.0; // 200km radius +let count = 100; // return up to 100 results +let sorted = true; // sort results by distance +let search_depth = 6; // search precision (higher means more precise) +let res = geo_index.search(nearby, within, count, sorted, depth).unwrap(); + +println!("found: {:#?}", res); + +assert_eq!(res.len(), 2); + +res.iter().for_each(|neighbor| { + assert!(neighbor.distance <= within); +}); +``` + ## Contributing Contributions are welcome! Please see the [contributing guidelines](https://github.com/ezrasingh/geoprox/blob/main/CONTRIBUTING.md) for more information. diff --git a/geoprox-core/benches/spatial_index_benchmark.rs b/geoprox-core/benches/spatial_index_benchmark.rs index e150228..a9e0414 100644 --- a/geoprox-core/benches/spatial_index_benchmark.rs +++ b/geoprox-core/benches/spatial_index_benchmark.rs @@ -1,7 +1,7 @@ use criterion::{ black_box, criterion_group, criterion_main, BatchSize, BenchmarkId, Criterion, Throughput, }; -use geoprox_core::{cache::SpatialIndex, models::LatLngCoord}; +use geoprox_core::{index::SpatialIndex, models::LatLngCoord}; use hashbrown::HashSet; use rand::prelude::*; diff --git a/geoprox-core/src/cache.rs b/geoprox-core/src/index.rs similarity index 100% rename from geoprox-core/src/cache.rs rename to geoprox-core/src/index.rs diff --git a/geoprox-core/src/lib.rs b/geoprox-core/src/lib.rs index e18ab65..505275f 100644 --- a/geoprox-core/src/lib.rs +++ b/geoprox-core/src/lib.rs @@ -1,6 +1,6 @@ mod metric; -pub mod cache; +pub mod index; pub mod models; pub mod serde; pub mod shard; diff --git a/geoprox-core/src/serde.rs b/geoprox-core/src/serde.rs index 01aa3bb..3297077 100644 --- a/geoprox-core/src/serde.rs +++ b/geoprox-core/src/serde.rs @@ -2,7 +2,7 @@ use std::time::{Duration, Instant, SystemTime}; use serde::{Deserialize, Serialize}; -use crate::cache::SpatialIndex; +use crate::index::SpatialIndex; impl Serialize for SpatialIndex { fn serialize(&self, serializer: S) -> Result diff --git a/geoprox-core/src/shard.rs b/geoprox-core/src/shard.rs index 05ebd8a..d4a610b 100644 --- a/geoprox-core/src/shard.rs +++ b/geoprox-core/src/shard.rs @@ -6,7 +6,7 @@ use itertools::Itertools; use rayon::prelude::*; use serde::{Deserialize, Serialize}; -use crate::cache::SpatialIndex; +use crate::index::SpatialIndex; use crate::models::{BatchOutput, GeoShardConfig, GeoShardError, LatLngCoord, Neighbor}; /// A collection of geospatial indexes stored in-memory