gix_hash/
oid.rs

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

gix_hash/
oid.rs
