tina-core 0.0.2

#![allow(dead_code)]
pub(crate) mod de {
    use std::borrow::Cow;

    use serde::de::{self, Deserializer, Error as DeError, Visitor};
    use serde::forward_to_deserialize_any;

    use super::inner::{Path, PathIter};
    use super::{quoter::Quoter, resource_path::ResourcePath};

    thread_local! {
        static FULL_QUOTER: Quoter = Quoter::new(b"+/%", b"");
    }

    macro_rules! unsupported_type {
        ($trait_fn:ident, $name:expr) => {
            fn $trait_fn<V>(self, _: V) -> Result<V::Value, Self::Error>
            where
                V: Visitor<'de>,
            {
                Err(de::Error::custom(concat!("unsupported type: ", $name)))
            }
        };
    }

    macro_rules! parse_single_value {
        ($trait_fn:ident) => {
            fn $trait_fn<V>(self, visitor: V) -> Result<V::Value, Self::Error>
            where
                V: Visitor<'de>,
            {
                if self.path.segment_count() != 1 {
                    Err(de::value::Error::custom(format!("wrong number of parameters: {} expected 1", self.path.segment_count()).as_str()))
                } else {
                    Value {
                        value: &self.path[0],
                    }
                    .$trait_fn(visitor)
                }
            }
        };
    }

    macro_rules! parse_value {
        ($trait_fn:ident, $visit_fn:ident, $tp:tt) => {
            fn $trait_fn<V>(self, visitor: V) -> Result<V::Value, Self::Error>
            where
                V: Visitor<'de>,
            {
                let decoded = FULL_QUOTER.with(|q| q.requote_str_lossy(self.value)).map(Cow::Owned).unwrap_or(Cow::Borrowed(self.value));

                let v = decoded.parse().map_err(|_| de::value::Error::custom(format!("can not parse {:?} to a {}", self.value, $tp)))?;

                visitor.$visit_fn(v)
            }
        };
    }

