foundationdb/
keyselector.rs

1// Copyright 2018 foundationdb-rs developers, https://github.com/Clikengo/foundationdb-rs/graphs/contributors
2// Copyright 2013-2018 Apple, Inc and the FoundationDB project authors.
3//
4// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
5// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
6// http://opensource.org/licenses/MIT>, at your option. This file may not be
7// copied, modified, or distributed except according to those terms.
8
9//! A `KeySelector` identifies a particular key in the database.
10
11use crate::tuple::Bytes;
12use std::borrow::Cow;
13
14/// A `KeySelector` identifies a particular key in the database.
15///
16/// FoundationDB's lexicographically ordered data model permits finding keys based on their order
17/// (for example, finding the first key in the database greater than a given key). Key selectors
18/// represent a description of a key in the database that could be resolved to an actual key by
19/// `Transaction::get_key` or used directly as the beginning or end of a range in
20/// `Transaction::getRange`.
21///
22/// Note that the way the key selectors are resolved is somewhat non-intuitive, so users who wish
23/// to use a key selector other than the default ones described below should probably consult that
24/// documentation before proceeding.
25///
26/// Generally one of the following static methods should be used to construct a KeySelector:
27///
28/// - `last_less_than`
29/// - `last_less_or_equal`
30/// - `first_greater_than`
31/// - `first_greater_or_equal`
32#[derive(Clone, Debug)]
33pub struct KeySelector<'a> {
34    key: Bytes<'a>,
35    or_equal: bool,
36    offset: i32,
37}
38
39impl<'a> KeySelector<'a> {
40    /// Constructs a new KeySelector from the given parameters.
41    pub const fn new(key: Cow<'a, [u8]>, or_equal: bool, offset: i32) -> Self {
42        Self {
43            key: Bytes(key),
44            or_equal,
45            offset,
46        }
47    }
48
49    /// Returns a the key that serves as the anchor for this `KeySelector`
50    pub fn key(&self) -> &[u8] {
51        self.key.as_ref()
52    }
53
54    /// True if this is an `or_equal` `KeySelector`
55    pub fn or_equal(&self) -> bool {
56        self.or_equal
57    }
58
59    /// Returns the key offset parameter for this `KeySelector`
60    pub fn offset(&self) -> i32 {
61        self.offset
62    }
63
64    /// Creates a `KeySelector` that picks the last key less than the parameter
65    pub fn last_less_than<K: Into<Cow<'a, [u8]>>>(key: K) -> Self {
66        Self::new(key.into(), false, 0)
67    }
68
69    /// Creates a `KeySelector` that picks the last key less than or equal to the parameter
70    pub fn last_less_or_equal<K: Into<Cow<'a, [u8]>>>(key: K) -> Self {
71        Self::new(key.into(), true, 0)
72    }
73
74    /// Creates a `KeySelector` that picks the first key greater than the parameter
75    pub fn first_greater_than<K: Into<Cow<'a, [u8]>>>(key: K) -> Self {
76        Self::new(key.into(), true, 1)
77    }
78
79    /// Creates a `KeySelector` that picks the first key greater than or equal to the parameter
80    pub fn first_greater_or_equal<K: Into<Cow<'a, [u8]>>>(key: K) -> Self {
81        Self::new(key.into(), false, 1)
82    }
83
84    fn make_key(&mut self, key: &[u8]) {
85        match &mut self.key {
86            Bytes(Cow::Borrowed(..)) => self.key = Bytes::from(key.to_owned()),
87            Bytes(Cow::Owned(vec)) => {
88                vec.clear();
89                vec.extend_from_slice(key);
90            }
91        };
92    }
93
94    pub(crate) fn make_first_greater_or_equal(&mut self, key: &[u8]) {
95        self.make_key(key);
96        self.or_equal = false;
97        self.offset = 1;
98    }
99
100    pub(crate) fn make_first_greater_than(&mut self, key: &[u8]) {
101        self.make_key(key);
102        self.or_equal = true;
103        self.offset = 1;
104    }
105}
foundationdb/keyselector.rs

foundationdb/
keyselector.rs
