synta 0.2.6

//! ASN.1 string types.
//!
//! ASN.1 defines many string types that differ in their allowed character
//! sets and on-wire encodings.  This module provides both owned and
//! zero-copy (borrowed) variants for the most common types.
//!
//! ## Owned vs. zero-copy variants
//!
//! Most types exist in two forms:
//!
//! - **Owned** (`OctetString`, `Utf8String`, …) — stores data in a `Vec<u8>`
//!   or `String`.  Use these when you need to keep the data after the
//!   decoder's input lifetime ends.
//! - **Zero-copy** (`OctetStringRef<'a>`, `Utf8StringRef<'a>`, …) — borrows
//!   directly from the decoder input slice with lifetime `'a`.  No allocation
//!   is performed during decoding; call `.to_owned()` when you need ownership.
//!
//! ## Character-set validation
//!
//! | Type              | Validation |
//! |-------------------|-----------|
//! | `PrintableString` | A–Z, a–z, 0–9, and a small set of punctuation |
//! | `IA5String`       | US-ASCII (code points 0–127) |
//! | `NumericString`   | Digits 0–9 and space |
//! | `VisibleString`   | Printable ASCII (0x20–0x7E) |
//! | `Utf8String`      | Well-formed UTF-8 |
//! | `TeletexString`   | No validation — raw bytes |
//! | `GeneralString`   | No validation — raw bytes |
//! | `UniversalString` | UCS-4 (UTF-32 BE, 4 bytes/char) |
//! | `BmpString`       | UCS-2 BE (BMP only, 2 bytes/char; surrogates rejected) |

#[cfg(not(feature = "std"))]
use alloc::{
    string::{String, ToString},
    vec::Vec,
};

/// ASN.1 OCTET STRING — an arbitrary sequence of bytes.
///
/// Holds an owned copy of the raw value bytes.  For a zero-copy alternative
/// that borrows from the decoder input, see [`OctetStringRef`].
///
/// # Example
/// ```
/// use synta::OctetString;
///
/// let s = OctetString::new(vec![0xDE, 0xAD, 0xBE, 0xEF]);
/// assert_eq!(s.as_bytes(), &[0xDE, 0xAD, 0xBE, 0xEF]);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OctetString {
    bytes: Vec<u8>,
}

impl OctetString {
    /// Create a new octet string
    pub fn new(bytes: Vec<u8>) -> Self {
        Self { bytes }
    }

    /// Get the bytes
    pub fn as_bytes(&self) -> &[u8] {
        &self.bytes
    }

    /// Convert into the inner Vec
    pub fn into_vec(self) -> Vec<u8> {
        self.bytes
    }
}

impl From<Vec<u8>> for OctetString {
    fn from(bytes: Vec<u8>) -> Self {
        Self::new(bytes)
    }
}

impl From<OctetString> for Vec<u8> {
    fn from(s: OctetString) -> Self {
        s.into_vec()
    }
}

/// Zero-copy borrowed octet string
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OctetStringRef<'a> {
    bytes: &'a [u8],
}

impl<'a> OctetStringRef<'a> {
    /// Create from a byte slice
    pub fn new(bytes: &'a [u8]) -> Self {
        Self { bytes }
    }

    /// Get the bytes
    pub fn as_bytes(&self) -> &'a [u8] {
        self.bytes
    }

    /// Convert to owned OctetString
    pub fn to_owned(&self) -> OctetString {
        OctetString::new(self.bytes.to_vec())
    }
}

// Implement Decode trait for OctetString
impl crate::traits::Decode<'_> for OctetString {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_OCTET_STRING;

        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_OCTET_STRING);

        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }

        let length = decoder.read_length()?;
        let len = length.definite()?;

        let bytes = decoder.read_bytes(len)?;
        Ok(OctetString::new(bytes.to_vec()))
    }
}

// Implement Decode trait for OctetStringRef (zero-copy)
impl<'a> crate::traits::Decode<'a> for OctetStringRef<'a> {
    fn decode(decoder: &mut crate::der::decoder::Decoder<'a>) -> crate::Result<Self> {
        use crate::tag::TAG_OCTET_STRING;

        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_OCTET_STRING);

        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }

        let length = decoder.read_length()?;
        let len = length.definite()?;

        let bytes = decoder.read_bytes(len)?; // Borrowed slice
        Ok(OctetStringRef::new(bytes))
    }
}

// Implement Encode trait for OctetStringRef
impl<'a> crate::traits::Encode for OctetStringRef<'a> {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_OCTET_STRING;

        let tag = crate::Tag::universal(TAG_OCTET_STRING);
        encoder.write_tag(tag)?;
        encoder.write_length(self.bytes.len())?;
        encoder.write_bytes(self.bytes);
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let tag_len = 1;
        let length_len = crate::Length::Definite(self.bytes.len()).encoded_len()?;
        Ok(tag_len + length_len + self.bytes.len())
    }
}

// Implement Tagged trait for OctetStringRef
impl<'a> crate::traits::Tagged for OctetStringRef<'a> {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_OCTET_STRING)
    }
}

// Implement DecodeImplicit trait for OctetStringRef
impl<'a> crate::traits::DecodeImplicit<'a> for OctetStringRef<'a> {
    fn decode_implicit(content: &'a [u8], _encoding: crate::Encoding) -> crate::Result<Self> {
        Ok(OctetStringRef::new(content))
    }
}

// Implement Encode trait for OctetString
impl crate::traits::Encode for OctetString {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_OCTET_STRING;

        let tag = crate::Tag::universal(TAG_OCTET_STRING);
        encoder.write_tag(tag)?;
        encoder.write_length(self.bytes.len())?;
        encoder.write_bytes(&self.bytes);
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let tag_len = 1;
        let length_len = crate::Length::Definite(self.bytes.len()).encoded_len()?;
        Ok(tag_len + length_len + self.bytes.len())
    }
}

// Implement Tagged trait
impl crate::traits::Tagged for OctetString {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_OCTET_STRING)
    }
}

/// ASN.1 BIT STRING
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BitString {
    bytes: Vec<u8>,
    unused_bits: u8,
}

impl BitString {
    /// Create a new BIT STRING.
    ///
    /// # Arguments
    /// * `bytes` - The bytes containing the bit data (excluding the leading
    ///   "unused bits" byte used in the on-wire encoding).
    /// * `unused_bits` - Number of padding bits in the last byte (0–7).
    ///   The padding bits must be zero, as required by DER and CER.
    ///
    /// # Errors
    /// Returns an error if `unused_bits > 7` or if the trailing padding bits
    /// in the last byte of `bytes` are non-zero.
    ///
    /// # DER/CER constraint
    /// This constructor enforces the DER/CER requirement that unused padding
    /// bits are zero.  BER permits non-zero unused bits, so this constructor
    /// is **not suitable** for constructing BER values where the padding bits
    /// may be set.  Use the decoder's BER path to read such values; they will
    /// be accepted there without this check.
    pub fn new(bytes: Vec<u8>, unused_bits: u8) -> crate::Result<Self> {
        if unused_bits > 7 {
            return Err(crate::Error::InvalidEncoding {
                position: 0,
                tag: crate::Tag::universal(crate::tag::TAG_BIT_STRING),
                #[cfg(feature = "std")]
                reason: format!("Invalid unused bits value: {}", unused_bits),
                #[cfg(not(feature = "std"))]
                reason: "Invalid unused bits value",
            });
        }

        // For DER compliance, unused bits in the last byte must be zero
        if !bytes.is_empty() && unused_bits > 0 {
            let last_byte = bytes[bytes.len() - 1];
            let mask = (1u8 << unused_bits) - 1;
            if (last_byte & mask) != 0 {
                return Err(crate::Error::DerViolation {
                    position: 0,
                    #[cfg(feature = "std")]
                    reason: "Unused bits in last byte must be zero".to_string(),
                    #[cfg(not(feature = "std"))]
                    reason: "Unused bits in last byte must be zero",
                });
            }
        }

        Ok(Self { bytes, unused_bits })
    }