    pub struct PathDeserializer<'de, T: ResourcePath> {
        path: &'de Path<'de, T>,
    }

    impl<'de, T: ResourcePath + 'de> PathDeserializer<'de, T> {
        pub fn new(path: &'de Path<'de, T>) -> Self {
            PathDeserializer {
                path,
            }
        }
    }

    impl<'de, T: ResourcePath + 'de> Deserializer<'de> for PathDeserializer<'de, T> {
        type Error = de::value::Error;

        fn deserialize_map<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_map(ParamsDeserializer {
                params: self.path.iter(),
                current: None,
            })
        }

        fn deserialize_struct<V>(self, _: &str, _: &'static [&str], visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            self.deserialize_map(visitor)
        }

        fn deserialize_unit<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_unit()
        }

        fn deserialize_unit_struct<V>(self, _: &str, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            self.deserialize_unit(visitor)
        }

        fn deserialize_newtype_struct<V>(self, _: &str, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_newtype_struct(self)
        }

        fn deserialize_tuple<V>(self, len: usize, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            if self.path.segment_count() < len {
                Err(de::value::Error::custom(
                    format!("wrong number of parameters: {} expected {}", self.path.segment_count(), len).as_str(),
                ))
            } else {
                visitor.visit_seq(ParamsSeq {
                    params: self.path.iter(),
                })
            }
        }

        fn deserialize_tuple_struct<V>(self, _: &str, len: usize, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            if self.path.segment_count() < len {
                Err(de::value::Error::custom(
                    format!("wrong number of parameters: {} expected {}", self.path.segment_count(), len).as_str(),
                ))
            } else {
                visitor.visit_seq(ParamsSeq {
                    params: self.path.iter(),
                })
            }
        }

        fn deserialize_enum<V>(self, _: &str, _: &'static [&str], visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            if self.path.is_empty() {
                Err(de::value::Error::custom("expected at least one parameters"))
            } else {
                visitor.visit_enum(ValueEnum {
                    value: &self.path[0],
                })
            }
        }

        fn deserialize_seq<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_seq(ParamsSeq {
                params: self.path.iter(),
            })
        }

        unsupported_type!(deserialize_any, "'any'");
        unsupported_type!(deserialize_option, "Option<T>");
        unsupported_type!(deserialize_identifier, "identifier");
        unsupported_type!(deserialize_ignored_any, "ignored_any");

        parse_single_value!(deserialize_bool);
        parse_single_value!(deserialize_i8);
        parse_single_value!(deserialize_i16);
        parse_single_value!(deserialize_i32);
        parse_single_value!(deserialize_i64);
        parse_single_value!(deserialize_u8);
        parse_single_value!(deserialize_u16);
        parse_single_value!(deserialize_u32);
        parse_single_value!(deserialize_u64);
        parse_single_value!(deserialize_f32);
        parse_single_value!(deserialize_f64);
        parse_single_value!(deserialize_str);
        parse_single_value!(deserialize_string);
        parse_single_value!(deserialize_bytes);
        parse_single_value!(deserialize_byte_buf);
        parse_single_value!(deserialize_char);
    }

    struct ParamsDeserializer<'de, T: ResourcePath> {
        params: PathIter<'de, T>,
        current: Option<(&'de str, &'de str)>,
    }

    impl<'de, T: ResourcePath> de::MapAccess<'de> for ParamsDeserializer<'de, T> {
        type Error = de::value::Error;

        fn next_key_seed<K>(&mut self, seed: K) -> Result<Option<K::Value>, Self::Error>
        where
            K: de::DeserializeSeed<'de>,
        {
            self.current = self.params.next().map(|ref item| (item.0, item.1));
            match self.current {
                Some((key, _)) => Ok(Some(seed.deserialize(Key {
                    key,
                })?)),
                None => Ok(None),
            }
        }

        fn next_value_seed<V>(&mut self, seed: V) -> Result<V::Value, Self::Error>
        where
            V: de::DeserializeSeed<'de>,
        {
            if let Some((_, value)) = self.current.take() {
                seed.deserialize(Value {
                    value,
                })
            } else {
                Err(de::value::Error::custom("unexpected item"))
            }
        }
    }

    struct Key<'de> {
        key: &'de str,
    }

    impl<'de> Deserializer<'de> for Key<'de> {
        type Error = de::value::Error;

        fn deserialize_identifier<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_str(self.key)
        }

        fn deserialize_any<V>(self, _visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            Err(de::value::Error::custom("Unexpected"))
        }

        forward_to_deserialize_any! {
            bool i8 i16 i32 i64 u8 u16 u32 u64 f32 f64 char str string bytes
                byte_buf option unit unit_struct newtype_struct seq tuple
                tuple_struct map struct enum ignored_any
        }
    }

    struct Value<'de> {
        value: &'de str,
    }

    impl<'de> Deserializer<'de> for Value<'de> {
        type Error = de::value::Error;

        parse_value!(deserialize_bool, visit_bool, "bool");
        parse_value!(deserialize_i8, visit_i8, "i8");
        parse_value!(deserialize_i16, visit_i16, "i16");
        parse_value!(deserialize_i32, visit_i32, "i16");
        parse_value!(deserialize_i64, visit_i64, "i64");
        parse_value!(deserialize_u8, visit_u8, "u8");
        parse_value!(deserialize_u16, visit_u16, "u16");
        parse_value!(deserialize_u32, visit_u32, "u32");
        parse_value!(deserialize_u64, visit_u64, "u64");
        parse_value!(deserialize_f32, visit_f32, "f32");
        parse_value!(deserialize_f64, visit_f64, "f64");
        parse_value!(deserialize_char, visit_char, "char");

        fn deserialize_ignored_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_unit()
        }

        fn deserialize_unit<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_unit()
        }

        fn deserialize_unit_struct<V>(self, _: &str, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_unit()
        }

        fn deserialize_str<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            match FULL_QUOTER.with(|q| q.requote_str_lossy(self.value)) {
                Some(s) => visitor.visit_string(s),
                None => visitor.visit_borrowed_str(self.value),
            }
        }

        fn deserialize_bytes<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            match FULL_QUOTER.with(|q| q.requote_str_lossy(self.value)) {
                Some(s) => visitor.visit_byte_buf(s.into()),
                None => visitor.visit_borrowed_bytes(self.value.as_bytes()),
            }
        }

        fn deserialize_byte_buf<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            self.deserialize_bytes(visitor)
        }

        fn deserialize_string<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            self.deserialize_str(visitor)
        }

        fn deserialize_option<V>(self, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_some(self)
        }

        fn deserialize_enum<V>(self, _: &str, _: &'static [&str], visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_enum(ValueEnum {
                value: self.value,
            })
        }

        fn deserialize_newtype_struct<V>(self, _: &str, visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            visitor.visit_newtype_struct(self)
        }

        fn deserialize_tuple<V>(self, _: usize, _: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            Err(de::value::Error::custom("unsupported type: tuple"))
        }

        fn deserialize_struct<V>(self, _: &str, _: &'static [&str], _: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            Err(de::value::Error::custom("unsupported type: struct"))
        }

        fn deserialize_tuple_struct<V>(self, _: &str, _: usize, _: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            Err(de::value::Error::custom("unsupported type: tuple struct"))
        }

        unsupported_type!(deserialize_any, "any");
        unsupported_type!(deserialize_seq, "seq");
        unsupported_type!(deserialize_map, "map");
        unsupported_type!(deserialize_identifier, "identifier");
    }

    struct ParamsSeq<'de, T: ResourcePath> {
        params: PathIter<'de, T>,
    }

    impl<'de, T: ResourcePath> de::SeqAccess<'de> for ParamsSeq<'de, T> {
        type Error = de::value::Error;

        fn next_element_seed<U>(&mut self, seed: U) -> Result<Option<U::Value>, Self::Error>
        where
            U: de::DeserializeSeed<'de>,
        {
            match self.params.next() {
                Some(item) => Ok(Some(seed.deserialize(Value {
                    value: item.1,
                })?)),
                None => Ok(None),
            }
        }
    }

    struct ValueEnum<'de> {
        value: &'de str,
    }

    impl<'de> de::EnumAccess<'de> for ValueEnum<'de> {
        type Error = de::value::Error;
        type Variant = UnitVariant;

        fn variant_seed<V>(self, seed: V) -> Result<(V::Value, Self::Variant), Self::Error>
        where
            V: de::DeserializeSeed<'de>,
        {
            Ok((
                seed.deserialize(Key {
                    key: self.value,
                })?,
                UnitVariant,
            ))
        }
    }

    struct UnitVariant;

    impl<'de> de::VariantAccess<'de> for UnitVariant {
        type Error = de::value::Error;

        fn unit_variant(self) -> Result<(), Self::Error> {
            Ok(())
        }

        fn newtype_variant_seed<T>(self, _seed: T) -> Result<T::Value, Self::Error>
        where
            T: de::DeserializeSeed<'de>,
        {
            Err(de::value::Error::custom("not supported"))
        }

        fn tuple_variant<V>(self, _len: usize, _visitor: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            Err(de::value::Error::custom("not supported"))
        }

        fn struct_variant<V>(self, _: &'static [&str], _: V) -> Result<V::Value, Self::Error>
        where
            V: Visitor<'de>,
        {
            Err(de::value::Error::custom("not supported"))
        }
    }
}

