Introduce TracePos type for trace positions (#273)

Many internal structures refer to trace positions; this is an important type of values. In the code, it is sometimes `u32`, sometimes `usize`. While such variables usually have "_pos" suffix, having a dedicated type does improve code with type guarantees.

crates/air-lib/interpreter-data/src/executed_state.rs

@@ -17,6 +17,8 @@
 mod impls;
 mod se_de;
 
+use crate::TracePos;
+
 use se_de::par_serializer;
 use se_de::sender_serializer;
 use serde::Deserialize;
@@ -82,7 +84,7 @@ pub enum Value {
 pub struct FoldSubTraceLore {
     /// Position of current value in a trace.
     #[serde(rename = "pos")]
-    pub value_pos: u32,
+    pub value_pos: TracePos,
 
     /// Descriptors of a subtrace that are corresponded to the current value. Technically, now
     /// it always contains two values, and Vec here is used to have a possibility to handle more
@@ -97,7 +99,7 @@ pub struct FoldSubTraceLore {
 pub struct SubTraceDesc {
     /// Start position in a trace of this subtrace.
     #[serde(rename = "pos")]
-    pub begin_pos: u32,
+    pub begin_pos: TracePos,
 
     /// Length of the subtrace.
     #[serde(rename = "len")]

crates/air-lib/interpreter-data/src/executed_state/impls.rs

@@ -59,9 +59,9 @@ impl CallResult {
 }
 
 impl SubTraceDesc {
-    pub fn new(begin_pos: usize, subtrace_len: usize) -> Self {
+    pub fn new(begin_pos: TracePos, subtrace_len: usize) -> Self {
         Self {
-            begin_pos: begin_pos as _,
+            begin_pos,
             subtrace_len: subtrace_len as _,
         }
     }

crates/air-lib/interpreter-data/src/interpreter_data.rs

@@ -14,16 +14,14 @@
  * limitations under the License.
  */
 
-use super::ExecutedState;
 use super::GlobalStreamGens;
 use super::RestrictedStreamGens;
 use super::DATA_FORMAT_VERSION;
+use crate::ExecutionTrace;
 use serde::Deserialize;
 use serde::Serialize;
 use std::ops::Deref;
 
-pub type ExecutionTrace = Vec<ExecutedState>;
-
 /// The AIR interpreter could be considered as a function
 /// f(prev_data: InterpreterData, current_data: InterpreterData, ... ) -> (result_data: InterpreterData, ...).
 /// This function receives prev and current data and produces a result data. All these data

crates/air-lib/interpreter-data/src/lib.rs

@@ -28,10 +28,14 @@
 mod executed_state;
 mod interpreter_data;
 mod stream_generations;
+mod trace;
+mod trace_pos;
 
 pub use executed_state::*;
 pub use interpreter_data::*;
 pub use stream_generations::*;
+pub use trace::*;
+pub use trace_pos::*;
 
 use once_cell::sync::Lazy;
 use std::str::FromStr;

crates/air-lib/interpreter-data/src/trace.rs

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2022 Fluence Labs Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+use super::ExecutedState;
+use crate::TracePos;
+use serde::Deserialize;
+use serde::Serialize;
+use std::ops::Deref;
+use std::ops::Index;
+use std::ops::IndexMut;
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct ExecutionTrace(Vec<ExecutedState>);
+
+impl ExecutionTrace {
+    pub fn get(&self, index: TracePos) -> Option<&ExecutedState> {
+        self.0.get(usize::from(index))
+    }
+
+    pub fn pop(&mut self) -> Option<ExecutedState> {
+        self.0.pop()
+    }
+
+    pub fn push(&mut self, value: ExecutedState) {
+        self.0.push(value);
+    }
+}
+
+impl Deref for ExecutionTrace {
+    type Target = [ExecutedState];
+
+    fn deref(&self) -> &[ExecutedState] {
+        &self.0
+    }
+}
+
+impl From<Vec<ExecutedState>> for ExecutionTrace {
+    fn from(vec: Vec<ExecutedState>) -> Self {
+        Self(vec)
+    }
+}
+
+impl Index<TracePos> for ExecutionTrace {
+    type Output = ExecutedState;
+
+    fn index(&self, index: TracePos) -> &Self::Output {
+        &self.deref()[usize::from(index)]
+    }
+}
+
+impl IndexMut<TracePos> for ExecutionTrace {
+    fn index_mut(&mut self, index: TracePos) -> &mut Self::Output {
+        &mut self.0[usize::from(index)]
+    }
+}
+
+impl PartialEq<Vec<ExecutedState>> for ExecutionTrace {
+    fn eq(&self, other: &Vec<ExecutedState>) -> bool {
+        &self.0 == other
+    }
+}

crates/air-lib/interpreter-data/src/trace_pos.rs

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2022 Fluence Labs Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+use serde::{Deserialize, Serialize};
+use std::{
+    fmt::{Debug, Display},
+    ops::{Add, AddAssign, Sub},
+};
+
+#[derive(Copy, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+#[repr(transparent)]
+pub struct TracePos(usize);
+
+impl TracePos {
+    pub fn checked_add(self, other: usize) -> Option<Self> {
+        self.0.checked_add(other).map(Self)
+    }
+}
+
+impl Debug for TracePos {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        Debug::fmt(&self.0, f)
+    }
+}
+
+impl Display for TracePos {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        Display::fmt(&self.0, f)
+    }
+}
+
+impl From<usize> for TracePos {
+    fn from(pos: usize) -> Self {
+        TracePos(pos)
+    }
+}
+
+impl From<TracePos> for usize {
+    fn from(pos: TracePos) -> Self {
+        pos.0
+    }
+}
+
+impl AddAssign<usize> for TracePos {
+    fn add_assign(&mut self, rhs: usize) {
+        self.0 += rhs;
+    }
+}
+
+impl Add<usize> for TracePos {
+    type Output = Self;
+
+    fn add(self, rhs: usize) -> Self::Output {
+        TracePos(self.0 + rhs)
+    }
+}
+
+impl Sub<usize> for TracePos {
+    type Output = Self;
+
+    fn sub(self, rhs: usize) -> Self::Output {
+        TracePos(self.0 - rhs)
+    }
+}
+
+impl Sub<TracePos> for TracePos {
+    type Output = usize;
+
+    fn sub(self, rhs: TracePos) -> Self::Output {
+        self.0 - rhs.0
+    }
+}