    /// Get the bytes
    pub fn as_bytes(&self) -> &[u8] {
        &self.bytes
    }

    /// Get the number of unused bits in the last byte
    pub fn unused_bits(&self) -> u8 {
        self.unused_bits
    }

    /// Get the total number of bits
    pub fn bit_len(&self) -> usize {
        if self.bytes.is_empty() {
            0
        } else {
            self.bytes.len() * 8 - self.unused_bits as usize
        }
    }
}

// Implement Decode trait for BitString
impl crate::traits::Decode<'_> for BitString {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_BIT_STRING;

        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_BIT_STRING);

        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }

        let length = decoder.read_length()?;
        let len = length.definite()?;

        if len == 0 {
            return Err(crate::Error::InvalidEncoding {
                position: decoder.position(),
                tag,
                #[cfg(feature = "std")]
                reason: "BIT STRING length cannot be 0".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "BIT STRING length cannot be 0",
            });
        }

        let bytes = decoder.read_bytes(len)?;
        let unused_bits = bytes[0];

        if unused_bits > 7 {
            return Err(crate::Error::InvalidEncoding {
                position: decoder.position(),
                tag,
                #[cfg(feature = "std")]
                reason: format!("Invalid unused bits value: {}", unused_bits),
                #[cfg(not(feature = "std"))]
                reason: "Invalid unused bits value",
            });
        }

        // For DER, verify unused bits in last byte are zero
        if decoder.encoding() == crate::Encoding::Der && len > 1 && unused_bits > 0 {
            let last_byte = bytes[len - 1];
            let mask = (1u8 << unused_bits) - 1;
            if (last_byte & mask) != 0 {
                return Err(crate::Error::DerViolation {
                    position: decoder.position(),
                    #[cfg(feature = "std")]
                    reason: "Unused bits in last byte must be zero".to_string(),
                    #[cfg(not(feature = "std"))]
                    reason: "Unused bits in last byte must be zero",
                });
            }
        }

        Ok(BitString {
            bytes: bytes[1..].to_vec(),
            unused_bits,
        })
    }
}

// Implement Encode trait for BitString
impl crate::traits::Encode for BitString {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_BIT_STRING;

        let tag = crate::Tag::universal(TAG_BIT_STRING);
        encoder.write_tag(tag)?;

        // Length is 1 (for unused bits byte) + data bytes
        encoder.write_length(1 + self.bytes.len())?;

        // First byte is the unused bits count
        encoder.write_bytes(&[self.unused_bits]);
        // Then the actual data
        encoder.write_bytes(&self.bytes);

        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let tag_len = 1;
        let content_len = 1 + self.bytes.len();
        let length_len = crate::Length::Definite(content_len).encoded_len()?;
        Ok(tag_len + length_len + content_len)
    }
}

// Implement Tagged trait
impl crate::traits::Tagged for BitString {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_BIT_STRING)
    }
}

/// Zero-copy borrowed BIT STRING
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BitStringRef<'a> {
    bytes: &'a [u8],
    unused_bits: u8,
}

impl<'a> BitStringRef<'a> {
    /// Create a new zero-copy BIT STRING reference.
    ///
    /// # Arguments
    /// * `bytes` - Borrowed slice containing the bit data (excluding the
    ///   leading "unused bits" byte used in the on-wire encoding).
    /// * `unused_bits` - Number of padding bits in the last byte (0–7).
    ///   The padding bits must be zero, as required by DER and CER.
    ///
    /// # Errors
    /// Returns an error if `unused_bits > 7` or if the trailing padding bits
    /// in the last byte of `bytes` are non-zero.
    ///
    /// # DER/CER constraint
    /// Same constraint as [`BitString::new`]: padding bits must be zero.
    /// This makes the constructor unsuitable for BER values where non-zero
    /// padding bits are allowed.
    pub fn new(bytes: &'a [u8], unused_bits: u8) -> crate::Result<Self> {
        if unused_bits > 7 {
            return Err(crate::Error::InvalidEncoding {
                position: 0,
                tag: crate::Tag::universal(crate::tag::TAG_BIT_STRING),
                #[cfg(feature = "std")]
                reason: format!("Invalid unused bits value: {}", unused_bits),
                #[cfg(not(feature = "std"))]
                reason: "Invalid unused bits value",
            });
        }

        // For DER compliance, unused bits in the last byte must be zero
        if !bytes.is_empty() && unused_bits > 0 {
            let last_byte = bytes[bytes.len() - 1];
            let mask = (1u8 << unused_bits) - 1;
            if (last_byte & mask) != 0 {
                return Err(crate::Error::DerViolation {
                    position: 0,
                    #[cfg(feature = "std")]
                    reason: "Unused bits in last byte must be zero".to_string(),
                    #[cfg(not(feature = "std"))]
                    reason: "Unused bits in last byte must be zero",
                });
            }
        }

        Ok(Self { bytes, unused_bits })
    }

    /// Get the bytes
    pub fn as_bytes(&self) -> &'a [u8] {
        self.bytes
    }

    /// Get the number of unused bits in the last byte
    pub fn unused_bits(&self) -> u8 {
        self.unused_bits
    }

    /// Get the total number of bits
    pub fn bit_len(&self) -> usize {
        if self.bytes.is_empty() {
            0
        } else {
            self.bytes.len() * 8 - self.unused_bits as usize
        }
    }

    /// Convert to owned BitString
    pub fn to_owned(&self) -> BitString {
        BitString::new(self.bytes.to_vec(), self.unused_bits).unwrap()
    }
}

// Implement Decode trait for BitStringRef (zero-copy)
impl<'a> crate::traits::Decode<'a> for BitStringRef<'a> {
    fn decode(decoder: &mut crate::der::decoder::Decoder<'a>) -> crate::Result<Self> {
        use crate::tag::TAG_BIT_STRING;

        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_BIT_STRING);

        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }

        let length = decoder.read_length()?;
        let len = length.definite()?;

        if len == 0 {
            return Err(crate::Error::InvalidEncoding {
                position: decoder.position(),
                tag,
                #[cfg(feature = "std")]
                reason: "BIT STRING length cannot be 0".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "BIT STRING length cannot be 0",
            });
        }

        let bytes = decoder.read_bytes(len)?;
        let unused_bits = bytes[0];

        if unused_bits > 7 {
            return Err(crate::Error::InvalidEncoding {
                position: decoder.position(),
                tag,
                #[cfg(feature = "std")]
                reason: format!("Invalid unused bits value: {}", unused_bits),
                #[cfg(not(feature = "std"))]
                reason: "Invalid unused bits value",
            });
        }

        // For DER, verify unused bits in last byte are zero
        if decoder.encoding() == crate::Encoding::Der && len > 1 && unused_bits > 0 {
            let last_byte = bytes[len - 1];
            let mask = (1u8 << unused_bits) - 1;
            if (last_byte & mask) != 0 {
                return Err(crate::Error::DerViolation {
                    position: decoder.position(),
                    #[cfg(feature = "std")]
                    reason: "Unused bits in last byte must be zero".to_string(),
                    #[cfg(not(feature = "std"))]
                    reason: "Unused bits in last byte must be zero",
                });
            }
        }

        Ok(BitStringRef {
            bytes: &bytes[1..], // Borrowed slice
            unused_bits,
        })
    }
}

