Skip to content

Commit

Permalink
update API docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@uint
uint committed Nov 4, 2024
1 parent 2a5394b commit aebd8f1
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 46 deletions.
82 changes: 36 additions & 46 deletions packages/storey-storage/src/storage.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,35 +55,29 @@ pub trait IterableStorage {

/// Get an iterator over keys.
///
/// The iterator should iterate over keys in lexicographical order.
/// The iterator walks keys in lexicographical order.
///
/// If `start` is `None`, the iterator should start from the first key.
/// If `end` is `None`, the iterator should iterate until the last key.
/// If both `start` and `end` are `None`, the iterator should iterate over all keys.
///
/// The range is inclusive for `start` and exclusive for `end`.
/// The [`Bound`] type is used to specify either end of the range - whether it should be
/// bounded at all, and if so, whether it should be inclusive or exclusive. See the
/// [`Bound`] documentation for more details.
fn keys<'a>(&'a self, start: Bound<&[u8]>, end: Bound<&[u8]>) -> Self::KeysIterator<'a>;

/// Get an iterator over values.
///
/// The iterator should iterate over values corresponding to keys in lexicographical order.
///
/// If `start` is `None`, the iterator should start from the first key.
/// If `end` is `None`, the iterator should iterate until the last key.
/// If both `start` and `end` are `None`, the iterator should iterate over all keys.
/// The iterator walks values corresponding to keys in lexicographical order.
///
/// The range is inclusive for `start` and exclusive for `end`.
/// The [`Bound`] type is used to specify either end of the range - whether it should be
/// bounded at all, and if so, whether it should be inclusive or exclusive. See the
/// [`Bound`] documentation for more details.
fn values<'a>(&'a self, start: Bound<&[u8]>, end: Bound<&[u8]>) -> Self::ValuesIterator<'a>;

/// Get an iterator over key-value pairs.
///
/// The iterator should iterate over key-value pairs in lexicographical order.
///
/// If `start` is `None`, the iterator should start from the first key.
/// If `end` is `None`, the iterator should iterate until the last key.
/// If both `start` and `end` are `None`, the iterator should iterate over all keys.
/// The iterator walks key-value pairs in lexicographical order.
///
/// The range is inclusive for `start` and exclusive for `end`.
/// The [`Bound`] type is used to specify either end of the range - whether it should be
/// bounded at all, and if so, whether it should be inclusive or exclusive. See the
/// [`Bound`] documentation for more details.
fn pairs<'a>(&'a self, start: Bound<&[u8]>, end: Bound<&[u8]>) -> Self::PairsIterator<'a>;
}

Expand All @@ -92,41 +86,14 @@ impl<T: IterableStorage> IterableStorage for &T {
type ValuesIterator<'a> = T::ValuesIterator<'a> where Self: 'a;
type PairsIterator<'a> = T::PairsIterator<'a> where Self: 'a;

/// Get an iterator over keys.
///
/// The iterator should iterate over keys in lexicographical order.
///
/// If `start` is `None`, the iterator should start from the first key.
/// If `end` is `None`, the iterator should iterate until the last key.
/// If both `start` and `end` are `None`, the iterator should iterate over all keys.
///
/// The range is inclusive for `start` and exclusive for `end`.
fn keys<'a>(&'a self, start: Bound<&[u8]>, end: Bound<&[u8]>) -> Self::KeysIterator<'a> {
(**self).keys(start, end)
}

/// Get an iterator over values.
///
/// The iterator should iterate over values corresponding to keys in lexicographical order.
///
/// If `start` is `None`, the iterator should start from the first key.
/// If `end` is `None`, the iterator should iterate until the last key.
/// If both `start` and `end` are `None`, the iterator should iterate over all keys.
///
/// The range is inclusive for `start` and exclusive for `end`.
fn values<'a>(&'a self, start: Bound<&[u8]>, end: Bound<&[u8]>) -> Self::ValuesIterator<'a> {
(**self).values(start, end)
}

