oxc_str 0.154.0

use std::{
    fmt::{self, Debug, Write},
    hash::{Hash, Hasher},
    iter::FusedIterator,
    marker::PhantomData,
    ptr::NonNull,
    slice, str,
};

use oxc_allocator::{Allocator, CloneIn, CloneInSemanticIds, Dummy, GetAllocator};

use crate::{Ident, JSChar, JSStrBuilder, Str, wtf8::*};

/// An immutable JavaScript string borrowed from source text or arena memory.
///
/// JavaScript strings can contain lone surrogates, which Rust's [`str`] cannot represent.
///
/// [`JSStr`] stores [canonical WTF-8]:
/// * Unicode scalar values use UTF-8.
/// * Lone surrogates use three bytes.
/// * Surrogate pairs use one four-byte supplementary character.
///
/// # Invariants
///
/// * The bytes are canonical WTF-8. In particular, a lead surrogate encoding
///   cannot be immediately followed by a trail surrogate encoding.
/// * `has_lone_surrogate` is `true` if and only if the bytes encode at least 1 lone surrogate.
///   When `false`, the bytes are valid UTF-8.
/// * The pointer references `len` initialized bytes, valid and immutable for `'a`.
/// * The byte length fits in `u32` and does not exceed `isize::MAX`.
///
/// All constructors maintain these invariants.
/// * [`as_bytes`] exposes the bytes read-only.
/// * [`from_bytes_unchecked`] re-borrows them under the same invariants.
///
/// Consumers read the value with [`as_str`], [`chars`], or [`encode_utf16`].
///
/// Equality uses the canonical bytes, and UTF-8 values hash like `str`. Ordering
/// by these bytes would differ from JavaScript's UTF-16 ordering, so `JSStr`
/// does not implement `Ord`.
///
/// ```
/// # use oxc_allocator::Allocator;
/// # let allocator = Allocator::new();
/// use oxc_str::JSStrBuilder;
///
/// let mut builder = JSStrBuilder::new_in(&&allocator);
/// builder.push_code_unit(0xD800);
/// builder.push('a');
/// let s = builder.into_js_str();
///
/// assert_eq!(s.as_str(), None);
/// assert_eq!(s.encode_utf16().collect::<Vec<_>>(), [0xD800, 0x61]);
/// ```
///
/// Borrowing source text does not extend its lifetime:
///
/// ```compile_fail
/// # use oxc_str::JSStr;
/// let value;
/// {
///     let source = String::from("hello");
///     value = JSStr::from(source.as_str());
/// }
/// println!("{value:?}");
/// ```
///
/// Arena-backed strings prevent resetting the arena while still in use:
///
/// ```compile_fail
/// # use oxc_allocator::Allocator;
/// # use oxc_str::JSStrBuilder;
/// let mut allocator = Allocator::new();
/// let mut builder = JSStrBuilder::new_in(&&allocator);
/// builder.push_code_unit(0xD800);
/// let value = builder.into_js_str();
/// allocator.reset();
/// println!("{value:?}");
/// ```
///
/// [`str`]: prim@str
/// [canonical WTF-8]: https://wtf-8.codeberg.page/
/// [`as_bytes`]: Self::as_bytes
/// [`from_bytes_unchecked`]: Self::from_bytes_unchecked
/// [`as_str`]: Self::as_str
/// [`chars`]: Self::chars
/// [`encode_utf16`]: Self::encode_utf16
#[derive(Clone, Copy)]
#[repr(C)]
pub struct JSStr<'a> {
    ptr: NonNull<u8>,
    len: u32,
    has_lone_surrogate: bool,
    _marker: PhantomData<&'a [u8]>,
}

impl JSStr<'static> {
    /// Return the empty string without allocating.
    #[inline]
    pub const fn empty() -> Self {
        Self::from_str("")
    }
}

impl<'a> JSStr<'a> {
    /// Borrow UTF-8 bytes. Their validity already proves the WTF-8 invariant.
    ///
    /// # Panics
    /// Panics if `value.len()` exceeds `u32::MAX`.
    #[inline]
    const fn from_str(value: &'a str) -> Self {
        assert!(value.len() <= u32::MAX as usize, "JavaScript string exceeds u32::MAX bytes");
        // SAFETY: `str` is UTF-8 (thus canonical WTF-8 without surrogates),
        // and its bytes are immutable and valid for `'a`. The length was checked.
        unsafe { Self::from_bytes_unchecked(value.as_bytes(), false) }
    }