// Implement Encode trait for BitStringRef
impl<'a> crate::traits::Encode for BitStringRef<'a> {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_BIT_STRING;

        let tag = crate::Tag::universal(TAG_BIT_STRING);
        encoder.write_tag(tag)?;

        // Length is 1 (for unused bits byte) + data bytes
        encoder.write_length(1 + self.bytes.len())?;

        // First byte is the unused bits count
        encoder.write_bytes(&[self.unused_bits]);
        // Then the actual data
        encoder.write_bytes(self.bytes);

        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let tag_len = 1;
        let content_len = 1 + self.bytes.len();
        let length_len = crate::Length::Definite(content_len).encoded_len()?;
        Ok(tag_len + length_len + content_len)
    }
}

// Implement Tagged trait for BitStringRef
impl<'a> crate::traits::Tagged for BitStringRef<'a> {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_BIT_STRING)
    }
}

// Implement DecodeImplicit trait for BitStringRef
impl<'a> crate::traits::DecodeImplicit<'a> for BitStringRef<'a> {
    fn decode_implicit(content: &'a [u8], _encoding: crate::Encoding) -> crate::Result<Self> {
        if content.is_empty() {
            return Err(crate::Error::UnexpectedEof { position: 0 });
        }
        let unused_bits = content[0];
        BitStringRef::new(&content[1..], unused_bits)
    }
}

/// ASN.1 UTF8String — a Unicode string encoded as UTF-8.
///
/// The byte content is validated as well-formed UTF-8 during decoding.
/// The inner `String` is accessible via [`as_str`](Self::as_str) or can be
/// consumed by [`into_string`](Self::into_string).
///
/// For a zero-copy alternative that borrows from the decoder input,
/// see [`Utf8StringRef`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Utf8String(pub String);

impl Utf8String {
    /// Create a new UTF8String
    pub fn new(s: String) -> Self {
        Self(s)
    }

    /// Get the string value
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Convert into the inner String
    pub fn into_string(self) -> String {
        self.0
    }
}

impl From<String> for Utf8String {
    fn from(s: String) -> Self {
        Self::new(s)
    }
}

impl From<Utf8String> for String {
    fn from(s: Utf8String) -> Self {
        s.into_string()
    }
}

// Implement Decode trait for Utf8String
impl crate::traits::Decode<'_> for Utf8String {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_UTF8_STRING;

        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_UTF8_STRING);

        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }

        let length = decoder.read_length()?;
        let len = length.definite()?;

        let bytes = decoder.read_bytes(len)?;

        // Validate UTF-8
        let s = core::str::from_utf8(bytes).map_err(|_| crate::Error::InvalidString {
            position: decoder.position(),
            string_type: "UTF8String",
            #[cfg(feature = "std")]
            reason: "Invalid UTF-8 encoding".to_string(),
            #[cfg(not(feature = "std"))]
            reason: "Invalid UTF-8 encoding",
        })?;

        Ok(Utf8String::new(s.to_string()))
    }
}

// Implement Encode trait for Utf8String
impl crate::traits::Encode for Utf8String {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_UTF8_STRING;

        let tag = crate::Tag::universal(TAG_UTF8_STRING);
        encoder.write_tag(tag)?;
        encoder.write_length(self.0.len())?;
        encoder.write_bytes(self.0.as_bytes());
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let tag_len = 1;
        let length_len = crate::Length::Definite(self.0.len()).encoded_len()?;
        Ok(tag_len + length_len + self.0.len())
    }
}

// Implement Tagged trait
impl crate::traits::Tagged for Utf8String {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_UTF8_STRING)
    }
}

/// Zero-copy borrowed UTF8String
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Utf8StringRef<'a>(&'a str);

impl<'a> Utf8StringRef<'a> {
    /// Create from a string slice
    pub fn new(s: &'a str) -> Self {
        Self(s)
    }

    /// Get the string value
    pub fn as_str(&self) -> &'a str {
        self.0
    }

    /// Convert to owned Utf8String
    pub fn to_owned(&self) -> Utf8String {
        Utf8String::new(self.0.to_string())
    }
}

// Implement Decode trait for Utf8StringRef (zero-copy)
impl<'a> crate::traits::Decode<'a> for Utf8StringRef<'a> {
    fn decode(decoder: &mut crate::der::decoder::Decoder<'a>) -> crate::Result<Self> {
        use crate::tag::TAG_UTF8_STRING;

        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_UTF8_STRING);

        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }

        let length = decoder.read_length()?;
        let len = length.definite()?;

        let bytes = decoder.read_bytes(len)?;

        // Validate UTF-8
        let s = core::str::from_utf8(bytes).map_err(|_| crate::Error::InvalidString {
            position: decoder.position(),
            string_type: "UTF8String",
            #[cfg(feature = "std")]
            reason: "Invalid UTF-8 encoding".to_string(),
            #[cfg(not(feature = "std"))]
            reason: "Invalid UTF-8 encoding",
        })?;

        Ok(Utf8StringRef::new(s))
    }
}

// Implement Encode trait for Utf8StringRef
impl<'a> crate::traits::Encode for Utf8StringRef<'a> {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_UTF8_STRING;

        let tag = crate::Tag::universal(TAG_UTF8_STRING);
        encoder.write_tag(tag)?;
        encoder.write_length(self.0.len())?;
        encoder.write_bytes(self.0.as_bytes());
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let tag_len = 1;
        let length_len = crate::Length::Definite(self.0.len()).encoded_len()?;
        Ok(tag_len + length_len + self.0.len())
    }
}

// Implement Tagged trait for Utf8StringRef
impl<'a> crate::traits::Tagged for Utf8StringRef<'a> {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_UTF8_STRING)
    }
}

/// ASN.1 PrintableString
///
/// PrintableString is a subset of ASCII containing:
/// - A-Z, a-z
/// - 0-9
/// - Space
/// - ' ( ) + , - . / : = ?
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PrintableString(pub String);

impl PrintableString {
    /// Create a new PrintableString
    ///
    /// Returns error if the string contains characters outside the PrintableString character set
    pub fn new(s: String) -> crate::Result<Self> {
        // Validate that all characters are in the PrintableString character set
        if !Self::is_valid(&s) {
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "PrintableString",
                #[cfg(feature = "std")]
                reason: "String contains invalid characters for PrintableString".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Invalid characters for PrintableString",
            });
        }
        Ok(Self(s))
    }

    /// Check if a string is valid PrintableString
    fn is_valid(s: &str) -> bool {
        s.chars().all(|c| {
            matches!(c,
                'A'..='Z' | 'a'..='z' | '0'..='9' |
                ' ' | '\'' | '(' | ')' | '+' | ',' | '-' | '.' | '/' | ':' | '=' | '?'
            )
        })
    }

    /// Get the string value
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Convert into the inner String
    pub fn into_string(self) -> String {
        self.0
    }
}