/// Get an iterator over key-value pairs.
///
/// The iterator should iterate over key-value pairs in lexicographical order.
///
/// If `start` is `None`, the iterator should start from the first key.
/// If `end` is `None`, the iterator should iterate until the last key.
/// If both `start` and `end` are `None`, the iterator should iterate over all keys.
///
/// The range is inclusive for `start` and exclusive for `end`.
fn pairs<'a>(&'a self, start: Bound<&[u8]>, end: Bound<&[u8]>) -> Self::PairsIterator<'a> {
(**self).pairs(start, end)
}
Expand All @@ -152,7 +119,7 @@ impl<T: IterableStorage> IterableStorage for &mut T {

/// Iteration interface for binary key-value storage in reverse order.
///
/// The iterator should iterate over key-value pairs in reverse lexicographical order of keys.
/// The iterator walks key-value pairs in reverse lexicographical order of keys.
pub trait RevIterableStorage {
/// The type of the iterator returned by [`rev_keys`](Self::rev_keys).
type RevKeysIterator<'a>: Iterator<Item = Vec<u8>>
Expand All @@ -169,12 +136,35 @@ pub trait RevIterableStorage {
where
Self: 'a;

/// Get a reverse iterator over keys.
///
/// The iterator walks keys in reverse lexicographical order.
///
/// The [`Bound`] type is used to specify either end of the range - whether it should be
/// bounded at all, and if so, whether it should be inclusive or exclusive. See the
/// [`Bound`] documentation for more details.
fn rev_keys<'a>(&'a self, start: Bound<&[u8]>, end: Bound<&[u8]>) -> Self::RevKeysIterator<'a>;

/// Get a reverse iterator over values.
///
/// The iterator walks values corresponding to keys in reverse lexicographical order.
///
/// The [`Bound`] type is used to specify either end of the range - whether it should be
/// bounded at all, and if so, whether it should be inclusive or exclusive. See the
/// [`Bound`] documentation for more details.
fn rev_values<'a>(
&'a self,
start: Bound<&[u8]>,
end: Bound<&[u8]>,
) -> Self::RevValuesIterator<'a>;

/// Get a reverse iterator over key-value pairs.
///
/// The iterator walks key-value pairs in reverse lexicographical order.
///
/// The [`Bound`] type is used to specify either end of the range - whether it should be
/// bounded at all, and if so, whether it should be inclusive or exclusive. See the
/// [`Bound`] documentation for more details.
fn rev_pairs<'a>(
&'a self,
start: Bound<&[u8]>,
Expand Down
12 changes: 12 additions & 0 deletions packages/storey/src/containers/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,8 @@ where
/// in turn means the entries found between two string keys may not be the expected ones.
pub trait BoundedIterableAccessor: IterableAccessor {
/// Iterate over key-value pairs in this collection, respecting the given bounds.
///
/// Either end of the range can be unbounded, inclusive, or exclusive. See [`Bound`] for more.
fn bounded_pairs<B>(
&self,
start: Bound<B>,
Expand All @@ -202,6 +204,8 @@ pub trait BoundedIterableAccessor: IterableAccessor {
}

/// Iterate over keys in this collection, respecting the given bounds.
///
/// Either end of the range can be unbounded, inclusive, or exclusive. See [`Bound`] for more.
fn bounded_keys<B>(
&self,
start: Bound<B>,
Expand All @@ -223,6 +227,8 @@ pub trait BoundedIterableAccessor: IterableAccessor {
}

/// Iterate over values in this collection, respecting the given bounds.
///
/// Either end of the range can be unbounded, inclusive, or exclusive. See [`Bound`] for more.
fn bounded_values<B>(
&self,
start: Bound<B>,
Expand Down Expand Up @@ -259,6 +265,8 @@ where
Self::Storage: RevIterableStorage,
{
/// Iterate over key-value pairs in this collection in reverse order, respecting the given bounds.
///
/// Either end of the range can be unbounded, inclusive, or exclusive. See [`Bound`] for more.
fn bounded_rev_pairs<B>(
&self,
start: Bound<B>,
Expand All @@ -280,6 +288,8 @@ where
}

/// Iterate over keys in this collection in reverse order, respecting the given bounds.
///
/// Either end of the range can be unbounded, inclusive, or exclusive. See [`Bound`] for more.
fn bounded_rev_keys<B>(
&self,
start: Bound<B>,
Expand All @@ -301,6 +311,8 @@ where
}

/// Iterate over values in this collection in reverse order, respecting the given bounds.
///
/// Either end of the range can be unbounded, inclusive, or exclusive. See [`Bound`] for more.
fn bounded_rev_values<B>(
&self,
start: Bound<B>,
Expand Down

0 comments on commit aebd8f1

Please sign in to comment.