arms/ports/
place.rs

1//! # Place Port
2//!
3//! Trait for placing points in the space.
4//!
5//! This is one of the five primitives of ARMS:
6//! `Place: fn(point, data) -> id` - Exist in space
7//!
8//! Implemented by storage adapters (Memory, NVMe, etc.)
9
10use crate::core::{Blob, Id, PlacedPoint, Point};
11
12/// Result type for place operations
13pub type PlaceResult<T> = Result<T, PlaceError>;
14
15/// Errors that can occur during place operations
16#[derive(Debug, Clone, PartialEq)]
17pub enum PlaceError {
18    /// The point has wrong dimensionality for this space
19    DimensionalityMismatch { expected: usize, got: usize },
20
21    /// Storage capacity exceeded
22    CapacityExceeded,
23
24    /// Point with this ID already exists
25    DuplicateId(Id),
26
27    /// Storage backend error
28    StorageError(String),
29}
30
31impl std::fmt::Display for PlaceError {
32    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
33        match self {
34            PlaceError::DimensionalityMismatch { expected, got } => {
35                write!(f, "Dimensionality mismatch: expected {}, got {}", expected, got)
36            }
37            PlaceError::CapacityExceeded => write!(f, "Storage capacity exceeded"),
38            PlaceError::DuplicateId(id) => write!(f, "Duplicate ID: {}", id),
39            PlaceError::StorageError(msg) => write!(f, "Storage error: {}", msg),
40        }
41    }
42}
43
44impl std::error::Error for PlaceError {}
45
46/// Trait for placing points in the space
47///
48/// Storage adapters implement this trait.
49pub trait Place: Send + Sync {
50    /// Place a point with its payload in the space
51    ///
52    /// Returns the ID assigned to the placed point.
53    fn place(&mut self, point: Point, blob: Blob) -> PlaceResult<Id>;
54
55    /// Place a point with a specific ID
56    ///
57    /// Use when you need deterministic IDs (e.g., replication, testing).
58    fn place_with_id(&mut self, id: Id, point: Point, blob: Blob) -> PlaceResult<()>;
59
60    /// Remove a point from the space
61    ///
62    /// Returns the removed point if it existed.
63    fn remove(&mut self, id: Id) -> Option<PlacedPoint>;
64
65    /// Get a placed point by ID
66    ///
67    /// Returns None if not found.
68    fn get(&self, id: Id) -> Option<&PlacedPoint>;
69
70    /// Check if a point exists
71    fn contains(&self, id: Id) -> bool {
72        self.get(id).is_some()
73    }
74
75    /// Get the number of placed points
76    fn len(&self) -> usize;
77
78    /// Check if the space is empty
79    fn is_empty(&self) -> bool {
80        self.len() == 0
81    }
82
83    /// Iterate over all placed points
84    fn iter(&self) -> Box<dyn Iterator<Item = &PlacedPoint> + '_>;
85
86    /// Get current storage size in bytes
87    fn size_bytes(&self) -> usize;
88
89    /// Clear all points
90    fn clear(&mut self);
91}
arms/ports/place.rs

arms/ports/
place.rs