// Implement Decode trait for PrintableString
impl crate::traits::Decode<'_> for PrintableString {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_PRINTABLE_STRING;

        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_PRINTABLE_STRING);

        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }

        let length = decoder.read_length()?;
        let len = length.definite()?;

        let bytes = decoder.read_bytes(len)?;

        // Validate ASCII
        let s = core::str::from_utf8(bytes).map_err(|_| crate::Error::InvalidString {
            position: decoder.position(),
            string_type: "PrintableString",
            #[cfg(feature = "std")]
            reason: "Invalid UTF-8/ASCII encoding".to_string(),
            #[cfg(not(feature = "std"))]
            reason: "Invalid UTF-8/ASCII encoding",
        })?;

        // Validate PrintableString character set
        if !PrintableString::is_valid(s) {
            return Err(crate::Error::InvalidString {
                position: decoder.position(),
                string_type: "PrintableString",
                #[cfg(feature = "std")]
                reason: "String contains invalid characters for PrintableString".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Invalid characters for PrintableString",
            });
        }

        Ok(PrintableString(s.to_string()))
    }
}

// Implement Encode trait for PrintableString
impl crate::traits::Encode for PrintableString {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_PRINTABLE_STRING;

        let tag = crate::Tag::universal(TAG_PRINTABLE_STRING);
        encoder.write_tag(tag)?;
        encoder.write_length(self.0.len())?;
        encoder.write_bytes(self.0.as_bytes());
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let tag_len = 1;
        let length_len = crate::Length::Definite(self.0.len()).encoded_len()?;
        Ok(tag_len + length_len + self.0.len())
    }
}

// Implement Tagged trait
impl crate::traits::Tagged for PrintableString {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_PRINTABLE_STRING)
    }
}

/// Zero-copy borrowed PrintableString
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PrintableStringRef<'a>(&'a str);

impl<'a> PrintableStringRef<'a> {
    /// Create from a string slice
    ///
    /// Returns error if the string contains characters outside the PrintableString character set
    pub fn new(s: &'a str) -> crate::Result<Self> {
        // Validate that all characters are in the PrintableString character set
        if !PrintableString::is_valid(s) {
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "PrintableString",
                #[cfg(feature = "std")]
                reason: "String contains invalid characters for PrintableString".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Invalid characters for PrintableString",
            });
        }
        Ok(Self(s))
    }

    /// Get the string value
    pub fn as_str(&self) -> &'a str {
        self.0
    }

    /// Convert to owned PrintableString
    pub fn to_owned(&self) -> PrintableString {
        PrintableString::new(self.0.to_string()).unwrap()
    }
}

// Implement Decode trait for PrintableStringRef (zero-copy)
impl<'a> crate::traits::Decode<'a> for PrintableStringRef<'a> {
    fn decode(decoder: &mut crate::der::decoder::Decoder<'a>) -> crate::Result<Self> {
        use crate::tag::TAG_PRINTABLE_STRING;

        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_PRINTABLE_STRING);

        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }

        let length = decoder.read_length()?;
        let len = length.definite()?;

        let bytes = decoder.read_bytes(len)?;

        // Validate ASCII
        let s = core::str::from_utf8(bytes).map_err(|_| crate::Error::InvalidString {
            position: decoder.position(),
            string_type: "PrintableString",
            #[cfg(feature = "std")]
            reason: "Invalid UTF-8/ASCII encoding".to_string(),
            #[cfg(not(feature = "std"))]
            reason: "Invalid UTF-8/ASCII encoding",
        })?;

        // Validate PrintableString character set
        if !PrintableString::is_valid(s) {
            return Err(crate::Error::InvalidString {
                position: decoder.position(),
                string_type: "PrintableString",
                #[cfg(feature = "std")]
                reason: "String contains invalid characters for PrintableString".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Invalid characters for PrintableString",
            });
        }

        Ok(PrintableStringRef(s))
    }
}

// Implement Encode trait for PrintableStringRef
impl<'a> crate::traits::Encode for PrintableStringRef<'a> {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_PRINTABLE_STRING;

        let tag = crate::Tag::universal(TAG_PRINTABLE_STRING);
        encoder.write_tag(tag)?;
        encoder.write_length(self.0.len())?;
        encoder.write_bytes(self.0.as_bytes());
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let tag_len = 1;
        let length_len = crate::Length::Definite(self.0.len()).encoded_len()?;
        Ok(tag_len + length_len + self.0.len())
    }
}

// Implement Tagged trait for PrintableStringRef
impl<'a> crate::traits::Tagged for PrintableStringRef<'a> {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_PRINTABLE_STRING)
    }
}

/// ASN.1 IA5String — International Alphabet 5, equivalent to US-ASCII.
///
/// Only code points 0–127 are allowed.  Construction validates that every
/// character is within the ASCII range.  Commonly used in X.509 extensions
/// for email addresses, URIs, and DNS names.
///
/// For a zero-copy alternative that borrows from the decoder input,
/// see [`IA5StringRef`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct IA5String(pub String);

impl IA5String {
    /// Create a new IA5String
    ///
    /// Returns error if the string contains non-ASCII characters
    pub fn new(s: String) -> crate::Result<Self> {
        // Validate that all characters are ASCII (0-127)
        if !s.is_ascii() {
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "IA5String",
                #[cfg(feature = "std")]
                reason: "String contains non-ASCII characters".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Non-ASCII characters",
            });
        }
        Ok(Self(s))
    }

    /// Get the string value
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Convert into the inner String
    pub fn into_string(self) -> String {
        self.0
    }
}

// Implement Decode trait for IA5String
impl crate::traits::Decode<'_> for IA5String {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_IA5_STRING;

        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_IA5_STRING);

        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }

        let length = decoder.read_length()?;
        let len = length.definite()?;

        let bytes = decoder.read_bytes(len)?;

        // Validate ASCII
        let s = core::str::from_utf8(bytes).map_err(|_| crate::Error::InvalidString {
            position: decoder.position(),
            string_type: "IA5String",
            #[cfg(feature = "std")]
            reason: "Invalid UTF-8/ASCII encoding".to_string(),
            #[cfg(not(feature = "std"))]
            reason: "Invalid UTF-8/ASCII encoding",
        })?;

        // Validate that all characters are ASCII
        if !s.is_ascii() {
            return Err(crate::Error::InvalidString {
                position: decoder.position(),
                string_type: "IA5String",
                #[cfg(feature = "std")]
                reason: "String contains non-ASCII characters".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Non-ASCII characters",
            });
        }

        Ok(IA5String(s.to_string()))
    }
}

// Implement Encode trait for IA5String
impl crate::traits::Encode for IA5String {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_IA5_STRING;

