miden_core/stack/
inputs.rs

1use alloc::vec::Vec;
2use core::{ops::Deref, slice};
3
4use super::{
5    super::ZERO, ByteWriter, Felt, InputError, MIN_STACK_DEPTH, Serializable, get_num_stack_values,
6};
7use crate::utils::{ByteReader, Deserializable, DeserializationError};
8
9// STACK INPUTS
10// ================================================================================================
11
12/// Defines the initial state of the VM's operand stack.
13///
14/// The values in the struct are stored in the "stack order" - i.e., the last input is at the top
15/// of the stack (in position 0).
16#[derive(Clone, Debug, Default)]
17pub struct StackInputs {
18    elements: [Felt; MIN_STACK_DEPTH],
19}
20
21impl StackInputs {
22    // CONSTRUCTORS
23    // --------------------------------------------------------------------------------------------
24
25    /// Returns [StackInputs] from a list of values, reversing them into a stack.
26    ///
27    /// # Errors
28    /// Returns an error if the number of input values exceeds the allowed maximum.
29    pub fn new(mut values: Vec<Felt>) -> Result<Self, InputError> {
30        if values.len() > MIN_STACK_DEPTH {
31            return Err(InputError::InputLengthExceeded(MIN_STACK_DEPTH, values.len()));
32        }
33        values.reverse();
34        values.resize(MIN_STACK_DEPTH, ZERO);
35
36        Ok(Self { elements: values.try_into().unwrap() })
37    }
38
39    /// Attempts to create stack inputs from an iterator of integers.
40    ///
41    /// # Errors
42    /// Returns an error if:
43    /// - The values do not represent a valid field element.
44    /// - Number of values in the iterator exceeds the allowed maximum number of input values.
45    pub fn try_from_ints<I>(iter: I) -> Result<Self, InputError>
46    where
47        I: IntoIterator<Item = u64>,
48    {
49        let values = iter
50            .into_iter()
51            .map(|v| Felt::try_from(v).map_err(|e| InputError::NotFieldElement(v, e)))
52            .collect::<Result<Vec<_>, _>>()?;
53
54        Self::new(values)
55    }
56}
57
58impl Deref for StackInputs {
59    type Target = [Felt; MIN_STACK_DEPTH];
60
61    fn deref(&self) -> &Self::Target {
62        &self.elements
63    }
64}
65
66impl From<[Felt; MIN_STACK_DEPTH]> for StackInputs {
67    fn from(value: [Felt; MIN_STACK_DEPTH]) -> Self {
68        Self { elements: value }
69    }
70}
71
72impl<'a> IntoIterator for &'a StackInputs {
73    type Item = &'a Felt;
74    type IntoIter = slice::Iter<'a, Felt>;
75
76    fn into_iter(self) -> Self::IntoIter {
77        self.elements.iter()
78    }
79}
80
81impl IntoIterator for StackInputs {
82    type Item = Felt;
83    type IntoIter = core::array::IntoIter<Felt, 16>;
84
85    fn into_iter(self) -> Self::IntoIter {
86        self.elements.into_iter()
87    }
88}
89
90// SERIALIZATION
91// ================================================================================================
92
93impl Serializable for StackInputs {
94    fn write_into<W: ByteWriter>(&self, target: &mut W) {
95        let num_stack_values = get_num_stack_values(self);
96        target.write_u8(num_stack_values);
97        target.write_many(&self.elements[..num_stack_values as usize]);
98    }
99}
100
101impl Deserializable for StackInputs {
102    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
103        let num_elements = source.read_u8()?;
104
105        let mut elements = source.read_many::<Felt>(num_elements.into())?;
106        elements.reverse();
107
108        StackInputs::new(elements).map_err(|_| {
109            DeserializationError::InvalidValue(format!(
110                "number of stack elements should not be greater than {MIN_STACK_DEPTH}, but {num_elements} was found",
111            ))
112        })
113    }
114}
miden_core/stack/inputs.rs

miden_core/stack/
inputs.rs
