//! read.rs --- sxp reader

 use crate::{err::ErrorCode, Error, Result};

 use alloc::vec::Vec;

 use core::{char, cmp, ops::Deref, str};

 #[cfg(feature = "std")]

 use crate::io;

 #[cfg(feature = "std")]

 use crate::iter::LineColIterator;

 /// Trait used by the deserializer for iterating over input. This is manually

 /// "specialized" for iterating over &[u8]. Once feature(specialization) is

 /// stable we can use actual specialization.

 //  TODO 2023-07-14: should we use specialization anyways? we are on

 //  nightly 99% of the time for better or worse

 pub trait Read<'de> {

   #[doc(hidden)]

   fn next(&mut self) -> Result<Option<u8>>;

   #[doc(hidden)]

   fn peek(&mut self) -> Result<Option<u8>>;

   /// Only valid after a call to peek(). Discards the peeked byte.

   #[doc(hidden)]

   fn discard(&mut self);

   /// Position of the most recent call to next().

   ///

   /// The most recent call was probably next() and not peek(), but this method

   /// should try to return a sensible result if the most recent call was

   /// actually peek() because we don't always know.

   ///

   /// Only called in case of an error, so performance is not important.

   #[doc(hidden)]

   fn position(&self) -> Position;

   /// Position of the most recent call to peek().

   ///

   /// The most recent call was probably peek() and not next(), but this method

   /// should try to return a sensible result if the most recent call was

   /// actually next() because we don't always know.

   ///

   /// Only called in case of an error, so performance is not important.

   #[doc(hidden)]

   fn peek_position(&self) -> Position;

   /// Offset from the beginning of the input to the next byte that would be

   /// returned by next() or peek().

   #[doc(hidden)]

   fn byte_offset(&self) -> usize;

   /// Assumes the previous byte was a quotation mark. Parses an escaped

   /// string until the next quotation mark using the given scratch space if

   /// necessary. The scratch space is initially empty.

   #[doc(hidden)]

   fn parse_str<'s>(

     &'s mut self,

     scratch: &'s mut Vec<u8>,

   ) -> Result<Reference<'de, 's, str>>;

   /// Assumes the previous byte was a quotation mark. Parses an escaped

   /// string until the next quotation mark using the given scratch space if

   /// necessary. The scratch space is initially empty.

   ///

   /// This function returns the raw bytes in the string with escape sequences

   /// expanded but without performing unicode validation.

   #[doc(hidden)]

   fn parse_str_raw<'s>(

     &'s mut self,

     scratch: &'s mut Vec<u8>,

   ) -> Result<Reference<'de, 's, [u8]>>;

   /// Assumes the previous byte was a quotation mark. Parses a

   /// string until the next quotation mark but discards the data.

   #[doc(hidden)]

   fn ignore_str(&mut self) -> Result<()>;

   /// Assumes the previous byte was a hex escape sequnce ('\u') in a string.

   /// Parses next hexadecimal sequence.

   #[doc(hidden)]

   fn decode_hex_escape(&mut self) -> Result<u16>;

   /// Whether StreamDeserializer::next needs to check the failed flag. True

   /// for IoRead, false for StrRead and SliceRead which can track failure by

   /// truncating their input slice to avoid the extra check on every next

   /// call.

   #[doc(hidden)]

   const SHOULD_EARLY_RETURN_IF_FAILED: bool;

   /// Mark a persistent failure of StreamDeserializer, either by setting the

   /// flag or by truncating the input data.

   #[doc(hidden)]

   fn set_failed(&mut self, failed: &mut bool);

 }

 pub struct Position {

   pub line: usize,

   pub column: usize,

 }

 pub enum Reference<'b, 'c, T>

 where

   T: ?Sized + 'static,

 {

   Borrowed(&'b T),

   Copied(&'c T),

 }

 impl<'b, 'c, T> Deref for Reference<'b, 'c, T>

 where

   T: ?Sized + 'static,

 {

   type Target = T;

   fn deref(&self) -> &Self::Target {

     match *self {

       Reference::Borrowed(b) => b,

       Reference::Copied(c) => c,

     }

   }

 }

 /// SXP input source that reads from a std::io input stream.

 #[cfg(feature = "std")]

 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]

 pub struct IoRead<R>

 where

   R: io::Read,

 {

   iter: LineColIterator<io::Bytes<R>>,

   /// Temporary storage of peeked byte.

   ch: Option<u8>,

 }

 /// SXP input source that reads from a slice of bytes.

 //

 // This is more efficient than other iterators because peek() can be read-only

 // and we can compute line/col position only if an error happens.

 pub struct SliceRead<'a> {

   slice: &'a [u8],

   /// Index of the *next* byte that will be returned by next() or peek().

   index: usize,

 }

 /// SXP input source that reads from a UTF-8 string.

 //

 // Able to elide UTF-8 checks by assuming that the input is valid UTF-8.

 pub struct StrRead<'a> {

   delegate: SliceRead<'a>,

 }

 #[cfg(feature = "std")]

 impl<R> IoRead<R>

 where

   R: io::Read,

 {

   /// Create a SXP input source to read from a std::io input stream.

   pub fn new(reader: R) -> Self {

     IoRead {

       iter: LineColIterator::new(reader.bytes()),

       ch: None,

     }

   }

 }

 #[cfg(feature = "std")]

 impl<R> IoRead<R>

 where

   R: io::Read,

 {

   fn parse_str_bytes<'s, T, F>(

     &'s mut self,

     scratch: &'s mut Vec<u8>,

     validate: bool,

     result: F,

   ) -> Result<T>

   where

     T: 's,

     F: FnOnce(&'s Self, &'s [u8]) -> Result<T>,

   {

     loop {

       let ch = e!(next_or_eof(self));

       if !ESCAPE[ch as usize] {

         scratch.push(ch);

         continue;

       }

       match ch {

         b'"' => {

           return result(self, scratch);

         }

         b'\\' => {

           e!(parse_escape(self, validate, scratch));

         }

         _ => {

           if validate {

             return error(self, ErrorCode::ControlCharacterWhileParsingString);

           }

           scratch.push(ch);

         }

       }

     }

   }

 }

 #[cfg(feature = "std")]

 impl<'de, R> Read<'de> for IoRead<R>

 where

   R: io::Read,

 {

   #[inline]

   fn next(&mut self) -> Result<Option<u8>> {

     match self.ch.take() {

       Some(ch) => Ok(Some(ch)),

       None => match self.iter.next() {

         Some(Err(err)) => Err(Error::io(err)),

         Some(Ok(ch)) => Ok(Some(ch)),

         None => Ok(None),

       },

     }

   }

   #[inline]

   fn peek(&mut self) -> Result<Option<u8>> {

     match self.ch {

       Some(ch) => Ok(Some(ch)),

       None => match self.iter.next() {

         Some(Err(err)) => Err(Error::io(err)),

         Some(Ok(ch)) => {

           self.ch = Some(ch);

           Ok(self.ch)

         }

         None => Ok(None),

       },

     }

   }

   #[inline]

   fn discard(&mut self) {

     self.ch = None;

   }

   fn position(&self) -> Position {

     Position {

       line: self.iter.line(),

       column: self.iter.col(),

     }

   }

   fn peek_position(&self) -> Position {

     // The LineColIterator updates its position during peek() so it has the

     // right one here.

     self.position()

   }

   fn byte_offset(&self) -> usize {

     match self.ch {

       Some(_) => self.iter.byte_offset() - 1,

       None => self.iter.byte_offset(),

     }

   }

   fn parse_str<'s>(

     &'s mut self,

     scratch: &'s mut Vec<u8>,

   ) -> Result<Reference<'de, 's, str>> {

     self

       .parse_str_bytes(scratch, true, as_str)

       .map(Reference::Copied)

   }

   fn parse_str_raw<'s>(

     &'s mut self,

     scratch: &'s mut Vec<u8>,

   ) -> Result<Reference<'de, 's, [u8]>> {

     self

       .parse_str_bytes(scratch, false, |_, bytes| Ok(bytes))

       .map(Reference::Copied)

   }

   fn ignore_str(&mut self) -> Result<()> {

     loop {

       let ch = e!(next_or_eof(self));

       if !ESCAPE[ch as usize] {

         continue;

       }

       match ch {

         b'"' => {

           return Ok(());

         }

         b'\\' => {

           e!(ignore_escape(self));

         }

         _ => {

           return error(self, ErrorCode::ControlCharacterWhileParsingString);

         }

       }

     }

   }

   fn decode_hex_escape(&mut self) -> Result<u16> {

     let mut n = 0;

     for _ in 0..4 {

       match decode_hex_val(e!(next_or_eof(self))) {

         None => return error(self, ErrorCode::InvalidEscape),

         Some(val) => {

           n = (n << 4) + val;

         }

       }

     }

     Ok(n)

   }

   const SHOULD_EARLY_RETURN_IF_FAILED: bool = true;

   #[inline]

   #[cold]

   fn set_failed(&mut self, failed: &mut bool) {

     *failed = true;

   }

 }

 //////////////////////////////////////////////////////////////////////////////

 impl<'a> SliceRead<'a> {

   /// Create a SXP input source to read from a slice of bytes.

   pub fn new(slice: &'a [u8]) -> Self {

     SliceRead { slice, index: 0 }

   }

   fn position_of_index(&self, i: usize) -> Position {

     let mut position = Position { line: 1, column: 0 };

     for ch in &self.slice[..i] {

       match *ch {

         b'\n' => {

           position.line += 1;

           position.column = 0;

         }

         _ => {

           position.column += 1;

         }

       }

     }

     position

   }

   /// The big optimization here over IoRead is that if the string contains no

   /// backslash escape sequences, the returned &str is a slice of the raw SXP

   /// data so we avoid copying into the scratch space.

   fn parse_str_bytes<'s, T, F>(

     &'s mut self,

     scratch: &'s mut Vec<u8>,

     validate: bool,

     result: F,

   ) -> Result<Reference<'a, 's, T>>

   where

     T: ?Sized + 's,

     F: for<'f> FnOnce(&'s Self, &'f [u8]) -> Result<&'f T>,

   {

     // Index of the first byte not yet copied into the scratch space.

     let mut start = self.index;

     loop {

       while self.index < self.slice.len()

         && !ESCAPE[self.slice[self.index] as usize]

       {

         self.index += 1;

       }

       if self.index == self.slice.len() {

         return error(self, ErrorCode::EofWhileParsingString);

       }

       match self.slice[self.index] {

         b'"' => {

           if scratch.is_empty() {

             // Fast path: return a slice of the raw SXP without any

             // copying.

             let borrowed = &self.slice[start..self.index];

             self.index += 1;

             return result(self, borrowed).map(Reference::Borrowed);

           } else {

             scratch.extend_from_slice(&self.slice[start..self.index]);

             self.index += 1;

             return result(self, scratch).map(Reference::Copied);

           }

         }

         b'\\' => {

           scratch.extend_from_slice(&self.slice[start..self.index]);

           self.index += 1;

           e!(parse_escape(self, validate, scratch));

           start = self.index;

         }

         _ => {

           self.index += 1;