        let tag = crate::Tag::universal(TAG_IA5_STRING);
        encoder.write_tag(tag)?;
        encoder.write_length(self.0.len())?;
        encoder.write_bytes(self.0.as_bytes());
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let tag_len = 1;
        let length_len = crate::Length::Definite(self.0.len()).encoded_len()?;
        Ok(tag_len + length_len + self.0.len())
    }
}

// Implement Tagged trait
impl crate::traits::Tagged for IA5String {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_IA5_STRING)
    }
}

/// ASN.1 NumericString (tag 18)
///
/// A restricted character set containing only digits (0-9) and space.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NumericString(pub String);

impl NumericString {
    /// Create a new NumericString.
    ///
    /// Returns an error if the string contains characters outside the NumericString
    /// character set (digits 0-9 and space).
    pub fn new(s: String) -> crate::Result<Self> {
        if !s.chars().all(|c| c.is_ascii_digit() || c == ' ') {
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "NumericString",
                #[cfg(feature = "std")]
                reason: "String contains invalid characters for NumericString".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Invalid characters for NumericString",
            });
        }
        Ok(Self(s))
    }

    /// Get the string value.
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Convert into the inner String.
    pub fn into_string(self) -> String {
        self.0
    }
}

impl crate::traits::Decode<'_> for NumericString {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_NUMERIC_STRING;
        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_NUMERIC_STRING);
        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }
        let length = decoder.read_length()?;
        let len = length.definite()?;
        let bytes = decoder.read_bytes(len)?;
        let s = core::str::from_utf8(bytes).map_err(|_| crate::Error::InvalidString {
            position: decoder.position(),
            string_type: "NumericString",
            #[cfg(feature = "std")]
            reason: "Invalid ASCII encoding".to_string(),
            #[cfg(not(feature = "std"))]
            reason: "Invalid ASCII encoding",
        })?;
        NumericString::new(s.to_string())
    }
}

impl crate::traits::Encode for NumericString {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_NUMERIC_STRING;
        encoder.write_tag(crate::Tag::universal(TAG_NUMERIC_STRING))?;
        encoder.write_length(self.0.len())?;
        encoder.write_bytes(self.0.as_bytes());
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let length_len = crate::Length::Definite(self.0.len()).encoded_len()?;
        Ok(1 + length_len + self.0.len())
    }
}

impl crate::traits::Tagged for NumericString {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_NUMERIC_STRING)
    }
}

/// ASN.1 TeletexString / T61String (tag 20)
///
/// An 8-bit character set (ITU T.61), in practice treated as raw bytes.
/// No character set validation is performed; bytes are decoded as Latin-1 on request.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TeletexString(pub Vec<u8>);

impl TeletexString {
    /// Create a new TeletexString from raw bytes.
    pub fn new(bytes: Vec<u8>) -> Self {
        Self(bytes)
    }

    /// Create a new TeletexString from a string slice, encoding it as Latin-1.
    ///
    /// Returns an error if any character is outside the Latin-1 range (U+0000..=U+00FF).
    ///
    /// For pure-ASCII input an SIMD-optimized scan is used followed by a single `memcpy`.
    /// For strings containing non-ASCII Latin-1 characters the encoding is done
    /// character by character (UTF-8 stores U+0080–U+00FF as two bytes; Latin-1 uses one).
    pub fn from_latin1(s: &str) -> crate::Result<Self> {
        // Fast path: SIMD-optimized ASCII scan, then a single memcpy.
        if s.is_ascii() {
            return Ok(Self(s.as_bytes().to_vec()));
        }
        // Slow path: validate and re-encode char by char in one pass.
        let mut bytes = Vec::with_capacity(s.len());
        for c in s.chars() {
            if c as u32 > 0xFF {
                return Err(crate::Error::InvalidString {
                    position: 0,
                    string_type: "TeletexString",
                    #[cfg(feature = "std")]
                    reason: format!(
                        "character U+{:04X} is outside Latin-1 range (U+0000..=U+00FF)",
                        c as u32
                    ),
                    #[cfg(not(feature = "std"))]
                    reason: "character outside Latin-1 range (U+0000..=U+00FF)",
                });
            }
            bytes.push(c as u8);
        }
        Ok(Self(bytes))
    }

    /// Create a new TeletexString from an owned String, encoding it as Latin-1.
    ///
    /// Returns an error if any character is outside the Latin-1 range (U+0000..=U+00FF).
    ///
    /// For pure-ASCII input the String's heap buffer is reused directly via
    /// [`String::into_bytes`] (zero extra allocation).  For strings containing
    /// non-ASCII Latin-1 characters a new `Vec<u8>` is allocated.
    pub fn from_latin1_string(s: String) -> crate::Result<Self> {
        // Fast path: pure ASCII — reuse the String's heap buffer (zero extra allocation).
        if s.is_ascii() {
            return Ok(Self(s.into_bytes()));
        }
        // Slow path: validate and re-encode char by char in one pass.
        let mut bytes = Vec::with_capacity(s.len());
        for c in s.chars() {
            if c as u32 > 0xFF {
                return Err(crate::Error::InvalidString {
                    position: 0,
                    string_type: "TeletexString",
                    #[cfg(feature = "std")]
                    reason: format!(
                        "character U+{:04X} is outside Latin-1 range (U+0000..=U+00FF)",
                        c as u32
                    ),
                    #[cfg(not(feature = "std"))]
                    reason: "character outside Latin-1 range (U+0000..=U+00FF)",
                });
            }
            bytes.push(c as u8);
        }
        Ok(Self(bytes))
    }

    /// Create a new TeletexString from a string, encoding it as Latin-1 (lossy).
    ///
    /// Characters above U+00FF are silently truncated to their low 8 bits.
    /// Prefer [`TeletexString::from_latin1`] which returns an error for out-of-range
    /// characters.
    pub fn from_str_lossy(s: &str) -> Self {
        Self(s.chars().map(|c| c as u8).collect())
    }

    /// Get the raw bytes.
    pub fn as_bytes(&self) -> &[u8] {
        &self.0
    }

    /// Decode the bytes as a Latin-1 string.
    pub fn as_latin1_string(&self) -> String {
        self.0.iter().map(|&b| b as char).collect()
    }

    /// Convert into the inner Vec.
    pub fn into_vec(self) -> Vec<u8> {
        self.0
    }
}

impl crate::traits::Decode<'_> for TeletexString {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_TELETEX_STRING;
        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_TELETEX_STRING);
        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }
        let length = decoder.read_length()?;
        let len = length.definite()?;
        let bytes = decoder.read_bytes(len)?;
        Ok(TeletexString::new(bytes.to_vec()))
    }
}

impl crate::traits::Encode for TeletexString {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_TELETEX_STRING;
        encoder.write_tag(crate::Tag::universal(TAG_TELETEX_STRING))?;
        encoder.write_length(self.0.len())?;
        encoder.write_bytes(&self.0);
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let length_len = crate::Length::Definite(self.0.len()).encoded_len()?;
        Ok(1 + length_len + self.0.len())
    }
}

impl crate::traits::Tagged for TeletexString {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_TELETEX_STRING)
    }
}

/// ASN.1 VisibleString / ISO646String (tag 26)
///
/// Printable ASCII characters: 0x20 (space) through 0x7e (~), excluding control characters.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VisibleString(pub String);

