rust-nodemap: NodeMap trait with simplest implementation

We're defining here only a small part of the immutable
methods it will have at the end. This is so we can
focus in the following changesets on the needed abstractions
for a mutable append-only serializable version.

The first implementor exposes the actual lookup
algorithm in its simplest form. It will have to be expanded
to account for the missing methods, and the special cases
related to NULL_NODE.

Differential Revision: https://phab.mercurial-scm.org/D7791

rust/hg-core/src/revlog/node.rs

@@ -1,364 +1,367 b''
 // Copyright 2019-2020 Georges Racinet <[e-mail]>
 //
 // This software may be used and distributed according to the terms of the
 // GNU General Public License version 2 or any later version.
 
 //! Definitions and utilities for Revision nodes
 //!
 //! In Mercurial code base, it is customary to call "a node" the binary SHA
 //! of a revision.
 
 use hex::{self, FromHex, FromHexError};
 
 /// The length in bytes of a `Node`
 ///
 /// This constant is meant to ease refactors of this module, and
 /// are private so that calling code does not expect all nodes have
 /// the same size, should we support several formats concurrently in
 /// the future.
 const NODE_BYTES_LENGTH: usize = 20;
 
 /// The length in bytes of a `Node`
 ///
 /// see also `NODES_BYTES_LENGTH` about it being private.
 const NODE_NYBBLES_LENGTH: usize = 2 * NODE_BYTES_LENGTH;
 
 /// Private alias for readability and to ease future change
 type NodeData = [u8; NODE_BYTES_LENGTH];
 
 /// Binary revision SHA
 ///
 /// ## Future changes of hash size
 ///
 /// To accomodate future changes of hash size, Rust callers
 /// should use the conversion methods at the boundaries (FFI, actual
 /// computation of hashes and I/O) only, and only if required.
 ///
 /// All other callers outside of unit tests should just handle `Node` values
 /// and never make any assumption on the actual length, using [`nybbles_len`]
 /// if they need a loop boundary.
 ///
 /// All methods that create a `Node` either take a type that enforces
 /// the size or fail immediately at runtime with [`ExactLengthRequired`].
 ///
 /// [`nybbles_len`]: #method.nybbles_len
 /// [`ExactLengthRequired`]: struct.NodeError#variant.ExactLengthRequired
 #[derive(Clone, Debug, PartialEq)]
 pub struct Node {
     data: NodeData,
 }
 
 /// The node value for NULL_REVISION
 pub const NULL_NODE: Node = Node {
     data: [0; NODE_BYTES_LENGTH],
 };
 
 impl From<NodeData> for Node {
     fn from(data: NodeData) -> Node {
         Node { data }
     }
 }
 
 #[derive(Debug, PartialEq)]
 pub enum NodeError {
     ExactLengthRequired(usize, String),
     PrefixTooLong(String),
     HexError(FromHexError, String),
 }
 
 /// Low level utility function, also for prefixes
 fn get_nybble(s: &[u8], i: usize) -> u8 {
     if i % 2 == 0 {
         s[i / 2] >> 4
     } else {
         s[i / 2] & 0x0f
     }
 }
 
 impl Node {
     /// Retrieve the `i`th half-byte of the binary data.
     ///
     /// This is also the `i`th hexadecimal digit in numeric form,
     /// also called a [nybble](https://en.wikipedia.org/wiki/Nibble).
     pub fn get_nybble(&self, i: usize) -> u8 {
         get_nybble(&self.data, i)
     }
 
     /// Length of the data, in nybbles
     pub fn nybbles_len(&self) -> usize {
         // public exposure as an instance method only, so that we can
         // easily support several sizes of hashes if needed in the future.
         NODE_NYBBLES_LENGTH
     }
 
     /// Convert from hexadecimal string representation
     ///
     /// Exact length is required.
     ///
     /// To be used in FFI and I/O only, in order to facilitate future
     /// changes of hash format.
     pub fn from_hex(hex: &str) -> Result<Node, NodeError> {
         Ok(NodeData::from_hex(hex)
             .map_err(|e| NodeError::from((e, hex)))?
             .into())
     }
 
     /// Convert to hexadecimal string representation
     ///
     /// To be used in FFI and I/O only, in order to facilitate future
     /// changes of hash format.
     pub fn encode_hex(&self) -> String {
         hex::encode(self.data)
     }
 
     /// Provide access to binary data
     ///
     /// This is needed by FFI layers, for instance to return expected
     /// binary values to Python.
     pub fn as_bytes(&self) -> &[u8] {
         &self.data
     }
 }
 
 impl<T: AsRef<str>> From<(FromHexError, T)> for NodeError {
     fn from(err_offender: (FromHexError, T)) -> Self {
         let (err, offender) = err_offender;
         match err {
             FromHexError::InvalidStringLength => {
                 NodeError::ExactLengthRequired(
                     NODE_NYBBLES_LENGTH,
                     offender.as_ref().to_owned(),
                 )
             }
             _ => NodeError::HexError(err, offender.as_ref().to_owned()),
         }
     }
 }
 
 /// The beginning of a binary revision SHA.
 ///
 /// Since it can potentially come from an hexadecimal representation with
 /// odd length, it needs to carry around whether the last 4 bits are relevant
 /// or not.
 #[derive(Debug, PartialEq)]
 pub struct NodePrefix {
     buf: Vec<u8>,
     is_odd: bool,
 }
 
 impl NodePrefix {
     /// Convert from hexadecimal string representation
     ///
     /// Similarly to `hex::decode`, can be used with Unicode string types
     /// (`String`, `&str`) as well as bytes.
     ///
     /// To be used in FFI and I/O only, in order to facilitate future
     /// changes of hash format.
     pub fn from_hex(hex: impl AsRef<[u8]>) -> Result<Self, NodeError> {
         let hex = hex.as_ref();
         let len = hex.len();
         if len > NODE_NYBBLES_LENGTH {
             return Err(NodeError::PrefixTooLong(
                 String::from_utf8_lossy(hex).to_owned().to_string(),
             ));
         }
 
         let is_odd = len % 2 == 1;
         let even_part = if is_odd { &hex[..len - 1] } else { hex };
         let mut buf: Vec<u8> = Vec::from_hex(&even_part)
             .map_err(|e| (e, String::from_utf8_lossy(hex)))?;
 
         if is_odd {
             let latest_char = char::from(hex[len - 1]);
             let latest_nybble = latest_char.to_digit(16).ok_or_else(|| {
                 (
                     FromHexError::InvalidHexCharacter {
                         c: latest_char,
                         index: len - 1,
                     },
                     String::from_utf8_lossy(hex),
                 )
             })? as u8;
             buf.push(latest_nybble << 4);
         }
         Ok(NodePrefix { buf, is_odd })
     }
 
     pub fn borrow(&self) -> NodePrefixRef {
         NodePrefixRef {
             buf: &self.buf,
             is_odd: self.is_odd,
         }
     }
 }
 
 #[derive(Clone, Debug, PartialEq)]
 pub struct NodePrefixRef<'a> {
     buf: &'a [u8],
     is_odd: bool,
 }
 
 impl<'a> NodePrefixRef<'a> {
     pub fn len(&self) -> usize {
         if self.is_odd {
             self.buf.len() * 2 - 1
         } else {
             self.buf.len() * 2
         }
     }
 
     pub fn is_prefix_of(&self, node: &Node) -> bool {
         if self.is_odd {
             let buf = self.buf;
             let last_pos = buf.len() - 1;
             node.data.starts_with(buf.split_at(last_pos).0)
                 && node.data[last_pos] >> 4 == buf[last_pos] >> 4
         } else {
             node.data.starts_with(self.buf)
         }
     }
 
     /// Retrieve the `i`th half-byte from the prefix.
     ///
     /// This is also the `i`th hexadecimal digit in numeric form,
     /// also called a [nybble](https://en.wikipedia.org/wiki/Nibble).
     pub fn get_nybble(&self, i: usize) -> u8 {
         get_nybble(self.buf, i)
     }
 }
 
 /// A shortcut for full `Node` references
 impl<'a> From<&'a Node> for NodePrefixRef<'a> {
     fn from(node: &'a Node) -> Self {
         NodePrefixRef {
             buf: &node.data,
             is_odd: false,
         }
     }
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
     fn sample_node() -> Node {
         let mut data = [0; NODE_BYTES_LENGTH];
         data.copy_from_slice(&[
             0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xfe, 0xdc, 0xba,
             0x98, 0x76, 0x54, 0x32, 0x10, 0xde, 0xad, 0xbe, 0xef,
         ]);
         data.into()
     }
 
     /// Pad an hexadecimal string to reach `NODE_NYBBLES_LENGTH`
     ///
     /// The padding is made with zeros
