Add CSI subparameter support

This adds support for CSI subparameters like `\x1b[38:2:255:0:255m`,
which allows the combination of truecolor SGR commands together with
other SGR parameters like bold text, without any ambiguity.

This implements subparameters by storing them in a list together with
all other parameters and having a separate slice to indicate which
parameter is a subparameter and how long the subparameter list is. This
allows for static memory allocation and good performance while still
having the option for dynamic sizing of the parameters. Since the
subparameters are now also counted as parameters, the number of allowed
parameters has been increased from `16` to `32`.

Since the existing structures combine the handling of parameters for CSI
and DCS escape sequences, it is now also possible for DCS parameters to
have subparameters, even though that is currently never used.
Considering that DCS is rarely supported by terminal emulators, handling
these separately would likely just cause unnecessary issues. The
performance should also be better by using this existing subparam
structure rather than having two separate structures for DCS and CSI
parameters.

The only API provided for accessing the list of parameters is using an
iterator, this is intentional to make the internal structure clear and
allow for easy optimizations downstream. Since it makes little sense to
access parameters out of order, this limitation should not have any
negative effects on performance. The main drawback is that direct access
to the first parameter while ignoring all other subparameters is less
efficient, since it requires indexing a slice after iterating to the
element. However while this is often useful, it's mostly done for the
first few parameters which significantly reduces the overhead to a
negligible amount. At the same time this forces people to support
subparameters or at least consider their existence, which should make it
more difficult to implement things improperly downstream.

Fixes #22.

1 files changed, 142 insertions, 0 deletions

diff --git a/src/params.rs b/src/params.rs
new file mode 100644
index 0000000..efa24cb
--- /dev/null
+++ b/src/params.rs
@@ -0,0 +1,142 @@
+//! Fixed size parameters list with optional subparameters.
+
+use core::fmt::{self, Debug, Formatter};
+
+pub(crate) const MAX_PARAMS: usize = 32;
+
+#[derive(Default)]
+pub struct Params {
+    /// Number of subparameters for each parameter.
+    ///
+    /// For each entry in the `params` slice, this stores the length of the param as number of
+    /// subparams at the same index as the param in the `params` slice.
+    ///
+    /// At the subparam positions the length will always be `0`.
+    subparams: [u8; MAX_PARAMS],
+
+    /// All parameters and subparameters.
+    params: [i64; MAX_PARAMS],
+
+    /// Number of suparameters in the current parameter.
+    current_subparams: u8,
+
+    /// Total number of parameters and subparameters.
+    len: usize,
+}
+
+impl Params {
+    /// Returns the number of parameters.
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.len
+    }
+
+    /// Returns `true` if there are no parameters present.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.len == 0
+    }
+
+    /// Returns an iterator over all parameters and subparameters.
+    #[inline]
+    pub fn iter(&self) -> ParamsIter<'_> {
+        ParamsIter::new(self)
+    }
+
+    /// Returns `true` if there is no more space for additional parameters.
+    #[inline]
+    pub(crate) fn is_full(&self) -> bool {
+        self.len == MAX_PARAMS
+    }
+
+    /// Clear all parameters.
+    #[inline]
+    pub(crate) fn clear(&mut self) {
+        self.current_subparams = 0;
+        self.len = 0;
+    }
+
+    /// Add an additional parameter.
+    #[inline]
+    pub(crate) fn push(&mut self, item: i64) {
+        self.subparams[self.len - self.current_subparams as usize] = self.current_subparams + 1;
+        self.params[self.len] = item;
+        self.current_subparams = 0;
+        self.len += 1;
+    }
+
+    /// Add an additional subparameter to the current parameter.
+    #[inline]
+    pub(crate) fn extend(&mut self, item: i64) {
+        self.params[self.len] = item;
+        self.current_subparams += 1;
+        self.len += 1;
+    }
+}
+
+impl<'a> IntoIterator for &'a Params {
+    type IntoIter = ParamsIter<'a>;
+    type Item = &'a [i64];
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.iter()
+    }
+}
+
+/// Immutable subparameter iterator.
+pub struct ParamsIter<'a> {
+    params: &'a Params,
+    index: usize,
+}
+
+impl<'a> ParamsIter<'a> {
+    fn new(params: &'a Params) -> Self {
+        Self { params, index: 0 }
+    }
+}
+
+impl<'a> Iterator for ParamsIter<'a> {
+    type Item = &'a [i64];
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.index >= self.params.len() {
+            return None;
+        }
+
+        // Get all subparameters for the current parameter.
+        let num_subparams = self.params.subparams[self.index];
+        let param = &self.params.params[self.index..self.index + num_subparams as usize];
+
+        // Jump to the next parameter.
+        self.index += num_subparams as usize;
+
+        Some(param)
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        let remaining = self.params.len() - self.index;
+        (remaining, Some(remaining))
+    }
+}
+
+impl Debug for Params {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        write!(f, "[")?;
+
+        for (i, param) in self.iter().enumerate() {
+            if i != 0 {
+                write!(f, ";")?;
+            }
+
+            for (i, subparam) in param.iter().enumerate() {
+                if i != 0 {
+                    write!(f, ":")?;
+                }
+
+                subparam.fmt(f)?;
+            }
+        }
+
+        write!(f, "]")
+    }
+}