impl VisibleString {
    /// Create a new VisibleString.
    ///
    /// Returns an error if the string contains characters outside the VisibleString
    /// character set (printable ASCII 0x20-0x7e).
    pub fn new(s: String) -> crate::Result<Self> {
        if !s.bytes().all(|b| (0x20..=0x7e).contains(&b)) {
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "VisibleString",
                #[cfg(feature = "std")]
                reason: "String contains invalid characters for VisibleString".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Invalid characters for VisibleString",
            });
        }
        Ok(Self(s))
    }

    /// Get the string value.
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Convert into the inner String.
    pub fn into_string(self) -> String {
        self.0
    }
}

impl crate::traits::Decode<'_> for VisibleString {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_VISIBLE_STRING;
        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_VISIBLE_STRING);
        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }
        let length = decoder.read_length()?;
        let len = length.definite()?;
        let bytes = decoder.read_bytes(len)?;
        let s = core::str::from_utf8(bytes).map_err(|_| crate::Error::InvalidString {
            position: decoder.position(),
            string_type: "VisibleString",
            #[cfg(feature = "std")]
            reason: "Invalid ASCII encoding".to_string(),
            #[cfg(not(feature = "std"))]
            reason: "Invalid ASCII encoding",
        })?;
        VisibleString::new(s.to_string())
    }
}

impl crate::traits::Encode for VisibleString {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_VISIBLE_STRING;
        encoder.write_tag(crate::Tag::universal(TAG_VISIBLE_STRING))?;
        encoder.write_length(self.0.len())?;
        encoder.write_bytes(self.0.as_bytes());
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let length_len = crate::Length::Definite(self.0.len()).encoded_len()?;
        Ok(1 + length_len + self.0.len())
    }
}

impl crate::traits::Tagged for VisibleString {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_VISIBLE_STRING)
    }
}

/// ASN.1 GeneralString (tag 27)
///
/// An 8-bit character set. In practice (Kerberos, X.500) this is used as Latin-1
/// or ASCII. No character set validation is performed; bytes are exposed raw.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GeneralString(pub Vec<u8>);

impl GeneralString {
    /// Create a new GeneralString from raw bytes.
    pub fn new(bytes: Vec<u8>) -> Self {
        Self(bytes)
    }

    /// Create a new GeneralString from an ASCII string slice.
    ///
    /// Returns an error if any character is outside the ASCII range (U+0000..=U+007F).
    /// The bytes are copied with a single `memcpy`; no per-character processing is needed
    /// because ASCII code points equal their UTF-8 byte representations.
    pub fn from_ascii(s: &str) -> crate::Result<Self> {
        if !s.is_ascii() {
            let c = s.chars().find(|c| !c.is_ascii()).unwrap();
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "GeneralString",
                #[cfg(feature = "std")]
                reason: format!(
                    "character U+{:04X} is outside ASCII range (U+0000..=U+007F)",
                    c as u32
                ),
                #[cfg(not(feature = "std"))]
                reason: "character outside ASCII range (U+0000..=U+007F)",
            });
        }
        Ok(Self(s.as_bytes().to_vec()))
    }

    /// Create a new GeneralString from an owned ASCII String.
    ///
    /// Returns an error if any character is outside the ASCII range (U+0000..=U+007F).
    ///
    /// On success the String's heap buffer is reused directly via [`String::into_bytes`];
    /// no extra allocation is performed.
    pub fn from_ascii_string(s: String) -> crate::Result<Self> {
        if !s.is_ascii() {
            let c = s.chars().find(|c| !c.is_ascii()).unwrap();
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "GeneralString",
                #[cfg(feature = "std")]
                reason: format!(
                    "character U+{:04X} is outside ASCII range (U+0000..=U+007F)",
                    c as u32
                ),
                #[cfg(not(feature = "std"))]
                reason: "character outside ASCII range (U+0000..=U+007F)",
            });
        }
        Ok(Self(s.into_bytes()))
    }

    /// Create a new GeneralString from a string, encoding it as Latin-1 (lossy).
    ///
    /// Characters above U+00FF are silently truncated to their low 8 bits.
    /// Prefer [`GeneralString::from_ascii`] which returns an error for out-of-range
    /// characters.
    pub fn from_str_lossy(s: &str) -> Self {
        Self(s.chars().map(|c| c as u8).collect())
    }

    /// Get the raw bytes.
    pub fn as_bytes(&self) -> &[u8] {
        &self.0
    }

    /// Decode the bytes as a Latin-1 string.
    pub fn as_latin1_string(&self) -> String {
        self.0.iter().map(|&b| b as char).collect()
    }

    /// Convert into the inner Vec.
    pub fn into_vec(self) -> Vec<u8> {
        self.0
    }
}

impl crate::traits::Decode<'_> for GeneralString {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_GENERAL_STRING;
        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_GENERAL_STRING);
        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }
        let length = decoder.read_length()?;
        let len = length.definite()?;
        let bytes = decoder.read_bytes(len)?;
        Ok(GeneralString::new(bytes.to_vec()))
    }
}

impl crate::traits::Encode for GeneralString {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_GENERAL_STRING;
        encoder.write_tag(crate::Tag::universal(TAG_GENERAL_STRING))?;
        encoder.write_length(self.0.len())?;
        encoder.write_bytes(&self.0);
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let length_len = crate::Length::Definite(self.0.len()).encoded_len()?;
        Ok(1 + length_len + self.0.len())
    }
}

impl crate::traits::Tagged for GeneralString {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_GENERAL_STRING)
    }
}

/// ASN.1 UniversalString (tag 28)
///
/// Characters encoded as UCS-4 (UTF-32 big-endian, 4 bytes per code point).
/// Decoded to a Rust String on construction.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UniversalString(pub String);

impl UniversalString {
    /// Create a new UniversalString from a Rust string.
    pub fn new(s: String) -> Self {
        Self(s)
    }

    /// Decode a UniversalString from raw UCS-4 big-endian bytes.
    ///
    /// Returns an error if the byte length is not a multiple of 4, or if any
    /// four-byte sequence is not a valid Unicode scalar value.
    pub fn from_ucs4_be(bytes: &[u8]) -> crate::Result<Self> {
        if !bytes.len().is_multiple_of(4) {
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "UniversalString",
                #[cfg(feature = "std")]
                reason: format!("UCS-4 byte length {} is not a multiple of 4", bytes.len()),
                #[cfg(not(feature = "std"))]
                reason: "UCS-4 byte length is not a multiple of 4",
            });
        }
        let mut s = String::with_capacity(bytes.len() / 4);
        for chunk in bytes.chunks(4) {
            let code_point = u32::from_be_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]);
            let c = char::from_u32(code_point).ok_or_else(|| crate::Error::InvalidString {
                position: 0,
                string_type: "UniversalString",
                #[cfg(feature = "std")]
                reason: format!("Invalid Unicode code point: U+{:04X}", code_point),
                #[cfg(not(feature = "std"))]
                reason: "Invalid Unicode code point",
            })?;
            s.push(c);
        }
        Ok(Self(s))
    }

    /// Encode the string as UCS-4 big-endian bytes.
    pub fn to_ucs4_be(&self) -> Vec<u8> {
        let mut bytes = Vec::with_capacity(self.0.chars().count() * 4);
        for c in self.0.chars() {
            bytes.extend_from_slice(&(c as u32).to_be_bytes());
        }
        bytes
    }

    /// Get the string value.
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Convert into the inner String.
    pub fn into_string(self) -> String {
        self.0
    }
}