mod resource_path {
    use crate::tina::server::http::path::inner::Path;

    pub trait Resource<'a> {
        /// Type of resource's path returned in `resource_path`.
        type Path: ResourcePath;

        fn resource_path(&mut self) -> &mut Path<'a, Self::Path>;
    }

    pub trait ResourcePath {
        fn path(&self) -> &str;
    }

    impl ResourcePath for String {
        fn path(&self) -> &str {
            self.as_str()
        }
    }

    impl<'a> ResourcePath for &'a str {
        fn path(&self) -> &str {
            self
        }
    }

    impl ResourcePath for bytestring::ByteString {
        fn path(&self) -> &str {
            self
        }
    }

    impl ResourcePath for http::Uri {
        fn path(&self) -> &str {
            http::Uri::path(self)
        }
    }

    impl ResourcePath for &http::Uri {
        fn path(&self) -> &str {
            http::Uri::path(self)
        }
    }
}

pub(crate) mod inner {
    use std::borrow::Cow;
    use std::ops::{DerefMut, Index};

    use firestorm::profile_method;
    use serde::de;

    use super::{de::PathDeserializer, resource_path::Resource, resource_path::ResourcePath};

    #[derive(Debug, Clone)]
    pub(crate) enum PathItem<'a> {
        Borrowed(Cow<'a, str>),
        Segment(u16, u16),
    }