    /// Copy UTF-8 text into arena.
    ///
    /// # Panics
    /// Panics if the byte length exceeds `u32::MAX`.
    #[inline]
    pub fn from_str_in(value: &str, allocator: &impl GetAllocator<'a>) -> Self {
        // Check the length before allocating or copying.
        JSStr::from(value).clone_in(allocator.allocator())
    }

    /// Concatenate JavaScript strings into an arena.
    ///
    /// Leading and trailing surrogates pair across string boundaries, including empty strings between them.
    /// Inputs are copied into the destination arena.
    ///
    /// # Panics
    /// Panics if the sum of input byte lengths exceeds `u32::MAX` or `isize::MAX`.
    #[inline]
    pub fn from_js_strs_array_in<const N: usize>(
        strings: [JSStr<'_>; N],
        allocator: &impl GetAllocator<'a>,
    ) -> Self {
        let capacity = strings
            .iter()
            .try_fold(0usize, |len, value| len.checked_add(value.len()))
            .expect("JavaScript string capacity overflow");
        let mut builder = JSStrBuilder::with_capacity_in(capacity, allocator);
        for value in strings {
            builder.push_js_str(value);
        }
        builder.into_js_str()
    }

    /// Borrow the value as UTF-8, or return `None` if it contains a lone surrogate.
    ///
    /// This checks the cached flag in O(1). It does not scan the bytes.
    #[inline]
    pub fn as_str(self) -> Option<&'a str> {
        if self.has_lone_surrogate() {
            None
        } else {
            // SAFETY: By `JSStr`'s invariant, canonical WTF-8 with no lone surrogates
            // is valid UTF-8
            Some(unsafe { str::from_utf8_unchecked(self.as_bytes()) })
        }
    }

    /// Return the byte length of the WTF-8 representation.
    ///
    /// Use [`len_utf16`] for JavaScript's string length.
    ///
    /// [`len_utf16`]: Self::len_utf16
    #[inline]
    pub const fn len(self) -> usize {
        self.len as usize
    }

    /// Return whether the string is empty.
    #[inline]
    pub const fn is_empty(self) -> bool {
        self.len == 0
    }

    /// Return whether the string contains a lone surrogate.
    ///
    /// This checks the cached flag in O(1). It does not scan the bytes.
    #[inline]
    pub const fn has_lone_surrogate(self) -> bool {
        self.has_lone_surrogate
    }

    /// Count UTF-16 code units, including lone surrogates.
    ///
    /// This scans the bytes in O(n) time.
    pub fn len_utf16(self) -> usize {
        // Every non-continuation byte starts one code point.
        // Four-byte code points contribute a second code unit.
        // Valid WTF-8 has no other bytes >= `FOUR_BYTE_TAG`, so this counts code units
        // without decoding individual points.
        self.as_bytes()
            .iter()
            .map(|&byte| {
                usize::from(byte & !CONT_MASK != CONT_TAG) + usize::from(byte >= FOUR_BYTE_TAG)
            })
            .sum()
    }