impl crate::traits::Decode<'_> for UniversalString {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_UNIVERSAL_STRING;
        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_UNIVERSAL_STRING);
        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }
        let length = decoder.read_length()?;
        let len = length.definite()?;
        let bytes = decoder.read_bytes(len)?;
        UniversalString::from_ucs4_be(bytes)
    }
}

impl crate::traits::Encode for UniversalString {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_UNIVERSAL_STRING;
        let ucs4 = self.to_ucs4_be();
        encoder.write_tag(crate::Tag::universal(TAG_UNIVERSAL_STRING))?;
        encoder.write_length(ucs4.len())?;
        encoder.write_bytes(&ucs4);
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let content_len = self.0.chars().count() * 4;
        let length_len = crate::Length::Definite(content_len).encoded_len()?;
        Ok(1 + length_len + content_len)
    }
}

impl crate::traits::Tagged for UniversalString {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_UNIVERSAL_STRING)
    }
}

/// ASN.1 BMPString (tag 30)
///
/// Characters encoded as UCS-2 big-endian (Basic Multilingual Plane only, 2 bytes per
/// code point). Decoded to a Rust String on construction.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BmpString(pub String);

impl BmpString {
    /// Create a new BmpString from a Rust string.
    ///
    /// Returns an error if the string contains code points outside the BMP (> U+FFFF).
    pub fn new(s: String) -> crate::Result<Self> {
        if s.chars().any(|c| c as u32 > 0xFFFF) {
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "BMPString",
                #[cfg(feature = "std")]
                reason: "String contains characters outside the Basic Multilingual Plane"
                    .to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Character outside BMP",
            });
        }
        Ok(Self(s))
    }

    /// Decode a BMPString from raw UCS-2 big-endian bytes.
    ///
    /// Returns an error if the byte length is not even, or if any two-byte sequence
    /// is a surrogate half (which would be invalid UCS-2).
    pub fn from_ucs2_be(bytes: &[u8]) -> crate::Result<Self> {
        if !bytes.len().is_multiple_of(2) {
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "BMPString",
                #[cfg(feature = "std")]
                reason: format!("UCS-2 byte length {} is not even", bytes.len()),
                #[cfg(not(feature = "std"))]
                reason: "UCS-2 byte length is not even",
            });
        }
        let mut s = String::with_capacity(bytes.len() / 2);
        for chunk in bytes.chunks(2) {
            let code_unit = u16::from_be_bytes([chunk[0], chunk[1]]);
            // Reject surrogate halves (0xD800-0xDFFF are not valid UCS-2 BMP chars)
            if (0xD800..=0xDFFF).contains(&code_unit) {
                return Err(crate::Error::InvalidString {
                    position: 0,
                    string_type: "BMPString",
                    #[cfg(feature = "std")]
                    reason: format!(
                        "Surrogate code unit U+{:04X} is not valid in BMPString",
                        code_unit
                    ),
                    #[cfg(not(feature = "std"))]
                    reason: "Surrogate code unit in BMPString",
                });
            }
            // Safety: BMP code points that are not surrogates are valid Unicode scalar values
            let c = char::from_u32(code_unit as u32).unwrap();
            s.push(c);
        }
        Ok(Self(s))
    }

    /// Encode the string as UCS-2 big-endian bytes.
    pub fn to_ucs2_be(&self) -> Vec<u8> {
        let mut bytes = Vec::with_capacity(self.0.chars().count() * 2);
        for c in self.0.chars() {
            bytes.extend_from_slice(&(c as u16).to_be_bytes());
        }
        bytes
    }

    /// Get the string value.
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Convert into the inner String.
    pub fn into_string(self) -> String {
        self.0
    }
}

impl crate::traits::Decode<'_> for BmpString {
    fn decode(decoder: &mut crate::der::decoder::Decoder) -> crate::Result<Self> {
        use crate::tag::TAG_BMP_STRING;
        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_BMP_STRING);
        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }
        let length = decoder.read_length()?;
        let len = length.definite()?;
        let bytes = decoder.read_bytes(len)?;
        BmpString::from_ucs2_be(bytes)
    }
}

impl crate::traits::Encode for BmpString {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_BMP_STRING;
        let ucs2 = self.to_ucs2_be();
        encoder.write_tag(crate::Tag::universal(TAG_BMP_STRING))?;
        encoder.write_length(ucs2.len())?;
        encoder.write_bytes(&ucs2);
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let content_len = self.0.chars().count() * 2;
        let length_len = crate::Length::Definite(content_len).encoded_len()?;
        Ok(1 + length_len + content_len)
    }
}

impl crate::traits::Tagged for BmpString {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_BMP_STRING)
    }
}

/// Zero-copy borrowed IA5String (International Alphabet 5 / US-ASCII).
///
/// Borrows a `&str` slice directly from the decoder input with lifetime `'a`.
/// Construction validates that every character is within the ASCII range
/// (code points 0–127).  Call [`to_owned`](Self::to_owned) to obtain an
/// owned [`IA5String`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct IA5StringRef<'a>(&'a str);

impl<'a> IA5StringRef<'a> {
    /// Create from a string slice
    ///
    /// Returns error if the string contains non-ASCII characters
    pub fn new(s: &'a str) -> crate::Result<Self> {
        // Validate that all characters are ASCII (0-127)
        if !s.is_ascii() {
            return Err(crate::Error::InvalidString {
                position: 0,
                string_type: "IA5String",
                #[cfg(feature = "std")]
                reason: "String contains non-ASCII characters".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Non-ASCII characters",
            });
        }
        Ok(Self(s))
    }

    /// Get the string value
    pub fn as_str(&self) -> &'a str {
        self.0
    }

    /// Convert to owned IA5String
    pub fn to_owned(&self) -> IA5String {
        IA5String::new(self.0.to_string()).unwrap()
    }
}

// Implement Decode trait for IA5StringRef (zero-copy)
impl<'a> crate::traits::Decode<'a> for IA5StringRef<'a> {
    fn decode(decoder: &mut crate::der::decoder::Decoder<'a>) -> crate::Result<Self> {
        use crate::tag::TAG_IA5_STRING;

        let tag = decoder.read_tag()?;
        let expected_tag = crate::Tag::universal(TAG_IA5_STRING);

        if tag != expected_tag {
            return Err(crate::Error::UnexpectedTag {
                position: decoder.position(),
                expected: expected_tag,
                actual: tag,
            });
        }

        let length = decoder.read_length()?;
        let len = length.definite()?;

        let bytes = decoder.read_bytes(len)?;

        // Validate ASCII
        let s = core::str::from_utf8(bytes).map_err(|_| crate::Error::InvalidString {
            position: decoder.position(),
            string_type: "IA5String",
            #[cfg(feature = "std")]
            reason: "Invalid UTF-8/ASCII encoding".to_string(),
            #[cfg(not(feature = "std"))]
            reason: "Invalid UTF-8/ASCII encoding",
        })?;

        // Validate that all characters are ASCII
        if !s.is_ascii() {
            return Err(crate::Error::InvalidString {
                position: decoder.position(),
                string_type: "IA5String",
                #[cfg(feature = "std")]
                reason: "String contains non-ASCII characters".to_string(),
                #[cfg(not(feature = "std"))]
                reason: "Non-ASCII characters",
            });
        }

        Ok(IA5StringRef(s))
    }
}