-    fn hex_pad_right(hex: &str) -> String {
+    pub fn hex_pad_right(hex: &str) -> String {
         let mut res = hex.to_string();
         while res.len() < NODE_NYBBLES_LENGTH {
             res.push('0');
         }
         res
     }
 
     fn sample_node_hex() -> String {
         hex_pad_right("0123456789abcdeffedcba9876543210deadbeef")
     }
 
     #[test]
     fn test_node_from_hex() {
         assert_eq!(Node::from_hex(&sample_node_hex()), Ok(sample_node()));
 
         let mut short = hex_pad_right("0123");
         short.pop();
         short.pop();
         assert_eq!(
             Node::from_hex(&short),
             Err(NodeError::ExactLengthRequired(NODE_NYBBLES_LENGTH, short)),
         );
 
         let not_hex = hex_pad_right("012... oops");
         assert_eq!(
             Node::from_hex(&not_hex),
             Err(NodeError::HexError(
                 FromHexError::InvalidHexCharacter { c: '.', index: 3 },
                 not_hex,
             )),
         );
     }
 
     #[test]
     fn test_node_encode_hex() {
         assert_eq!(sample_node().encode_hex(), sample_node_hex());
     }
 
     #[test]
     fn test_prefix_from_hex() -> Result<(), NodeError> {
         assert_eq!(
             NodePrefix::from_hex("0e1")?,
             NodePrefix {
                 buf: vec![14, 16],
                 is_odd: true
             }
         );
         assert_eq!(
             NodePrefix::from_hex("0e1a")?,
             NodePrefix {
                 buf: vec![14, 26],
                 is_odd: false
             }
         );
 
         // checking limit case
         let node_as_vec = sample_node().data.iter().cloned().collect();
         assert_eq!(
             NodePrefix::from_hex(sample_node_hex())?,
             NodePrefix {
                 buf: node_as_vec,
                 is_odd: false
             }
         );
 
         Ok(())
     }
 
     #[test]
     fn test_prefix_from_hex_errors() {
         assert_eq!(
             NodePrefix::from_hex("testgr"),
             Err(NodeError::HexError(
                 FromHexError::InvalidHexCharacter { c: 't', index: 0 },
                 "testgr".to_string()
             ))
         );
         let mut long = NULL_NODE.encode_hex();
         long.push('c');
         match NodePrefix::from_hex(&long)
             .expect_err("should be refused as too long")
         {
             NodeError::PrefixTooLong(s) => assert_eq!(s, long),
             err => panic!(format!("Should have been TooLong, got {:?}", err)),
         }
     }
 
     #[test]
     fn test_is_prefix_of() -> Result<(), NodeError> {
         let mut node_data = [0; NODE_BYTES_LENGTH];
         node_data[0] = 0x12;
         node_data[1] = 0xca;
         let node = Node::from(node_data);
         assert!(NodePrefix::from_hex("12")?.borrow().is_prefix_of(&node));
         assert!(!NodePrefix::from_hex("1a")?.borrow().is_prefix_of(&node));
         assert!(NodePrefix::from_hex("12c")?.borrow().is_prefix_of(&node));
         assert!(!NodePrefix::from_hex("12d")?.borrow().is_prefix_of(&node));
         Ok(())
     }
 
     #[test]
     fn test_get_nybble() -> Result<(), NodeError> {
         let prefix = NodePrefix::from_hex("dead6789cafe")?;
         assert_eq!(prefix.borrow().get_nybble(0), 13);
         assert_eq!(prefix.borrow().get_nybble(7), 9);
         Ok(())
     }
 }
