feat: Add Find and Exists trait and extension FindExt to easily find objects.

This is more convenient than having to rely on closures all the time.
Note that `Contains::contains` was renamed to `Exists::exists()`

Author: Byron

gix-object/src/find.rs

@@ -0,0 +1,79 @@
+/// The error type returned by the [`Find`](crate::Find) trait.
+pub type Error = Box<dyn std::error::Error + Send + Sync + 'static>;
+///
+pub mod existing {
+    use gix_hash::ObjectId;
+
+    /// The error returned by the [`find(…)`][crate::FindExt::find()] trait methods.
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        Find(crate::find::Error),
+        #[error("An object with id {} could not be found", .oid)]
+        NotFound { oid: ObjectId },
+    }
+}
+
+///
+pub mod existing_object {
+    use gix_hash::ObjectId;
+
+    /// The error returned by the various [`find_*()`][crate::FindExt::find_commit()] trait methods.
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        Find(crate::find::Error),
+        #[error("Could not decode object at {oid}")]
+        Decode {
+            oid: ObjectId,
+            source: crate::decode::Error,
+        },
+        #[error("An object with id {oid} could not be found")]
+        NotFound { oid: ObjectId },
+        #[error("Expected object of kind {expected} but got {actual} at {oid}")]
+        ObjectKind {
+            oid: ObjectId,
+            actual: crate::Kind,
+            expected: crate::Kind,
+        },
+    }
+}
+
+///
+pub mod existing_iter {
+    use gix_hash::ObjectId;
+
+    /// The error returned by the various [`find_*_iter()`][crate::FindExt::find_commit_iter()] trait methods.
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        Find(crate::find::Error),
+        #[error("An object with id {oid} could not be found")]
+        NotFound { oid: ObjectId },
+        #[error("Expected object of kind {expected} but got {actual} at {oid}")]
+        ObjectKind {
+            oid: ObjectId,
+            actual: crate::Kind,
+            expected: crate::Kind,
+        },
+    }
+}
+
+/// An implementation of all traits that never fails, but also never finds anything.
+#[derive(Debug, Copy, Clone)]
+pub struct Never;
+
+impl super::Find for Never {
+    fn try_find<'a>(&self, _id: &gix_hash::oid, _buffer: &'a mut Vec<u8>) -> Result<Option<crate::Data<'a>>, Error> {
+        Ok(None)
+    }
+}
+
+impl super::Exists for Never {
+    fn exists(&self, _id: &gix_hash::oid) -> bool {
+        false
+    }
+}

gix-object/src/lib.rs

@@ -30,8 +30,11 @@ mod blob;
 ///
 pub mod data;
 
+///
+pub mod find;
+
 mod traits;
-pub use traits::WriteTo;
+pub use traits::{Exists, Find, FindExt, WriteTo};
 
 pub mod encode;
 pub(crate) mod parse;

gix-object/src/traits.rs

@@ -41,3 +41,203 @@ where
         <T as WriteTo>::size(self)
     }
 }