// Implement Encode trait for IA5StringRef
impl<'a> crate::traits::Encode for IA5StringRef<'a> {
    fn encode(&self, encoder: &mut crate::der::encoder::Encoder) -> crate::Result<()> {
        use crate::tag::TAG_IA5_STRING;

        let tag = crate::Tag::universal(TAG_IA5_STRING);
        encoder.write_tag(tag)?;
        encoder.write_length(self.0.len())?;
        encoder.write_bytes(self.0.as_bytes());
        Ok(())
    }

    fn encoded_len(&self) -> crate::Result<usize> {
        let tag_len = 1;
        let length_len = crate::Length::Definite(self.0.len()).encoded_len()?;
        Ok(tag_len + length_len + self.0.len())
    }
}

// Implement Tagged trait for IA5StringRef
impl<'a> crate::traits::Tagged for IA5StringRef<'a> {
    fn tag() -> crate::Tag {
        crate::Tag::universal(crate::tag::TAG_IA5_STRING)
    }
}

// ---- serde support ----

// OctetString: hex-encoded bytes
#[cfg(feature = "serde")]
impl serde::Serialize for OctetString {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(&crate::serde_impl::bytes_to_hex(self.as_bytes()))
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for OctetString {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let hex = <String as serde::Deserialize<'de>>::deserialize(d)?;
        let bytes = crate::serde_impl::hex_to_bytes::<D::Error>(&hex)?;
        Ok(OctetString::new(bytes))
    }
}

// OctetStringRef: serialize only (borrowed)
#[cfg(feature = "serde")]
impl<'a> serde::Serialize for OctetStringRef<'a> {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(&crate::serde_impl::bytes_to_hex(self.as_bytes()))
    }
}

// BitString: {"bytes": "<hex>", "unused_bits": <n>}
#[cfg(feature = "serde")]
impl serde::Serialize for BitString {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        use serde::ser::SerializeStruct;
        let mut st = s.serialize_struct("BitString", 2)?;
        st.serialize_field("bytes", &crate::serde_impl::bytes_to_hex(self.as_bytes()))?;
        st.serialize_field("unused_bits", &self.unused_bits())?;
        st.end()
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for BitString {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        struct BitStringVisitor;
        impl<'de> serde::de::Visitor<'de> for BitStringVisitor {
            type Value = BitString;
            fn expecting(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
                write!(
                    f,
                    "a BitString with \"bytes\" (hex) and \"unused_bits\" fields"
                )
            }
            fn visit_map<A: serde::de::MapAccess<'de>>(
                self,
                mut map: A,
            ) -> Result<BitString, A::Error> {
                let mut bytes_hex: Option<String> = None;
                let mut unused_bits: Option<u8> = None;
                while let Some(key) = map.next_key::<String>()? {
                    match key.as_str() {
                        "bytes" => bytes_hex = Some(map.next_value()?),
                        "unused_bits" => unused_bits = Some(map.next_value()?),
                        _ => {
                            let _ = map.next_value::<serde::de::IgnoredAny>()?;
                        }
                    }
                }
                let bytes_hex =
                    bytes_hex.ok_or_else(|| serde::de::Error::missing_field("bytes"))?;
                let unused_bits =
                    unused_bits.ok_or_else(|| serde::de::Error::missing_field("unused_bits"))?;
                let bytes = crate::serde_impl::hex_to_bytes::<A::Error>(&bytes_hex)?;
                BitString::new(bytes, unused_bits)
                    .map_err(|_| serde::de::Error::custom("invalid BitString"))
            }
        }
        d.deserialize_map(BitStringVisitor)
    }
}

// BitStringRef: serialize only (borrowed)
#[cfg(feature = "serde")]
impl<'a> serde::Serialize for BitStringRef<'a> {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        use serde::ser::SerializeStruct;
        let mut st = s.serialize_struct("BitString", 2)?;
        st.serialize_field("bytes", &crate::serde_impl::bytes_to_hex(self.as_bytes()))?;
        st.serialize_field("unused_bits", &self.unused_bits())?;
        st.end()
    }
}

// Text string types: serialize as plain strings
#[cfg(feature = "serde")]
impl serde::Serialize for Utf8String {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(self.as_str())
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for Utf8String {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = <String as serde::Deserialize<'de>>::deserialize(d)?;
        Ok(Utf8String::new(v))
    }
}

#[cfg(feature = "serde")]
impl<'a> serde::Serialize for Utf8StringRef<'a> {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(self.as_str())
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for PrintableString {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(self.as_str())
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for PrintableString {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = <String as serde::Deserialize<'de>>::deserialize(d)?;
        PrintableString::new(v).map_err(|_| serde::de::Error::custom("invalid PrintableString"))
    }
}

#[cfg(feature = "serde")]
impl<'a> serde::Serialize for PrintableStringRef<'a> {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(self.as_str())
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for IA5String {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(self.as_str())
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for IA5String {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = <String as serde::Deserialize<'de>>::deserialize(d)?;
        IA5String::new(v).map_err(|_| serde::de::Error::custom("invalid IA5String"))
    }
}

#[cfg(feature = "serde")]
impl<'a> serde::Serialize for IA5StringRef<'a> {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(self.0)
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for NumericString {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(self.as_str())
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for NumericString {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = <String as serde::Deserialize<'de>>::deserialize(d)?;
        NumericString::new(v).map_err(|_| serde::de::Error::custom("invalid NumericString"))
    }
}

// TeletexString: arbitrary bytes, hex-encoded
#[cfg(feature = "serde")]
impl serde::Serialize for TeletexString {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(&crate::serde_impl::bytes_to_hex(self.as_bytes()))
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for TeletexString {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let hex = <String as serde::Deserialize<'de>>::deserialize(d)?;
        let bytes = crate::serde_impl::hex_to_bytes::<D::Error>(&hex)?;
        Ok(TeletexString::new(bytes))
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for VisibleString {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(self.as_str())
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for VisibleString {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = <String as serde::Deserialize<'de>>::deserialize(d)?;
        VisibleString::new(v).map_err(|_| serde::de::Error::custom("invalid VisibleString"))
    }
}

// GeneralString: arbitrary bytes, hex-encoded
#[cfg(feature = "serde")]
impl serde::Serialize for GeneralString {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(&crate::serde_impl::bytes_to_hex(self.as_bytes()))
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for GeneralString {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let hex = <String as serde::Deserialize<'de>>::deserialize(d)?;
        let bytes = crate::serde_impl::hex_to_bytes::<D::Error>(&hex)?;
        Ok(GeneralString::new(bytes))
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for UniversalString {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(self.as_str())
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for UniversalString {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = <String as serde::Deserialize<'de>>::deserialize(d)?;
        Ok(UniversalString::new(v))
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for BmpString {
    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(&self.0)
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for BmpString {
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let v = <String as serde::Deserialize<'de>>::deserialize(d)?;
        BmpString::new(v).map_err(|_| serde::de::Error::custom("invalid BmpString"))
    }
}