From e158e43a07329eca3907fb20a71b8d61454d034a Mon Sep 17 00:00:00 2001 From: Ximo Guanter Date: Thu, 23 Mar 2023 11:07:02 +0100 Subject: [PATCH] Make Binding public --- src/lib.rs | 2 +- src/util.rs | 16 +++++++++++++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 8b3b66dad5..c742900e8e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -139,7 +139,7 @@ pub use crate::tracing::{trace_set, TraceLevel}; pub use crate::transaction::Transaction; pub use crate::tree::{Tree, TreeEntry, TreeIter, TreeWalkMode, TreeWalkResult}; pub use crate::treebuilder::TreeBuilder; -pub use crate::util::IntoCString; +pub use crate::util::{Binding, IntoCString}; pub use crate::version::Version; pub use crate::worktree::{Worktree, WorktreeAddOptions, WorktreeLockStatus, WorktreePruneOptions}; diff --git a/src/util.rs b/src/util.rs index 5f735bc004..e06868a2dc 100644 --- a/src/util.rs +++ b/src/util.rs @@ -21,13 +21,27 @@ impl IsNull for *mut T { } } -#[doc(hidden)] +/// Provides access to the raw libgit2 pointer to be able to interact with libgit2-sys. +/// +/// If you are going to depend on this trait on your code, do consider contributing to the git2 +/// project to add the missing capabilities to git2. pub trait Binding: Sized { + /// The raw type that allows you to interact with libgit2-sys. type Raw; + /// Build a git2 struct from its [Binding::Raw] value. unsafe fn from_raw(raw: Self::Raw) -> Self; + + /// Access the [Binding::Raw] value for a struct. + /// + /// The returned value is only safe to use while its associated git2 struct is in scope. + /// Once the associated git2 struct is destroyed, the raw value can point to an invalid memory address. fn raw(&self) -> Self::Raw; + /// A null-handling version of [Binding::from_raw]. + /// + /// If the input parameter is null, then the funtion returns None. Otherwise, it + /// calls [Binding::from_raw]. unsafe fn from_raw_opt(raw: T) -> Option where T: Copy + IsNull,