+
+mod find {
+    use crate::find;
+
+    /// Check if an object is present in an object store.
+    pub trait Exists {
+        /// Returns `true` if the object exists in the database.
+        fn exists(&self, id: &gix_hash::oid) -> bool;
+    }
+
+    /// Find an object in the object store.
+    ///
+    /// ## Notes
+    ///
+    /// Find effectively needs [generic associated types][issue] to allow a trait for the returned object type.
+    /// Until then, we will have to make due with explicit types and give them the potentially added features we want.
+    ///
+    /// [issue]: https://github.com/rust-lang/rust/issues/44265
+    pub trait Find {
+        /// Find an object matching `id` in the database while placing its raw, possibly encoded data into `buffer`.
+        ///
+        /// Returns `Some` object if it was present in the database, or the error that occurred during lookup or object
+        /// retrieval.
+        fn try_find<'a>(
+            &self,
+            id: &gix_hash::oid,
+            buffer: &'a mut Vec<u8>,
+        ) -> Result<Option<crate::Data<'a>>, find::Error>;
+    }
+
+    mod _impls {
+        use std::{ops::Deref, rc::Rc, sync::Arc};
+
+        use crate::Data;
+        use gix_hash::oid;
+
+        impl<T> crate::Exists for &T
+        where
+            T: crate::Exists,
+        {
+            fn exists(&self, id: &oid) -> bool {
+                (*self).exists(id)
+            }
+        }
+
+        impl<T> crate::Find for &T
+        where
+            T: crate::Find,
+        {
+            fn try_find<'a>(&self, id: &oid, buffer: &'a mut Vec<u8>) -> Result<Option<Data<'a>>, crate::find::Error> {
+                (*self).try_find(id, buffer)
+            }
+        }
+
+        impl<T> crate::Exists for Box<T>
+        where
+            T: crate::Exists,
+        {
+            fn exists(&self, id: &oid) -> bool {
+                self.deref().exists(id)
+            }
+        }
+
+        impl<T> crate::Exists for Rc<T>
+        where
+            T: crate::Exists,
+        {
+            fn exists(&self, id: &oid) -> bool {
+                self.deref().exists(id)
+            }
+        }
+
+        impl<T> crate::Find for Rc<T>
+        where
+            T: crate::Find,
+        {
+            fn try_find<'a>(&self, id: &oid, buffer: &'a mut Vec<u8>) -> Result<Option<Data<'a>>, crate::find::Error> {
+                self.deref().try_find(id, buffer)
+            }
+        }
+
+        impl<T> crate::Find for Box<T>
+        where
+            T: crate::Find,
+        {
+            fn try_find<'a>(&self, id: &oid, buffer: &'a mut Vec<u8>) -> Result<Option<Data<'a>>, crate::find::Error> {
+                self.deref().try_find(id, buffer)
+            }
+        }
+
+        impl<T> crate::Exists for Arc<T>
+        where
+            T: crate::Exists,
+        {
+            fn exists(&self, id: &oid) -> bool {
+                self.deref().exists(id)
+            }
+        }
+
+        impl<T> crate::Find for Arc<T>
+        where
+            T: crate::Find,
+        {
+            fn try_find<'a>(&self, id: &oid, buffer: &'a mut Vec<u8>) -> Result<Option<Data<'a>>, crate::find::Error> {
+                self.deref().try_find(id, buffer)
+            }
+        }
+    }
+
+    mod ext {
+        use crate::{BlobRef, CommitRef, CommitRefIter, Kind, ObjectRef, TagRef, TagRefIter, TreeRef, TreeRefIter};
+
+        use crate::find;
+
+        macro_rules! make_obj_lookup {
+            ($method:ident, $object_variant:path, $object_kind:path, $object_type:ty) => {
+                /// Like [`find(…)`][Self::find()], but flattens the `Result<Option<_>>` into a single `Result` making a non-existing object an error
+                /// while returning the desired object type.
+                fn $method<'a>(
+                    &self,
+                    id: &gix_hash::oid,
+                    buffer: &'a mut Vec<u8>,
+                ) -> Result<$object_type, find::existing_object::Error> {
+                    self.try_find(id, buffer)
+                        .map_err(find::existing_object::Error::Find)?
+                        .ok_or_else(|| find::existing_object::Error::NotFound {
+                            oid: id.as_ref().to_owned(),
+                        })
+                        .and_then(|o| {
+                            o.decode()
+                                .map_err(|err| find::existing_object::Error::Decode {
+                                    source: err,
+                                    oid: id.as_ref().to_owned(),
+                                })
+                        })
+                        .and_then(|o| match o {
+                            $object_variant(o) => return Ok(o),
+                            o => Err(find::existing_object::Error::ObjectKind {
+                                oid: id.as_ref().to_owned(),
+                                actual: o.kind(),
+                                expected: $object_kind,
+                            }),
+                        })
+                }
+            };
+        }
+
+        macro_rules! make_iter_lookup {
+            ($method:ident, $object_kind:path, $object_type:ty, $into_iter:tt) => {
+                /// Like [`find(…)`][Self::find()], but flattens the `Result<Option<_>>` into a single `Result` making a non-existing object an error
+                /// while returning the desired iterator type.
+                fn $method<'a>(
+                    &self,
+                    id: &gix_hash::oid,
+                    buffer: &'a mut Vec<u8>,
+                ) -> Result<$object_type, find::existing_iter::Error> {
+                    self.try_find(id, buffer)
+                        .map_err(find::existing_iter::Error::Find)?
+                        .ok_or_else(|| find::existing_iter::Error::NotFound {
+                            oid: id.as_ref().to_owned(),
+                        })
+                        .and_then(|o| {
+                            o.$into_iter()
+                                .ok_or_else(|| find::existing_iter::Error::ObjectKind {
+                                    oid: id.as_ref().to_owned(),
+                                    actual: o.kind,
+                                    expected: $object_kind,
+                                })
+                        })
+                }
+            };
+        }
+
+        /// An extension trait with convenience functions.
+        pub trait FindExt: super::Find {
+            /// Like [`try_find(…)`][super::Find::try_find()], but flattens the `Result<Option<_>>` into a single `Result` making a non-existing object an error.
+            fn find<'a>(
+                &self,
+                id: &gix_hash::oid,
+                buffer: &'a mut Vec<u8>,
+            ) -> Result<crate::Data<'a>, find::existing::Error> {
+                self.try_find(id, buffer)
+                    .map_err(find::existing::Error::Find)?
+                    .ok_or_else(|| find::existing::Error::NotFound { oid: id.to_owned() })
+            }
+
+            make_obj_lookup!(find_commit, ObjectRef::Commit, Kind::Commit, CommitRef<'a>);
+            make_obj_lookup!(find_tree, ObjectRef::Tree, Kind::Tree, TreeRef<'a>);
+            make_obj_lookup!(find_tag, ObjectRef::Tag, Kind::Tag, TagRef<'a>);
+            make_obj_lookup!(find_blob, ObjectRef::Blob, Kind::Blob, BlobRef<'a>);
+            make_iter_lookup!(find_commit_iter, Kind::Commit, CommitRefIter<'a>, try_into_commit_iter);
+            make_iter_lookup!(find_tree_iter, Kind::Tree, TreeRefIter<'a>, try_into_tree_iter);
+            make_iter_lookup!(find_tag_iter, Kind::Tag, TagRefIter<'a>, try_into_tag_iter);
+        }
+
+        impl<T: super::Find + ?Sized> FindExt for T {}
+    }
+    pub use ext::FindExt;
+}
+pub use find::*;