    /// Iterate code points. Paired surrogates yield one supplementary `JSChar`.
    #[inline]
    pub fn chars(self) -> impl FusedIterator<Item = JSChar> + Clone + 'a {
        JSChars { remaining: self.as_bytes() }
    }

    /// Iterate UTF-16 code units, preserving lone surrogates.
    #[inline]
    pub fn encode_utf16(self) -> impl FusedIterator<Item = u16> + Clone + 'a {
        EncodeUtf16 { chars: JSChars { remaining: self.as_bytes() }, pending: 0 }
    }

    /// Borrow the underlying canonical WTF-8 bytes.
    ///
    /// Together with [`has_lone_surrogate`], the bytes are a complete representation.
    /// Storage held outside an arena can keep them and convert back to a [`JSStr`]
    /// with [`from_bytes_unchecked`].
    ///
    /// [`has_lone_surrogate`]: Self::has_lone_surrogate
    /// [`from_bytes_unchecked`]: Self::from_bytes_unchecked
    #[inline]
    pub fn as_bytes(self) -> &'a [u8] {
        // SAFETY: `JSStr`'s pointer references `len` initialized bytes, valid
        // and immutable for `'a`, including the zero-length case.
        unsafe { slice::from_raw_parts(self.ptr.as_ptr(), self.len()) }
    }

    /// Borrow bytes whose encoding and metadata have already been established,
    /// such as bytes previously taken from [`as_bytes`] together with the lone surrogate flag.
    ///
    /// # SAFETY
    ///
    /// * `bytes` must be canonical WTF-8 - valid WTF-8 in which a lead surrogate encoding
    ///   is never followed by a trail surrogate encoding.
    /// * `has_lone_surrogate` must exactly describe whether they encode a lone surrogate.
    /// * `bytes.len()` must fit in `u32`.
    ///
    /// The `&[u8]` reference itself guarantees initialization, immutability, lifetime,
    /// and that `bytes.len()` cannot exceed `isize::MAX`.
    ///
    /// [`as_bytes`]: Self::as_bytes
    #[inline]
    #[expect(clippy::cast_possible_truncation, reason = "the caller guarantees the length fits")]
    pub const unsafe fn from_bytes_unchecked(bytes: &'a [u8], has_lone_surrogate: bool) -> Self {
        Self {
            ptr: NonNull::from_ref(bytes).cast(),
            len: bytes.len() as u32,
            has_lone_surrogate,
            _marker: PhantomData,
        }
    }
}

/// SAFETY: The only referenced storage is an immutable byte slice valid for `'a`.
/// `JSStr` exposes neither mutation nor an allocator reference.
unsafe impl Send for JSStr<'_> {}
/// SAFETY: Sharing `JSStr` only shares immutable bytes, as with `&[u8]`.
unsafe impl Sync for JSStr<'_> {}

impl<'a> From<&'a str> for JSStr<'a> {
    /// Borrow UTF-8 without allocating.
    ///
    /// # Panics
    /// Panics if `value.len()` exceeds `u32::MAX`.
    #[inline]
    fn from(value: &'a str) -> Self {
        Self::from_str(value)
    }
}

impl<'a> From<Str<'a>> for JSStr<'a> {
    #[inline]
    fn from(value: Str<'a>) -> Self {
        Self::from(value.as_str())
    }
}

impl<'a> From<Ident<'a>> for JSStr<'a> {
    #[inline]
    fn from(value: Ident<'a>) -> Self {
        Self::from(value.as_str())
    }
}

impl PartialEq for JSStr<'_> {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.as_bytes() == other.as_bytes()
    }
}

impl Eq for JSStr<'_> {}

impl PartialEq<str> for JSStr<'_> {
    #[inline]
    fn eq(&self, other: &str) -> bool {
        self.as_bytes() == other.as_bytes()
    }
}

impl PartialEq<&str> for JSStr<'_> {
    #[inline]
    fn eq(&self, other: &&str) -> bool {
        self == *other
    }
}

impl PartialEq<JSStr<'_>> for str {
    #[inline]
    fn eq(&self, other: &JSStr<'_>) -> bool {
        other == self
    }
}

impl PartialEq<JSStr<'_>> for &str {
    #[inline]
    fn eq(&self, other: &JSStr<'_>) -> bool {
        other == *self
    }
}

impl PartialEq<Ident<'_>> for JSStr<'_> {
    #[inline]
    fn eq(&self, other: &Ident<'_>) -> bool {
        self == other.as_str()
    }
}

impl PartialEq<JSStr<'_>> for Ident<'_> {
    #[inline]
    fn eq(&self, other: &JSStr<'_>) -> bool {
        other == self.as_str()
    }
}

impl Hash for JSStr<'_> {
    #[inline]
    fn hash<H: Hasher>(&self, state: &mut H) {
        // Match `str` hashing so UTF-8 values hash like `str` and `Str`.
        match self.as_str() {
            Some(value) => value.hash(state),
            None => self.as_bytes().hash(state),
        }
    }
}

impl Debug for JSStr<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_char('"')?;
        for c in self.chars() {
            if let Some(c) = c.to_char() {
                // `char::escape_debug` escapes a quote for `char` literals.
                // `str`'s `Debug` prints it plain, and this output is a string.
                if c == '\'' {
                    f.write_char(c)?;
                } else {
                    for escaped in c.escape_debug() {
                        f.write_char(escaped)?;
                    }
                }
            } else {
                write!(f, "\\u{:04x}", c.to_u32())?;
            }
        }
        f.write_char('"')
    }
}