+
+#[cfg(test)]
+pub use tests::hex_pad_right;

rust/hg-core/src/revlog/nodemap.rs

@@ -1,160 +1,388 b''
 // Copyright 2018-2020 Georges Racinet <[e-mail]>
 //           and Mercurial contributors
 //
 // This software may be used and distributed according to the terms of the
 // GNU General Public License version 2 or any later version.
 //! Indexing facilities for fast retrieval of `Revision` from `Node`
 //!
 //! This provides a variation on the 16-ary radix tree that is
 //! provided as "nodetree" in revlog.c, ready for append-only persistence
 //! on disk.
 //!
 //! Following existing implicit conventions, the "nodemap" terminology
 //! is used in a more abstract context.
 
-use super::Revision;
+use super::{
+    Node, NodeError, NodePrefix, NodePrefixRef, Revision, RevlogIndex,
+};
 use std::fmt;
+use std::ops::Deref;
+
+#[derive(Debug, PartialEq)]
+pub enum NodeMapError {
+    MultipleResults,
+    InvalidNodePrefix(NodeError),
+    /// A `Revision` stored in the nodemap could not be found in the index
+    RevisionNotInIndex(Revision),
+}
+
+impl From<NodeError> for NodeMapError {
+    fn from(err: NodeError) -> Self {
+        NodeMapError::InvalidNodePrefix(err)
+    }
+}
+
+/// Mapping system from Mercurial nodes to revision numbers.
+///
+/// ## `RevlogIndex` and `NodeMap`
+///
+/// One way to think about their relationship is that
+/// the `NodeMap` is a prefix-oriented reverse index of the `Node` information
+/// carried by a [`RevlogIndex`].
+///
+/// Many of the methods in this trait take a `RevlogIndex` argument
+/// which is used for validation of their results. This index must naturally
+/// be the one the `NodeMap` is about, and it must be consistent.
+///
+/// Notably, the `NodeMap` must not store
+/// information about more `Revision` values than there are in the index.
+/// In these methods, an encountered `Revision` is not in the index, a
+/// [`RevisionNotInIndex`] error is returned.
+///
+/// In insert operations, the rule is thus that the `NodeMap` must always
+/// be updated after the `RevlogIndex`
+/// be updated first, and the `NodeMap` second.
+///
+/// [`RevisionNotInIndex`]: enum.NodeMapError.html#variant.RevisionNotInIndex
+/// [`RevlogIndex`]: ../trait.RevlogIndex.html
+pub trait NodeMap {
+    /// Find the unique `Revision` having the given `Node`
+    ///
+    /// If no Revision matches the given `Node`, `Ok(None)` is returned.
+    fn find_node(
+        &self,
+        index: &impl RevlogIndex,
+        node: &Node,
+    ) -> Result<Option<Revision>, NodeMapError> {
+        self.find_bin(index, node.into())
+    }
+
+    /// Find the unique Revision whose `Node` starts with a given binary prefix
+    ///
+    /// If no Revision matches the given prefix, `Ok(None)` is returned.
+    ///
+    /// If several Revisions match the given prefix, a [`MultipleResults`]
+    /// error is returned.
+    fn find_bin<'a>(
+        &self,
+        idx: &impl RevlogIndex,
+        prefix: NodePrefixRef<'a>,
+    ) -> Result<Option<Revision>, NodeMapError>;
+
+    /// Find the unique Revision whose `Node` hexadecimal string representation
+    /// starts with a given prefix
+    ///
+    /// If no Revision matches the given prefix, `Ok(None)` is returned.
+    ///
+    /// If several Revisions match the given prefix, a [`MultipleResults`]
+    /// error is returned.
+    fn find_hex(
+        &self,
+        idx: &impl RevlogIndex,
+        prefix: &str,
+    ) -> Result<Option<Revision>, NodeMapError> {
+        self.find_bin(idx, NodePrefix::from_hex(prefix)?.borrow())
+    }
+}
 
 /// Low level NodeTree [`Blocks`] elements
 ///
 /// These are exactly as for instance on persistent storage.
 type RawElement = i32;
 
 /// High level representation of values in NodeTree
 /// [`Blocks`](struct.Block.html)
 ///
 /// This is the high level representation that most algorithms should
 /// use.
 #[derive(Clone, Debug, Eq, PartialEq)]
 enum Element {
     Rev(Revision),
     Block(usize),
     None,
 }
 
 impl From<RawElement> for Element {
     /// Conversion from low level representation, after endianness conversion.
     ///
     /// See [`Block`](struct.Block.html) for explanation about the encoding.
     fn from(raw: RawElement) -> Element {
         if raw >= 0 {
             Element::Block(raw as usize)
         } else if raw == -1 {
             Element::None
         } else {
             Element::Rev(-raw - 2)
         }
     }
 }
 
 impl From<Element> for RawElement {
     fn from(element: Element) -> RawElement {
         match element {
             Element::None => 0,
             Element::Block(i) => i as RawElement,
             Element::Rev(rev) => -rev - 2,
         }
     }
 }
 
 /// A logical block of the `NodeTree`, packed with a fixed size.
 ///
 /// These are always used in container types implementing `Index<Block>`,
 /// such as `&Block`
 ///
 /// As an array of integers, its ith element encodes that the
 /// ith potential edge from the block, representing the ith hexadecimal digit
 /// (nybble) `i` is either:
 ///
 /// - absent (value -1)
 /// - another `Block` in the same indexable container (value ≥ 0)
 ///  - a `Revision` leaf (value ≤ -2)
 ///
 /// Endianness has to be fixed for consistency on shared storage across
 /// different architectures.
 ///
 /// A key difference with the C `nodetree` is that we need to be
 /// able to represent the [`Block`] at index 0, hence -1 is the empty marker
 /// rather than 0 and the `Revision` range upper limit of -2 instead of -1.
 ///
 /// Another related difference is that `NULL_REVISION` (-1) is not
 /// represented at all, because we want an immutable empty nodetree
 /// to be valid.
 
 #[derive(Clone, PartialEq)]
 pub struct Block([RawElement; 16]);
 
 impl Block {
     fn new() -> Self {
         Block([-1; 16])
     }
 
     fn get(&self, nybble: u8) -> Element {
         Element::from(RawElement::from_be(self.0[nybble as usize]))
     }
 
     fn set(&mut self, nybble: u8, element: Element) {
         self.0[nybble as usize] = RawElement::to_be(element.into())
     }
 }
 
 impl fmt::Debug for Block {
     /// sparse representation for testing and debugging purposes
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         f.debug_map()
             .entries((0..16).filter_map(|i| match self.get(i) {
                 Element::None => None,
                 element => Some((i, element)),
             }))
             .finish()
     }
 }
 
