gix_hash/
oid.rs

1use std::hash;
2
3use crate::{Kind, ObjectId};
4
5#[cfg(feature = "sha1")]
6use crate::{EMPTY_BLOB_SHA1, EMPTY_TREE_SHA1, SIZE_OF_SHA1_DIGEST};
7
8#[cfg(feature = "sha256")]
9use crate::{EMPTY_BLOB_SHA256, EMPTY_TREE_SHA256, SIZE_OF_SHA256_DIGEST};
10
11/// A borrowed reference to a hash identifying objects.
12///
13/// # Future Proofing
14///
15/// In case we wish to support multiple hashes with the same length we cannot discriminate
16/// using the slice length anymore. To make that work, we will use the high bits of the
17/// internal `bytes` slice length (a fat pointer, pointing to data and its length in bytes)
18/// to encode additional information. Before accessing or returning the bytes, a new adjusted
19/// slice will be constructed, while the high bits will be used to help resolving the
20/// hash [`kind()`][oid::kind()].
21/// We expect to have quite a few bits available for such 'conflict resolution' as most hashes aren't longer
22/// than 64 bytes.
23#[derive(PartialEq, Eq, Ord, PartialOrd)]
24#[repr(transparent)]
25#[allow(non_camel_case_types)]
26#[cfg_attr(feature = "serde", derive(serde::Serialize))]
27pub struct oid {
28    bytes: [u8],
29}
30
31// False positive:
32// Using an automatic implementation of `Hash` for `oid` would lead to
33// it attempting to hash the length of the slice first. On 32 bit systems
34// this can lead to issues with the custom `gix_hashtable` `Hasher` implementation,
35// and it currently ends up being discarded there anyway.
36#[allow(clippy::derived_hash_with_manual_eq)]
37impl hash::Hash for oid {
38    fn hash<H: hash::Hasher>(&self, state: &mut H) {
39        state.write(self.as_bytes());
40    }
41}
42
43/// A utility able to format itself with the given number of characters in hex.
44#[derive(PartialEq, Eq, Hash, Ord, PartialOrd)]
45pub struct HexDisplay<'a> {
46    inner: &'a oid,
47    hex_len: usize,
48}
49
50impl std::fmt::Display for HexDisplay<'_> {
51    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
52        let mut hex = Kind::hex_buf();
53        let hex = self.inner.hex_to_buf(hex.as_mut());
54        let max_len = hex.len();
55        f.write_str(&hex[..self.hex_len.min(max_len)])
56    }
57}
58
59impl std::fmt::Debug for oid {
60    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
61        write!(
62            f,
63            "{}({})",
64            match self.kind() {
65                #[cfg(feature = "sha1")]
66                Kind::Sha1 => "Sha1",
67                #[cfg(feature = "sha256")]
68                Kind::Sha256 => "Sha256",
69            },
70            self.to_hex(),
71        )
72    }
73}
74
75/// The error returned when trying to convert a byte slice to an [`oid`] or [`ObjectId`]
76#[allow(missing_docs)]
77#[derive(Debug, thiserror::Error)]
78pub enum Error {
79    #[error("Cannot instantiate git hash from a digest of length {0}")]
80    InvalidByteSliceLength(usize),
81}
82
83/// Conversion
84impl oid {
85    /// Try to create a shared object id from a slice of bytes representing a hash `digest`
86    #[inline]
87    pub fn try_from_bytes(digest: &[u8]) -> Result<&Self, Error> {
88        match digest.len() {
89            #[cfg(feature = "sha1")]
90            SIZE_OF_SHA1_DIGEST => Ok(
91                #[allow(unsafe_code)]
92                unsafe {
93                    &*(std::ptr::from_ref::<[u8]>(digest) as *const oid)
94                },
95            ),
96            #[cfg(feature = "sha256")]
97            SIZE_OF_SHA256_DIGEST => Ok(
98                #[allow(unsafe_code)]
99                unsafe {
100                    &*(std::ptr::from_ref::<[u8]>(digest) as *const oid)
101                },
102            ),
103            len => Err(Error::InvalidByteSliceLength(len)),
104        }
105    }
106
107    /// Create an `oid` from the input `value` slice without performing any length check.
108    /// Use only once you are sure that `value` is a hash of valid length, or panics will occur on most uses.
109    pub fn from_bytes_unchecked(value: &[u8]) -> &Self {
110        Self::from_bytes(value)
111    }
112
113    /// Only from code that statically assures correct sizes using array conversions.
114    pub(crate) fn from_bytes(value: &[u8]) -> &Self {
115        #[allow(unsafe_code)]
116        unsafe {
117            &*(std::ptr::from_ref::<[u8]>(value) as *const oid)
118        }
119    }
120}
121
122/// Access
123impl oid {
124    /// The kind of hash used for this instance.
125    #[inline]
126    pub fn kind(&self) -> Kind {
127        Kind::from_len_in_bytes(self.bytes.len())
128    }
129
130    /// The first byte of the hash, commonly used to partition a set of object ids.
131    #[inline]
132    pub fn first_byte(&self) -> u8 {
133        self.bytes[0]
134    }
135
136    /// Interpret this object id as raw byte slice.
137    #[inline]
138    pub fn as_bytes(&self) -> &[u8] {
139        &self.bytes
140    }
141
142    /// Return a type which can display itself in hexadecimal form with the `len` amount of characters.
143    #[inline]
144    pub fn to_hex_with_len(&self, len: usize) -> HexDisplay<'_> {
145        HexDisplay {
146            inner: self,
147            hex_len: len,
148        }
149    }
150
151    /// Return a type which displays this `oid` as hex in full.
152    #[inline]
153    pub fn to_hex(&self) -> HexDisplay<'_> {
154        HexDisplay {
155            inner: self,
156            hex_len: self.bytes.len() * 2,
157        }
158    }
159
160    /// Write ourselves to the `out` in hexadecimal notation, returning the hex-string ready for display.
161    ///
162    /// # Panics
163    ///
164    /// If the buffer isn't big enough to hold twice as many bytes as the current binary size.
165    #[inline]
166    #[must_use]
167    pub fn hex_to_buf<'a>(&self, buf: &'a mut [u8]) -> &'a mut str {
168        let num_hex_bytes = self.bytes.len() * 2;
169        faster_hex::hex_encode(&self.bytes, &mut buf[..num_hex_bytes])
170            .expect("buffer size must be at least twice the hash digest size in bytes")
171    }
172
173    /// Write ourselves to `out` in hexadecimal notation.
174    #[inline]
175    pub fn write_hex_to(&self, out: &mut dyn std::io::Write) -> std::io::Result<()> {
176        let mut hex = Kind::hex_buf();
177        let hex_len = self.hex_to_buf(&mut hex).len();
178        out.write_all(&hex[..hex_len])
179    }
180
181    /// Returns `true` if this hash consists of all null bytes.
182    #[inline]
183    #[doc(alias = "is_zero", alias = "git2")]
184    pub fn is_null(&self) -> bool {
185        match self.kind() {
186            #[cfg(feature = "sha1")]
187            Kind::Sha1 => &self.bytes == oid::null_sha1().as_bytes(),
188            #[cfg(feature = "sha256")]
189            Kind::Sha256 => &self.bytes == oid::null_sha256().as_bytes(),
190        }
191    }
192
193    /// Returns `true` if this hash is equal to an empty blob.
194    #[inline]
195    pub fn is_empty_blob(&self) -> bool {
196        match self.kind() {
197            #[cfg(feature = "sha1")]
198            Kind::Sha1 => &self.bytes == oid::empty_blob_sha1().as_bytes(),
199            #[cfg(feature = "sha256")]
200            Kind::Sha256 => &self.bytes == oid::empty_blob_sha256().as_bytes(),
201        }
202    }
203
204    /// Returns `true` if this hash is equal to an empty tree.
205    #[inline]
206    pub fn is_empty_tree(&self) -> bool {
207        match self.kind() {
208            #[cfg(feature = "sha1")]
209            Kind::Sha1 => &self.bytes == oid::empty_tree_sha1().as_bytes(),
210            #[cfg(feature = "sha256")]
211            Kind::Sha256 => &self.bytes == oid::empty_tree_sha256().as_bytes(),
212        }
213    }
214}
215
216/// Methods for creating special-case `oid`s (null, empty blob, empty tree)
217impl oid {
218    /// Returns a SHA1 digest with all bytes being initialized to zero.
219    #[inline]
220    #[cfg(feature = "sha1")]
221    pub(crate) fn null_sha1() -> &'static Self {
222        oid::from_bytes([0u8; SIZE_OF_SHA1_DIGEST].as_ref())
223    }
224
225    /// Returns a SHA256 digest with all bytes being initialized to zero.
226    #[inline]
227    #[cfg(feature = "sha256")]
228    pub(crate) fn null_sha256() -> &'static Self {
229        oid::from_bytes([0u8; SIZE_OF_SHA256_DIGEST].as_ref())
230    }
231
232    /// Returns an `oid` representing the SHA1 hash of an empty blob.
233    #[inline]
234    #[cfg(feature = "sha1")]
235    pub(crate) fn empty_blob_sha1() -> &'static Self {
236        oid::from_bytes(EMPTY_BLOB_SHA1)
237    }
238
239    /// Returns an `oid` representing the SHA256 hash of an empty blob.
240    #[inline]
241    #[cfg(feature = "sha256")]
242    pub(crate) fn empty_blob_sha256() -> &'static Self {
243        oid::from_bytes(EMPTY_BLOB_SHA256)
244    }
245
246    /// Returns an `oid` representing the SHA1 hash of an empty tree.
247    #[inline]
248    #[cfg(feature = "sha1")]
249    pub(crate) fn empty_tree_sha1() -> &'static Self {
250        oid::from_bytes(EMPTY_TREE_SHA1)
251    }
252
253    /// Returns an `oid` representing the SHA256 hash of an empty tree.
254    #[inline]
255    #[cfg(feature = "sha256")]
256    pub(crate) fn empty_tree_sha256() -> &'static Self {
257        oid::from_bytes(EMPTY_TREE_SHA256)
258    }
259}
260
261impl AsRef<oid> for &oid {
262    fn as_ref(&self) -> &oid {
263        self
264    }
265}
266
267impl<'a> TryFrom<&'a [u8]> for &'a oid {
268    type Error = Error;
269
270    fn try_from(value: &'a [u8]) -> Result<Self, Self::Error> {
271        oid::try_from_bytes(value)
272    }
273}
274
275impl ToOwned for oid {
276    type Owned = ObjectId;
277
278    fn to_owned(&self) -> Self::Owned {
279        match self.kind() {
280            #[cfg(feature = "sha1")]
281            Kind::Sha1 => ObjectId::Sha1(self.bytes.try_into().expect("no bug in hash detection")),
282            #[cfg(feature = "sha256")]
283            Kind::Sha256 => ObjectId::Sha256(self.bytes.try_into().expect("no bug in hash detection")),
284        }
285    }
286}
287
288#[cfg(feature = "sha1")]
289impl<'a> From<&'a [u8; SIZE_OF_SHA1_DIGEST]> for &'a oid {
290    fn from(v: &'a [u8; SIZE_OF_SHA1_DIGEST]) -> Self {
291        oid::from_bytes(v.as_ref())
292    }
293}
294
295#[cfg(feature = "sha256")]
296impl<'a> From<&'a [u8; SIZE_OF_SHA256_DIGEST]> for &'a oid {
297    fn from(v: &'a [u8; SIZE_OF_SHA256_DIGEST]) -> Self {
298        oid::from_bytes(v.as_ref())
299    }
300}
301
302impl std::fmt::Display for &oid {
303    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
304        let mut buf = Kind::hex_buf();
305        f.write_str(self.hex_to_buf(&mut buf))
306    }
307}
308
309impl PartialEq<ObjectId> for &oid {
310    fn eq(&self, other: &ObjectId) -> bool {
311        *self == other.as_ref()
312    }
313}
314
315/// Manually created from a version that uses a slice, and we forcefully try to convert it into a borrowed array of the desired size
316/// Could be improved by fitting this into serde.
317/// Unfortunately the `serde::Deserialize` derive wouldn't work for borrowed arrays.
318#[cfg(feature = "serde")]
319impl<'de: 'a, 'a> serde::Deserialize<'de> for &'a oid {
320    fn deserialize<D>(deserializer: D) -> Result<Self, <D as serde::Deserializer<'de>>::Error>
321    where
322        D: serde::Deserializer<'de>,
323    {
324        struct __Visitor<'de: 'a, 'a> {
325            marker: std::marker::PhantomData<&'a oid>,
326            lifetime: std::marker::PhantomData<&'de ()>,
327        }
328        impl<'de: 'a, 'a> serde::de::Visitor<'de> for __Visitor<'de, 'a> {
329            type Value = &'a oid;
330            fn expecting(&self, __formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
331                std::fmt::Formatter::write_str(__formatter, "tuple struct Digest")
332            }
333            #[inline]
334            fn visit_newtype_struct<__E>(self, __e: __E) -> std::result::Result<Self::Value, __E::Error>
335            where
336                __E: serde::Deserializer<'de>,
337            {
338                let __field0: &'a [u8] = match <&'a [u8] as serde::Deserialize>::deserialize(__e) {
339                    Ok(__val) => __val,
340                    Err(__err) => {
341                        return Err(__err);
342                    }
343                };
344                Ok(oid::try_from_bytes(__field0).expect("hash of known length"))
345            }
346            #[inline]
347            fn visit_seq<__A>(self, mut __seq: __A) -> std::result::Result<Self::Value, __A::Error>
348            where
349                __A: serde::de::SeqAccess<'de>,
350            {
351                let __field0 = match match serde::de::SeqAccess::next_element::<&'a [u8]>(&mut __seq) {
352                    Ok(__val) => __val,
353                    Err(__err) => {
354                        return Err(__err);
355                    }
356                } {
357                    Some(__value) => __value,
358                    None => {
359                        return Err(serde::de::Error::invalid_length(
360                            0usize,
361                            &"tuple struct Digest with 1 element",
362                        ));
363                    }
364                };
365                Ok(oid::try_from_bytes(__field0).expect("hash of known length"))
366            }
367        }
368        serde::Deserializer::deserialize_newtype_struct(
369            deserializer,
370            "Digest",
371            __Visitor {
372                marker: std::marker::PhantomData::<&'a oid>,
373                lifetime: std::marker::PhantomData,
374            },
375        )
376    }
377}
gix_hash/oid.rs

gix_hash/
oid.rs