impl<'new_alloc> CloneIn<'new_alloc> for JSStr<'_> {
    type Cloned = JSStr<'new_alloc>;

    #[inline]
    fn clone_in_impl(
        &self,
        _with_semantic_ids: CloneInSemanticIds,
        allocator: &'new_alloc Allocator,
    ) -> Self::Cloned {
        let bytes = allocator.alloc_slice_copy(self.as_bytes());
        // SAFETY: Copying identical bytes preserves canonical WTF-8, the
        // surrogate flag, and the u32 length bound. Storage belongs to the new arena.
        unsafe { JSStr::from_bytes_unchecked(bytes, self.has_lone_surrogate()) }
    }
}

impl<'a> Dummy<'a> for JSStr<'a> {
    #[inline]
    fn dummy(_allocator: &'a Allocator) -> Self {
        JSStr::empty()
    }
}

/// Iterator over [`JSChar`]s comprising a [`JSStr`].
//
// `remaining` is always canonical WTF-8 starting at a code-point boundary.
#[derive(Clone)]
struct JSChars<'a> {
    remaining: &'a [u8],
}

impl Iterator for JSChars<'_> {
    type Item = JSChar;

    #[inline]
    fn next(&mut self) -> Option<JSChar> {
        let (&first, rest) = self.remaining.split_first()?;
        let (value, len) = if first.is_ascii() {
            (u32::from(first), 0)
        } else {
            // SAFETY: `remaining` is complete, valid WTF-8 at a code-point boundary.
            // Its leading byte therefore determines how many continuation bytes are present.
            // Their bit patterns and the encoding's range restrictions guarantee a value <= 0x10_FFFF.
            unsafe {
                let second = u32::from(*rest.get_unchecked(0) & CONT_MASK);
                if first < THREE_BYTE_TAG {
                    ((u32::from(first & TWO_BYTE_MASK) << 6) | second, 1)
                } else {
                    let third = u32::from(*rest.get_unchecked(1) & CONT_MASK);
                    if first < FOUR_BYTE_TAG {
                        ((u32::from(first & THREE_BYTE_MASK) << 12) | (second << 6) | third, 2)
                    } else {
                        let fourth = u32::from(*rest.get_unchecked(2) & CONT_MASK);
                        let first = u32::from(first & FOUR_BYTE_MASK);
                        ((first << 18) | (second << 12) | (third << 6) | fourth, 3)
                    }
                }
            }
        };
        // SAFETY: The complete code point has `len` continuation bytes, as established above.
        // The suffix begins at the next code-point boundary.
        self.remaining = unsafe { rest.get_unchecked(len..) };
        // SAFETY: Decoding valid WTF-8 produces a code point <= 0x10_FFFF
        Some(unsafe { JSChar::from_u32_unchecked(value) })
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let len = self.remaining.len();
        (len.div_ceil(char::MAX_LEN_UTF8), Some(len))
    }
}

impl FusedIterator for JSChars<'_> {}

/// Iterator over `u16` code units comprising a [`JSStr`].
#[derive(Clone)]
struct EncodeUtf16<'a> {
    chars: JSChars<'a>,
    /// 0 when empty, otherwise a trailing surrogate (which cannot be 0).
    pending: u16,
}

impl Iterator for EncodeUtf16<'_> {
    type Item = u16;

    #[inline]
    #[expect(clippy::cast_possible_truncation, reason = "code units are masked or range-checked")]
    fn next(&mut self) -> Option<u16> {
        if self.pending != 0 {
            let trail = self.pending;
            self.pending = 0;
            return Some(trail);
        }
        let value = self.chars.next()?.to_u32();
        if value < SUPPLEMENTARY_MIN {
            Some(value as u16)
        } else {
            let offset = value - SUPPLEMENTARY_MIN;
            self.pending = (TRAIL_SURROGATE_MIN | (offset & SURROGATE_PAYLOAD_MASK)) as u16;
            Some((LEAD_SURROGATE_MIN | (offset >> 10)) as u16)
        }
    }
}

impl FusedIterator for EncodeUtf16<'_> {}

#[cfg(test)]
#[path = "js_str/tests.rs"]
mod tests;