+/// A 16-radix tree with the root block at the end
+pub struct NodeTree {
+    readonly: Box<dyn Deref<Target = [Block]> + Send>,
+}
+
+/// Return `None` unless the `Node` for `rev` has given prefix in `index`.
+fn has_prefix_or_none<'p>(
+    idx: &impl RevlogIndex,
+    prefix: NodePrefixRef<'p>,
+    rev: Revision,
+) -> Result<Option<Revision>, NodeMapError> {
+    idx.node(rev)
+        .ok_or_else(|| NodeMapError::RevisionNotInIndex(rev))
+        .map(|node| {
+            if prefix.is_prefix_of(node) {
+                Some(rev)
+            } else {
+                None
+            }
+        })
+}
+
+impl NodeTree {
+    /// Main working method for `NodeTree` searches
+    ///
+    /// This partial implementation lacks special cases for NULL_REVISION
+    fn lookup<'p>(
+        &self,
+        prefix: NodePrefixRef<'p>,
+    ) -> Result<Option<Revision>, NodeMapError> {
+        let blocks: &[Block] = &*self.readonly;
+        if blocks.is_empty() {
+            return Ok(None);
+        }
+        let mut visit = blocks.len() - 1;
+        for i in 0..prefix.len() {
+            let nybble = prefix.get_nybble(i);
+            match blocks[visit].get(nybble) {
+                Element::None => return Ok(None),
+                Element::Rev(r) => return Ok(Some(r)),
+                Element::Block(idx) => visit = idx,
+            }
+        }
+        Err(NodeMapError::MultipleResults)
+    }
+}
+
+impl From<Vec<Block>> for NodeTree {
+    fn from(vec: Vec<Block>) -> Self {
+        NodeTree {
+            readonly: Box::new(vec),
+        }
+    }
+}
+
+impl fmt::Debug for NodeTree {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let blocks: &[Block] = &*self.readonly;
+        write!(f, "readonly: {:?}", blocks)
+    }
+}
+
+impl NodeMap for NodeTree {
+    fn find_bin<'a>(
+        &self,
+        idx: &impl RevlogIndex,
+        prefix: NodePrefixRef<'a>,
+    ) -> Result<Option<Revision>, NodeMapError> {
+        self.lookup(prefix.clone()).and_then(|opt| {
+            opt.map_or(Ok(None), |rev| has_prefix_or_none(idx, prefix, rev))
+        })
+    }
+}
+
 #[cfg(test)]
 mod tests {
+    use super::NodeMapError::*;
     use super::*;
+    use crate::revlog::node::{hex_pad_right, Node};
+    use std::collections::HashMap;
 
     /// Creates a `Block` using a syntax close to the `Debug` output
     macro_rules! block {
         {$($nybble:tt : $variant:ident($val:tt)),*} => (
             {
                 let mut block = Block::new();
                 $(block.set($nybble, Element::$variant($val)));*;
                 block
             }
         )
     }
 
     #[test]
     fn test_block_debug() {
         let mut block = Block::new();
         block.set(1, Element::Rev(3));
         block.set(10, Element::Block(0));
         assert_eq!(format!("{:?}", block), "{1: Rev(3), 10: Block(0)}");
     }
 
     #[test]
     fn test_block_macro() {
         let block = block! {5: Block(2)};
         assert_eq!(format!("{:?}", block), "{5: Block(2)}");
 
         let block = block! {13: Rev(15), 5: Block(2)};
         assert_eq!(format!("{:?}", block), "{5: Block(2), 13: Rev(15)}");
     }
 
     #[test]
     fn test_raw_block() {
         let mut raw = [-1; 16];
         raw[0] = 0;
         raw[1] = RawElement::to_be(15);
         raw[2] = RawElement::to_be(-2);
         raw[3] = RawElement::to_be(-1);
         raw[4] = RawElement::to_be(-3);
         let block = Block(raw);
         assert_eq!(block.get(0), Element::Block(0));
         assert_eq!(block.get(1), Element::Block(15));
         assert_eq!(block.get(3), Element::None);
         assert_eq!(block.get(2), Element::Rev(0));
         assert_eq!(block.get(4), Element::Rev(1));
     }
+
+    type TestIndex = HashMap<Revision, Node>;
+
+    impl RevlogIndex for TestIndex {
+        fn node(&self, rev: Revision) -> Option<&Node> {
+            self.get(&rev)
+        }
+
+        fn len(&self) -> usize {
+            self.len()
+        }
+    }
+
+    /// Pad hexadecimal Node prefix with zeros on the right, then insert
+    ///
+    /// This avoids having to repeatedly write very long hexadecimal
+    /// strings for test data, and brings actual hash size independency.
+    fn pad_insert(idx: &mut TestIndex, rev: Revision, hex: &str) {
+        idx.insert(rev, Node::from_hex(&hex_pad_right(hex)).unwrap());
+    }
+
+    fn sample_nodetree() -> NodeTree {
+        NodeTree::from(vec![
+            block![0: Rev(9)],
+            block![0: Rev(0), 1: Rev(9)],
+            block![0: Block(1), 1:Rev(1)],
+        ])
+    }
+
+    #[test]
+    fn test_nt_debug() {
+        let nt = sample_nodetree();
+        assert_eq!(
+            format!("{:?}", nt),
+            "readonly: \
+             [{0: Rev(9)}, {0: Rev(0), 1: Rev(9)}, {0: Block(1), 1: Rev(1)}]"
+        );
+    }
+
+    #[test]
+    fn test_immutable_find_simplest() -> Result<(), NodeMapError> {
+        let mut idx: TestIndex = HashMap::new();
+        pad_insert(&mut idx, 1, "1234deadcafe");
+
+        let nt = NodeTree::from(vec![block![1: Rev(1)]]);
+        assert_eq!(nt.find_hex(&idx, "1")?, Some(1));
+        assert_eq!(nt.find_hex(&idx, "12")?, Some(1));
+        assert_eq!(nt.find_hex(&idx, "1234de")?, Some(1));
+        assert_eq!(nt.find_hex(&idx, "1a")?, None);
+        assert_eq!(nt.find_hex(&idx, "ab")?, None);
+
+        // and with full binary Nodes
+        assert_eq!(nt.find_node(&idx, idx.get(&1).unwrap())?, Some(1));
+        let unknown = Node::from_hex(&hex_pad_right("3d")).unwrap();
+        assert_eq!(nt.find_node(&idx, &unknown)?, None);
+        Ok(())
+    }
+
+    #[test]
+    fn test_immutable_find_one_jump() {
+        let mut idx = TestIndex::new();
+        pad_insert(&mut idx, 9, "012");
+        pad_insert(&mut idx, 0, "00a");
+
+        let nt = sample_nodetree();
+
+        assert_eq!(nt.find_hex(&idx, "0"), Err(MultipleResults));
+        assert_eq!(nt.find_hex(&idx, "01"), Ok(Some(9)));
+        assert_eq!(nt.find_hex(&idx, "00"), Ok(Some(0)));
+        assert_eq!(nt.find_hex(&idx, "00a"), Ok(Some(0)));
+    }
 }