    impl<'a> Default for PathItem<'a> {
        fn default() -> Self {
            Self::Borrowed(Cow::Borrowed(""))
        }
    }

    /// Resource path match information.
    ///
    /// If resource path contains variable patterns, `Path` stores them.
    #[derive(Debug, Clone, Default)]
    pub struct Path<'a, T> {
        path: T,
        pub(crate) skip: u16,
        pub(crate) segments: Vec<(Cow<'a, str>, PathItem<'a>)>,
    }

    impl<'a, T: ResourcePath> Path<'a, T> {
        pub fn new(path: T) -> Path<'a, T> {
            Path {
                path,
                skip: 0,
                segments: Vec::new(),
            }
        }

        /// Returns reference to inner path instance.
        #[inline]
        pub fn get_ref(&self) -> &T {
            &self.path
        }

        /// Returns mutable reference to inner path instance.
        #[inline]
        pub fn get_mut(&mut self) -> &mut T {
            &mut self.path
        }

        /// Returns full path as a string.
        #[inline]
        pub fn as_str(&self) -> &str {
            profile_method!(as_str);
            self.path.path()
        }

        /// Returns unprocessed part of the path.
        ///
        /// Returns empty string if no more is to be processed.
        #[inline]
        pub fn unprocessed(&self) -> &str {
            profile_method!(unprocessed);
            // clamp skip to path length
            let skip = (self.skip as usize).min(self.as_str().len());
            &self.path.path()[skip..]
        }

        /// Returns unprocessed part of the path.
        #[doc(hidden)]
        #[deprecated(since = "0.6.0", note = "Use `.as_str()` or `.unprocessed()`.")]
        #[inline]
        pub fn path(&self) -> &str {
            profile_method!(path);

            let skip = self.skip as usize;
            let path = self.path.path();
            if skip <= path.len() {
                &path[skip..]
            } else {
                ""
            }
        }

        /// Set new path.
        #[inline]
        pub fn set(&mut self, path: T) {
            profile_method!(set);

            self.skip = 0;
            self.path = path;
            self.segments.clear();
        }

        /// Reset state.
        #[inline]
        pub fn reset(&mut self) {
            profile_method!(reset);

            self.skip = 0;
            self.segments.clear();
        }

        /// Skip first `n` chars in path.
        #[inline]
        pub fn skip(&mut self, n: u16) {
            profile_method!(skip);
            self.skip += n;
        }

        pub(crate) fn add(&mut self, name: impl Into<Cow<'a, str>>, value: PathItem<'a>) {
            profile_method!(add);

            match value {
                PathItem::Borrowed(s) => self.segments.push((name.into(), PathItem::Borrowed(s))),
                PathItem::Segment(begin, end) => self.segments.push((name.into(), PathItem::Segment(self.skip + begin, self.skip + end))),
            }
        }

        /// Check if there are any matched patterns.
        #[inline]
        pub fn is_empty(&self) -> bool {
            self.segments.is_empty()
        }

        /// Returns number of interpolated segments.
        #[inline]
        pub fn segment_count(&self) -> usize {
            self.segments.len()
        }

        /// Get matched parameter by name without type conversion
        pub fn get(&self, name: &str) -> Option<&str> {
            profile_method!(get);

            for (seg_name, val) in self.segments.iter() {
                if name == seg_name {
                    return match val {
                        PathItem::Borrowed(ref s) => Some(s),
                        PathItem::Segment(s, e) => Some(&self.path.path()[(*s as usize)..(*e as usize)]),
                    };
                }
            }

            None
        }

        /// Get matched parameter by name.
        ///
        /// If keyed parameter is not available empty string is used as default value.
        pub fn query(&self, key: &str) -> &str {
            profile_method!(query);

            if let Some(s) = self.get(key) {
                s
            } else {
                ""
            }
        }

        /// Return iterator to items in parameter container.
        pub fn iter(&self) -> PathIter<'_, T> {
            PathIter {
                idx: 0,
                params: self,
            }
        }

        /// Try to deserialize matching parameters to a specified type `U`
        pub fn load<'de, U: serde::Deserialize<'de>>(&'de self) -> Result<U, de::value::Error> {
            profile_method!(load);
            de::Deserialize::deserialize(PathDeserializer::new(self))
        }
    }

    #[derive(Debug)]
    pub struct PathIter<'a, T> {
        idx: usize,
        params: &'a Path<'a, T>,
    }

    impl<'a, T: ResourcePath> Iterator for PathIter<'a, T> {
        type Item = (&'a str, &'a str);

        #[inline]
        fn next(&mut self) -> Option<(&'a str, &'a str)> {
            if self.idx < self.params.segment_count() {
                let idx = self.idx;
                let res = match self.params.segments[idx].1 {
                    PathItem::Borrowed(ref s) => s,
                    PathItem::Segment(s, e) => &self.params.path.path()[(s as usize)..(e as usize)],
                };
                self.idx += 1;
                return Some((&self.params.segments[idx].0, res));
            }
            None
        }
    }

    impl<'a, T: ResourcePath> Index<&'a str> for Path<'a, T> {
        type Output = str;

        fn index(&self, name: &'a str) -> &str {
            self.get(name).expect("Value for parameter is not available")
        }
    }

    impl<'a, T: ResourcePath> Index<usize> for Path<'a, T> {
        type Output = str;

        fn index(&self, idx: usize) -> &str {
            match self.segments[idx].1 {
                PathItem::Borrowed(ref s) => s,
                PathItem::Segment(s, e) => &self.path.path()[(s as usize)..(e as usize)],
            }
        }
    }

    impl<'a, T: ResourcePath> Resource<'a> for Path<'a, T> {
        type Path = T;

        fn resource_path(&mut self) -> &mut Path<'a, Self::Path> {
            self
        }
    }

    impl<'a, T, P> Resource<'a> for T
    where
        T: DerefMut<Target = Path<'a, P>>,
        P: ResourcePath,
    {
        type Path = P;

        fn resource_path(&mut self) -> &mut Path<'a, Self::Path> {
            &mut *self
        }
    }
}

