compact_genome/interface/
sequence_store.rs

1//! Traits for genome sequence stores.
2
3use crate::interface::alphabet::{Alphabet, AlphabetError};
4use crate::interface::sequence::GenomeSequence;
5
6/// A store for sequence data, which gives out handles that can be used to retrieve concrete sequences.
7pub trait SequenceStore<AlphabetType: Alphabet> {
8    /// A handle to a sequence in this store. Can be used to retrieve the respective sequence.
9    type Handle;
10
11    /// A reference to a sequence stored in this store.
12    /// This trait only uses `&SequenceRef`, so `SequenceRef` should be the base type and not a reference type itself.
13    type SequenceRef: GenomeSequence<AlphabetType, Self::SequenceRef> + ?Sized;
14
15    /// Adds a sequence to this store and returns a handle for later retrieval.
16    /// Handles do not borrow the sequence store, so they can exist while the store is modified.
17    fn add<
18        Sequence: GenomeSequence<AlphabetType, Subsequence> + ?Sized,
19        Subsequence: GenomeSequence<AlphabetType, Subsequence> + ?Sized,
20    >(
21        &mut self,
22        s: &Sequence,
23    ) -> Self::Handle;
24
25    /// Adds a sequence to this store and returns a handle for later retrieval.
26    /// Handles do not borrow the sequence store, so they can exist while the store is modified.
27    ///
28    /// This method expects an `IntoIterator` over alphabet characters.
29    fn add_from_iter(
30        &mut self,
31        iter: impl IntoIterator<Item = AlphabetType::CharacterType>,
32    ) -> Self::Handle;
33
34    /// Adds a sequence to this store and returns a handle for later retrieval.
35    /// Handles do not borrow the sequence store, so they can exist while the store is modified.
36    ///
37    /// This method expects an `IntoIterator` over ASCII characters, and returns and error if any of the characters is not part of the alphabet.
38    fn add_from_iter_u8<IteratorType: IntoIterator<Item = u8>>(
39        &mut self,
40        iter: IteratorType,
41    ) -> Result<Self::Handle, AlphabetError>;
42
43    /// Adds a sequence to this store and returns a handle for later retrieval.
44    /// Handles do not borrow the sequence store, so they can exist while the store is modified.
45    ///
46    /// This method expects slice of ASCII characters, and returns an error if any of the characters is not part of the alphabet.
47    fn add_from_slice_u8(&mut self, slice: &[u8]) -> Result<Self::Handle, AlphabetError> {
48        self.add_from_iter_u8(slice.iter().copied())
49    }
50
51    /// Returns a reference to a sequence in this store, given the handle.
52    /// The reference borrows the sequence store, so it cannot be mutated while references exist.
53    fn get<'this: 'result, 'handle: 'result, 'result>(
54        &'this self,
55        handle: &'handle Self::Handle,
56    ) -> &'result Self::SequenceRef;
57}
58
59/// A sequence store that is able to map from references to sequences back to handles.
60pub trait InverseMappingSequenceStore<AlphabetType: Alphabet>: SequenceStore<AlphabetType> {
61    /// Returns a handle that refers the given sequence reference.
62    fn map_sequence_ref_to_handle(&self, sequence_ref: &Self::SequenceRef) -> Self::Handle;
63}
64
65/// A handle of a sequence store that can compute the length of the referred sequence without retrieving the sequence.
66pub trait HandleWithLength {
67    /// Returns the length of the sequence referred by this handle without retrieving the sequence.
68    fn len(&self) -> usize;
69
70    /// Returns true if the length of the sequence referred by this handle is zero, without retrieving the sequence.
71    fn is_empty(&self) -> bool {
72        self.len() == 0
73    }
74}
75
76/// A handle that allows the creation of handles referring arbitrary subsequences of this handle.
77pub trait HandleWithSubsequence<RangeType> {
78    /// Returns a new handle that refers the subsequence of this handle as indicated by the range.
79    /// This method may panic if the range does not define a subsequence of the sequence referred by this handle.
80    /// However, since the handle might not know anything about the sequence it refers, it might also silently ignore such errors.
81    fn subsequence_handle(&self, range: RangeType) -> Self;
82}
compact_genome/interface/sequence_store.rs

compact_genome/interface/
sequence_store.rs
