scolapasta_hex/
lib.rs

1#![warn(clippy::all, clippy::pedantic, clippy::undocumented_unsafe_blocks)]
2#![allow(
3    clippy::let_underscore_untyped,
4    reason = "https://github.com/rust-lang/rust-clippy/pull/10442#issuecomment-1516570154"
5)]
6#![allow(
7    clippy::question_mark,
8    reason = "https://github.com/rust-lang/rust-clippy/issues/8281"
9)]
10#![allow(clippy::manual_let_else, reason = "manual_let_else was very buggy on release")]
11#![allow(clippy::missing_errors_doc, reason = "A lot of existing code fails this lint")]
12#![allow(
13    clippy::unnecessary_lazy_evaluations,
14    reason = "https://github.com/rust-lang/rust-clippy/issues/8109"
15)]
16#![cfg_attr(
17    test,
18    allow(clippy::non_ascii_literal, reason = "tests sometimes require UTF-8 string content")
19)]
20#![allow(unknown_lints)]
21#![warn(
22    missing_copy_implementations,
23    missing_debug_implementations,
24    missing_docs,
25    rust_2024_compatibility,
26    trivial_casts,
27    trivial_numeric_casts,
28    unused_qualifications,
29    variant_size_differences
30)]
31#![forbid(unsafe_code)]
32// Enable feature callouts in generated documentation:
33// https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html
34//
35// This approach is borrowed from tokio.
36#![cfg_attr(docsrs, feature(doc_cfg))]
37#![cfg_attr(docsrs, feature(doc_alias))]
38
39//! Functions for encoding sequences of bytes into base 16 hex encoding.
40//!
41//! [Base 16 encoding] is an encoding scheme that uses a 16 character ASCII
42//! alphabet for encoding arbitrary octets.
43//!
44//! This crate offers encoders that:
45//!
46//! - Allocate and return a [`String`]: [`try_encode`].
47//! - Encode into an already allocated [`String`]: [`try_encode_into`].
48//! - Encode into a [`core::fmt::Write`]: [`format_into`].
49//! - Encode into a [`std::io::Write`]: [`write_into`].
50//!
51//! # Examples
52//!
53//! ```
54//! # #[cfg(feature = "alloc")]
55//! # extern crate alloc;
56//! # #[cfg(feature = "alloc")]
57//! # use alloc::collections::TryReserveError;
58//! # #[cfg(feature = "alloc")]
59//! # fn example() -> Result<(), TryReserveError> {
60//! let data = b"Artichoke Ruby";
61//! let mut buf = String::new();
62//! scolapasta_hex::try_encode_into(data, &mut buf)?;
63//! assert_eq!(buf, "4172746963686f6b652052756279");
64//! # Ok(())
65//! # }
66//! # #[cfg(feature = "alloc")]
67//! # example().unwrap()
68//! ```
69//!
70//! This module also exposes an iterator:
71//!
72//! ```
73//! use scolapasta_hex::Hex;
74//!
75//! let data = "Artichoke Ruby";
76//! let iter = Hex::from(data);
77//! assert_eq!(iter.collect::<String>(), "4172746963686f6b652052756279");
78//! ```
79//!
80//! # `no_std`
81//!
82//! This crate is `no_std` compatible when built without the `std` feature. This
83//! crate optionally depends on [`alloc`] when the `alloc` feature is enabled.
84//!
85//! When this crate depends on `alloc`, it exclusively uses fallible allocation
86//! APIs. The APIs in this crate will never abort due to allocation failure or
87//! capacity overflows. Note that writers given to [`format_into`] and
88//! [`write_into`] may have abort on allocation failure behavior.
89//!
90//! # Crate features
91//!
92//! All features are enabled by default.
93//!
94//! - **std** - Enables a dependency on the Rust Standard Library. Activating
95//!   this feature enables APIs that require [`std::io::Write`]. Activating this
96//!   feature also activates the **alloc** feature.
97//! - **alloc** - Enables a dependency on the Rust [`alloc`] crate. Activating
98//!   this feature enables APIs that require [`alloc::string::String`].
99//!
100#![cfg_attr(
101    not(feature = "std"),
102    doc = "[`std::io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html"
103)]
104#![cfg_attr(
105    not(feature = "std"),
106    doc = "[`write_into`]: https://artichoke.github.io/artichoke/scolapasta_hex/fn.write_into.html"
107)]
108//! [Base 16 encoding]: https://tools.ietf.org/html/rfc4648#section-8
109
110#![no_std]
111
112// Ensure code blocks in `README.md` compile
113#[cfg(all(doctest, feature = "alloc"))]
114#[doc = include_str!("../README.md")]
115mod readme {}
116
117#[cfg(feature = "alloc")]
118extern crate alloc;
119// Having access to `String` in tests is convenient to collect `Inspect`
120// iterators for whole content comparisons.
121#[cfg(any(feature = "std", test, doctest))]
122extern crate std;
123
124#[cfg(feature = "alloc")]
125use alloc::collections::TryReserveError;
126#[cfg(feature = "alloc")]
127use alloc::string::String;
128use core::fmt;
129use core::iter::FusedIterator;
130use core::slice;
131use core::str::Chars;
132#[cfg(feature = "std")]
133use std::io;
134
135/// Encode arbitrary octets as base16. Returns a [`String`].
136///
137/// This function allocates an empty [`String`] and delegates to
138/// [`try_encode_into`].
139///
140/// # Errors
141///
142/// If the allocated string's capacity overflows, or the allocator reports a
143/// failure, then an error is returned.
144///
145/// # Examples
146///
147/// ```
148/// # extern crate alloc;
149/// # use alloc::collections::TryReserveError;
150/// # fn example() -> Result<(), TryReserveError> {
151/// let data = b"Artichoke Ruby";
152/// let buf = scolapasta_hex::try_encode(data)?;
153/// assert_eq!(buf, "4172746963686f6b652052756279");
154/// # Ok(())
155/// # }
156/// # example().unwrap()
157/// ```
158#[inline]
159#[cfg(feature = "alloc")]
160#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
161pub fn try_encode<T: AsRef<[u8]>>(data: T) -> Result<String, TryReserveError> {
162    let mut buf = String::new();
163    try_encode_into(data.as_ref(), &mut buf)?;
164    Ok(buf)
165}
166
167/// Encode arbitrary octets as base16 into the given [`String`].
168///
169/// This function writes encoded octets into the given `String`. This function
170/// will allocate at most once.
171///
172/// # Errors
173///
174/// If the given string's capacity overflows, or the allocator reports a
175/// failure, then an error is returned.
176///
177/// # Examples
178///
179/// ```
180/// # extern crate alloc;
181/// # use alloc::collections::TryReserveError;
182/// # use alloc::string::String;
183/// # fn example() -> Result<(), TryReserveError> {
184/// let data = b"Artichoke Ruby";
185/// let mut buf = String::new();
186/// scolapasta_hex::try_encode_into(data, &mut buf)?;
187/// assert_eq!(buf, "4172746963686f6b652052756279");
188/// # Ok(())
189/// # }
190/// # example().unwrap()
191/// ```
192#[inline]
193#[cfg(feature = "alloc")]
194#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
195pub fn try_encode_into<T: AsRef<[u8]>>(data: T, buf: &mut String) -> Result<(), TryReserveError> {
196    let data = data.as_ref();
197    let iter = Hex::from(data);
198    buf.try_reserve(iter.len())?;
199    buf.extend(iter);
200    Ok(())
201}
202
203/// Write hex-encoded octets into the given [`fmt::Write`].
204///
205/// This function writes UTF-8 encoded octets into the given writer. This
206/// function does not allocate, but the given writer may.
207///
208/// # Examples
209///
210/// ```
211/// # extern crate alloc;
212/// # use alloc::string::String;
213/// let data = b"Artichoke Ruby";
214/// let mut buf = String::new();
215/// scolapasta_hex::format_into(data, &mut buf);
216/// assert_eq!(buf, "4172746963686f6b652052756279");
217/// ```
218///
219/// # Errors
220///
221/// If the formatter returns an error, that error is returned.
222#[inline]
223pub fn format_into<T, W>(data: T, mut f: W) -> fmt::Result
224where
225    T: AsRef<[u8]>,
226    W: fmt::Write,
227{
228    let data = data.as_ref();
229    let iter = Hex::from(data);
230    let mut enc = [0; 4];
231    for ch in iter {
232        let escaped = ch.encode_utf8(&mut enc);
233        f.write_str(escaped)?;
234    }
235    Ok(())
236}
237
238/// Write hex-encoded octets into the given [`io::Write`].
239///
240/// This function writes UTF-8 encoded octets into the given writer. This
241/// function does not allocate, but the given writer may.
242///
243/// # Examples
244///
245/// ```
246/// # extern crate alloc;
247/// # use alloc::vec::Vec;
248/// let data = b"Artichoke Ruby";
249/// let mut buf = Vec::new();
250/// scolapasta_hex::write_into(data, &mut buf);
251/// assert_eq!(buf, b"4172746963686f6b652052756279".to_vec());
252/// ```
253///
254/// # Errors
255///
256/// If the destination returns an error, that error is returned.
257#[inline]
258#[cfg(feature = "std")]
259#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
260pub fn write_into<T, W>(data: T, mut dest: W) -> io::Result<()>
261where
262    T: AsRef<[u8]>,
263    W: io::Write,
264{
265    let data = data.as_ref();
266    let iter = Hex::from(data);
267    let mut enc = [0; 4];
268    for ch in iter {
269        let escaped = ch.encode_utf8(&mut enc);
270        dest.write_all(escaped.as_bytes())?;
271    }
272    Ok(())
273}
274
275/// An iterator over a byte slice that returns the data as a sequence of hex
276/// encoded [`char`]s.
277///
278/// # Examples
279///
280/// ```
281/// use scolapasta_hex::Hex;
282///
283/// let data = "Artichoke Ruby";
284/// let iter = Hex::from(data);
285/// assert_eq!(iter.collect::<String>(), "4172746963686f6b652052756279");
286/// ```
287#[derive(Debug, Clone)]
288pub struct Hex<'a> {
289    iter: slice::Iter<'a, u8>,
290    escaped_byte: Option<EscapedByte>,
291}
292
293impl Hex<'_> {
294    /// Returns the number of remaining hex encoded characters in the iterator.
295    ///
296    /// # Examples
297    ///
298    /// ```
299    /// use scolapasta_hex::Hex;
300    ///
301    /// let iter = Hex::from("");
302    /// assert_eq!(iter.len(), 0);
303    ///
304    /// let mut iter = Hex::from("a");
305    /// assert_eq!(iter.len(), 2);
306    /// assert_eq!(iter.next(), Some('6'));
307    /// assert_eq!(iter.len(), 1);
308    /// assert_eq!(iter.next(), Some('1'));
309    /// assert_eq!(iter.len(), 0);
310    /// assert_eq!(iter.next(), None);
311    /// assert_eq!(iter.len(), 0);
312    /// ```
313    #[inline]
314    #[must_use]
315    pub fn len(&self) -> usize {
316        let remaining_bytes = self.iter.as_slice().len();
317        // Every byte expands to two hexadecimal ASCII `char`s.
318        let remaining_bytes_encoded_len = remaining_bytes.saturating_mul(2);
319        if let Some(ref escaped_byte) = self.escaped_byte {
320            // Add the dangling char(s) from the `EscapedByte` iterator.
321            remaining_bytes_encoded_len.saturating_add(escaped_byte.len())
322        } else {
323            remaining_bytes_encoded_len
324        }
325    }
326
327    /// Returns whether the iterator has no more remaining escape codes.
328    ///
329    /// # Examples
330    ///
331    /// ```
332    /// use scolapasta_hex::Hex;
333    ///
334    /// let iter = Hex::from("");
335    /// assert!(iter.is_empty());
336    ///
337    /// let mut iter = Hex::from("a");
338    /// assert!(!iter.is_empty());
339    /// assert_eq!(iter.next(), Some('6'));
340    /// assert!(!iter.is_empty());
341    /// assert_eq!(iter.next(), Some('1'));
342    /// assert!(iter.is_empty());
343    /// assert_eq!(iter.next(), None);
344    /// assert!(iter.is_empty());
345    /// ```
346    #[inline]
347    #[must_use]
348    pub fn is_empty(&self) -> bool {
349        if let Some(ref escaped_byte) = self.escaped_byte {
350            self.iter.as_slice().is_empty() && escaped_byte.is_empty()
351        } else {
352            self.iter.as_slice().is_empty()
353        }
354    }
355}
356
357impl<'a> From<&'a str> for Hex<'a> {
358    #[inline]
359    fn from(data: &'a str) -> Self {
360        Self::from(data.as_bytes())
361    }
362}
363
364impl<'a> From<&'a [u8]> for Hex<'a> {
365    #[inline]
366    fn from(data: &'a [u8]) -> Self {
367        Self {
368            iter: data.iter(),
369            escaped_byte: None,
370        }
371    }
372}
373
374impl<'a, const N: usize> From<&'a [u8; N]> for Hex<'a> {
375    #[inline]
376    fn from(data: &'a [u8; N]) -> Self {
377        Self {
378            iter: data.iter(),
379            escaped_byte: None,
380        }
381    }
382}
383
384impl Iterator for Hex<'_> {
385    type Item = char;
386
387    #[inline]
388    fn next(&mut self) -> Option<Self::Item> {
389        if let Some(ref mut escaped) = self.escaped_byte {
390            let next = escaped.next();
391            if next.is_some() {
392                return next;
393            }
394        }
395        let byte = self.iter.next().copied()?;
396        let mut escaped = EscapedByte::from(byte);
397        let next = escaped.next()?;
398        self.escaped_byte = Some(escaped);
399        Some(next)
400    }
401
402    #[inline]
403    fn count(self) -> usize {
404        self.len()
405    }
406
407    #[inline]
408    fn size_hint(&self) -> (usize, Option<usize>) {
409        let size = self.len();
410        (size, Some(size))
411    }
412
413    #[inline]
414    fn last(self) -> Option<Self::Item> {
415        let byte = self.iter.last().copied()?;
416        let escaped = EscapedByte::from(byte);
417        escaped.last()
418    }
419}
420
421impl FusedIterator for Hex<'_> {}
422
423impl ExactSizeIterator for Hex<'_> {}
424
425/// Map from a `u8` to a hex encoded string literal.
426///
427/// # Examples
428///
429/// ```
430/// assert_eq!(scolapasta_hex::escape_byte(0), "00");
431/// assert_eq!(scolapasta_hex::escape_byte(0x20), "20");
432/// assert_eq!(scolapasta_hex::escape_byte(255), "ff");
433/// ```
434#[inline]
435#[must_use]
436pub const fn escape_byte(byte: u8) -> &'static str {
437    EscapedByte::hex_escape(byte)
438}
439
440#[derive(Debug, Clone)]
441#[must_use = "this `EscapedByte` is an `Iterator`, which should be consumed if constructed"]
442struct EscapedByte(Chars<'static>);
443
444impl EscapedByte {
445    /// Views the underlying data as a subslice of the original data.
446    ///
447    /// This has `'static` lifetime, and so the iterator can continue to be used
448    /// while this exists.
449    #[inline]
450    #[must_use]
451    pub fn as_str(&self) -> &'static str {
452        self.0.as_str()
453    }
454
455    #[inline]
456    #[must_use]
457    pub fn len(&self) -> usize {
458        self.as_str().len()
459    }
460
461    #[inline]
462    #[must_use]
463    pub fn is_empty(&self) -> bool {
464        self.as_str().is_empty()
465    }
466
467    /// Map from a `u8` to a hex encoded string literal.
468    ///
469    /// For example, `00`, `20` or `ff`.
470    const fn hex_escape(value: u8) -> &'static str {
471        // Use a lookup table, generated with:
472        //
473        // ```ruby
474        // puts "const TABLE: [&str; 256] = [" + (0x00..0xFF).to_a.map {|b| b.to_s(16).rjust(2, "0").inspect}.join(", ") + "];"
475        // ```
476        #[rustfmt::skip]
477        const TABLE: [&str; 256] = [
478            "00", "01", "02", "03", "04", "05", "06", "07", "08", "09", "0a", "0b", "0c", "0d", "0e", "0f",
479            "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "1a", "1b", "1c", "1d", "1e", "1f",
480            "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "2a", "2b", "2c", "2d", "2e", "2f",
481            "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "3a", "3b", "3c", "3d", "3e", "3f",
482            "40", "41", "42", "43", "44", "45", "46", "47", "48", "49", "4a", "4b", "4c", "4d", "4e", "4f",
483            "50", "51", "52", "53", "54", "55", "56", "57", "58", "59", "5a", "5b", "5c", "5d", "5e", "5f",
484            "60", "61", "62", "63", "64", "65", "66", "67", "68", "69", "6a", "6b", "6c", "6d", "6e", "6f",
485            "70", "71", "72", "73", "74", "75", "76", "77", "78", "79", "7a", "7b", "7c", "7d", "7e", "7f",
486            "80", "81", "82", "83", "84", "85", "86", "87", "88", "89", "8a", "8b", "8c", "8d", "8e", "8f",
487            "90", "91", "92", "93", "94", "95", "96", "97", "98", "99", "9a", "9b", "9c", "9d", "9e", "9f",
488            "a0", "a1", "a2", "a3", "a4", "a5", "a6", "a7", "a8", "a9", "aa", "ab", "ac", "ad", "ae", "af",
489            "b0", "b1", "b2", "b3", "b4", "b5", "b6", "b7", "b8", "b9", "ba", "bb", "bc", "bd", "be", "bf",
490            "c0", "c1", "c2", "c3", "c4", "c5", "c6", "c7", "c8", "c9", "ca", "cb", "cc", "cd", "ce", "cf",
491            "d0", "d1", "d2", "d3", "d4", "d5", "d6", "d7", "d8", "d9", "da", "db", "dc", "dd", "de", "df",
492            "e0", "e1", "e2", "e3", "e4", "e5", "e6", "e7", "e8", "e9", "ea", "eb", "ec", "ed", "ee", "ef",
493            "f0", "f1", "f2", "f3", "f4", "f5", "f6", "f7", "f8", "f9", "fa", "fb", "fc", "fd", "fe", "ff",
494        ];
495
496        TABLE[value as usize]
497    }
498}
499
500impl From<u8> for EscapedByte {
501    #[inline]
502    fn from(byte: u8) -> Self {
503        let escape = Self::hex_escape(byte);
504        Self(escape.chars())
505    }
506}
507
508impl Iterator for EscapedByte {
509    type Item = char;
510
511    #[inline]
512    fn next(&mut self) -> Option<Self::Item> {
513        self.0.next()
514    }
515
516    #[inline]
517    fn nth(&mut self, n: usize) -> Option<Self::Item> {
518        self.0.nth(n)
519    }
520
521    #[inline]
522    fn count(self) -> usize {
523        self.0.count()
524    }
525
526    #[inline]
527    fn size_hint(&self) -> (usize, Option<usize>) {
528        self.0.size_hint()
529    }
530
531    #[inline]
532    fn last(self) -> Option<Self::Item> {
533        self.0.last()
534    }
535}
536
537impl DoubleEndedIterator for EscapedByte {
538    #[inline]
539    fn next_back(&mut self) -> Option<Self::Item> {
540        self.0.next_back()
541    }
542
543    #[inline]
544    fn nth_back(&mut self, n: usize) -> Option<Self::Item> {
545        self.0.nth_back(n)
546    }
547}
548
549impl FusedIterator for EscapedByte {}
550
551#[cfg(test)]
552mod tests;
scolapasta_hex/lib.rs

scolapasta_hex/
lib.rs