mod quoter {
    #[allow(dead_code)]
    const GEN_DELIMS: &[u8] = b":/?#[]@";

    #[allow(dead_code)]
    const SUB_DELIMS_WITHOUT_QS: &[u8] = b"!$'()*,";

    #[allow(dead_code)]
    const SUB_DELIMS: &[u8] = b"!$'()*,+?=;";

    #[allow(dead_code)]
    const RESERVED: &[u8] = b":/?#[]@!$'()*,+?=;";

    #[allow(dead_code)]
    const UNRESERVED: &[u8] = b"abcdefghijklmnopqrstuvwxyz
    ABCDEFGHIJKLMNOPQRSTUVWXYZ
    1234567890
    -._~";

    const ALLOWED: &[u8] = b"abcdefghijklmnopqrstuvwxyz
    ABCDEFGHIJKLMNOPQRSTUVWXYZ
    1234567890
    -._~
    !$'()*,";

    const QS: &[u8] = b"+&=;b";

    /// A quoter
    pub struct Quoter {
        /// Simple bit-map of safe values in the 0-127 ASCII range.
        safe_table: [u8; 16],

        /// Simple bit-map of protected values in the 0-127 ASCII range.
        protected_table: [u8; 16],
    }

    impl Quoter {
        pub fn new(safe: &[u8], protected: &[u8]) -> Quoter {
            let mut quoter = Quoter {
                safe_table: [0; 16],
                protected_table: [0; 16],
            };

            // prepare safe table
            for ch in 0..128 {
                if ALLOWED.contains(&ch) {
                    set_bit(&mut quoter.safe_table, ch);
                }

                if QS.contains(&ch) {
                    set_bit(&mut quoter.safe_table, ch);
                }
            }

            for &ch in safe {
                set_bit(&mut quoter.safe_table, ch)
            }

            // prepare protected table
            for &ch in protected {
                set_bit(&mut quoter.safe_table, ch);
                set_bit(&mut quoter.protected_table, ch);
            }

            quoter
        }

        /// Decodes safe percent-encoded sequences from `val`.
        ///
        /// Returns `None` when no modification to the original byte string was required.
        ///
        /// Non-ASCII bytes are accepted as valid input.
        ///
        /// Behavior for invalid/incomplete percent-encoding sequences is unspecified and may include
        /// removing the invalid sequence from the output or passing it as-is.
        pub fn requote(&self, val: &[u8]) -> Option<Vec<u8>> {
            let mut has_pct = 0;
            let mut pct = [b'%', 0, 0];
            let mut idx = 0;
            let mut cloned: Option<Vec<u8>> = None;

            let len = val.len();

            while idx < len {
                let ch = val[idx];

                if has_pct != 0 {
                    pct[has_pct] = val[idx];
                    has_pct += 1;

                    if has_pct == 3 {
                        has_pct = 0;
                        let buf = cloned.as_mut().expect("error logic");

                        if let Some(ch) = hex_pair_to_char(pct[1], pct[2]) {
                            if ch < 128 {
                                if bit_at(&self.protected_table, ch) {
                                    buf.extend_from_slice(&pct);
                                    idx += 1;
                                    continue;
                                }

                                if bit_at(&self.safe_table, ch) {
                                    buf.push(ch);
                                    idx += 1;
                                    continue;
                                }
                            }

                            buf.push(ch);
                        } else {
                            buf.extend_from_slice(&pct[..]);
                        }
                    }
                } else if ch == b'%' {
                    has_pct = 1;

                    if cloned.is_none() {
                        let mut c = Vec::with_capacity(len);
                        c.extend_from_slice(&val[..idx]);
                        cloned = Some(c);
                    }
                } else if let Some(ref mut cloned) = cloned {
                    cloned.push(ch)
                }

                idx += 1;
            }

            cloned
        }

        pub(crate) fn requote_str_lossy(&self, val: &str) -> Option<String> {
            self.requote(val.as_bytes()).map(|data| String::from_utf8_lossy(&data).into_owned())
        }
    }

    /// Converts an ASCII character in the hex-encoded set (`0-9`, `A-F`, `a-f`) to its integer
    /// representation from `0x0`–`0xF`.
    ///
    /// - `0x30 ('0') => 0x0`
    /// - `0x39 ('9') => 0x9`
    /// - `0x41 ('a') => 0xA`
    /// - `0x61 ('A') => 0xA`
    /// - `0x46 ('f') => 0xF`
    /// - `0x66 ('F') => 0xF`
    fn from_ascii_hex(v: u8) -> Option<u8> {
        match v {
            b'0'..=b'9' => Some(v - 0x30),      // ord('0') == 0x30
            b'A'..=b'F' => Some(v - 0x41 + 10), // ord('A') == 0x41
            b'a'..=b'f' => Some(v - 0x61 + 10), // ord('a') == 0x61
            _ => None,
        }
    }

    /// Decode a ASCII hex-encoded pair to an integer.
    ///
    /// Returns `None` if either portion of the decoded pair does not evaluate to a valid hex value.
    ///
    /// - `0x33 ('3'), 0x30 ('0') => 0x30 ('0')`
    /// - `0x34 ('4'), 0x31 ('1') => 0x41 ('A')`
    /// - `0x36 ('6'), 0x31 ('1') => 0x61 ('a')`
    fn hex_pair_to_char(d1: u8, d2: u8) -> Option<u8> {
        let (d_high, d_low) = (from_ascii_hex(d1)?, from_ascii_hex(d2)?);

        // left shift high nibble by 4 bits
        Some(d_high << 4 | d_low)
    }

    /// Sets bit in given bit-map to 1=true.
    ///
    /// # Panics
    /// Panics if `ch` index is out of bounds.
    fn set_bit(array: &mut [u8], ch: u8) {
        array[(ch >> 3) as usize] |= 0b1 << (ch & 0b111)
    }

    /// Returns true if bit to true in given bit-map.
    ///
    /// # Panics
    /// Panics if `ch` index is out of bounds.
    fn bit_at(array: &[u8], ch: u8) -> bool {
        array[(ch >> 3) as usize] & (0b1 << (ch & 0b111)) != 0
    }
}