From 32c2fc2701d599f4bbc741d780a1417a660dcd74 Mon Sep 17 00:00:00 2001
From: elvis <elvilio98@gmail.com>
Date: Mon, 19 May 2025 13:10:05 +0200
Subject: [PATCH] Adding documentation for classical.rs, modifying compute_step
 with pointers

---
 src/rsprocess/classical.rs    | 21 ++++++++++++++++-----
 src/rsprocess/grammar.lalrpop |  2 +-
 src/rsprocess/structure.rs    | 18 ++++++++++++++++++
 3 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/src/rsprocess/classical.rs b/src/rsprocess/classical.rs
index bc3fb3b..f56b793 100644
--- a/src/rsprocess/classical.rs
+++ b/src/rsprocess/classical.rs
@@ -1,13 +1,24 @@
+//! Definitions for the 'classical' mechanism for computation.
+//!
+//! This initial part allows to define the 'classical' mechanism to compute in a
+//! Reaction System (RS) Framework.
+//! The data is held in RSset or RSreaction, in the latter the reagents,
+//! inhibitors and products are held.
+
 use super::structure::{RSset, RSreaction};
 
-pub fn compute_step<'a>(current_state: &RSset<'a>, reaction: &RSreaction<'a>) -> RSset<'a> {
+/// Computes the result of a single reaction (if enabled returns the products)
+/// otherwise returns None.
+pub fn compute_step<'a>(current_state: &RSset<'a>, reaction: &'a RSreaction<'a>) -> Option<&'a RSset<'a>> {
     if reaction.enabled(current_state) {
-	reaction.products_clone()
+	Some(reaction.products())
     } else {
-	RSset::new()
+	None
     }
 }
 
-pub fn compute_all<'a>(current_state: &RSset<'a>, reactions: Vec<&RSreaction<'a>>) -> RSset<'a> {
-    reactions.iter().fold(RSset::new(), |acc, r| acc.union(&compute_step(current_state, r)))
+/// Computes the result of a series of reactions. Returns the union of all
+/// products.
+pub fn compute_all<'a>(current_state: &RSset<'a>, reactions: Vec<&'a RSreaction<'a>>) -> RSset<'a> {
+    reactions.iter().fold(RSset::new(), |acc, r| acc.union_option(compute_step(current_state, r)))
 }
diff --git a/src/rsprocess/grammar.lalrpop b/src/rsprocess/grammar.lalrpop
index 2e28bf0..e77030f 100644
--- a/src/rsprocess/grammar.lalrpop
+++ b/src/rsprocess/grammar.lalrpop
@@ -55,7 +55,7 @@ CTX_process: RSprocess<'input> = {
 			       next_process: Box::new(k)},
     "nil" => RSprocess::Nill,
     <identifier: Literal> =>
-	RSprocess::ConstantIdentifier{ identifier: identifier }
+	RSprocess::ConstantIdentifier{ identifier }
 };
 
 // ----- EnvironmentParser -----
diff --git a/src/rsprocess/structure.rs b/src/rsprocess/structure.rs
index f12f2e2..e6232be 100644
--- a/src/rsprocess/structure.rs
+++ b/src/rsprocess/structure.rs
@@ -40,12 +40,24 @@ impl<'a> RSset<'a> {
 	self.identifiers.is_disjoint(&b.identifiers)
     }
 
+    #[allow(dead_code)]
     pub fn union(&self, b: &RSset<'a>) -> RSset<'a> {
 	// TODO maybe find more efficient way
 	let mut ret: RSset = b.clone();
 	ret.identifiers.extend(self.identifiers.iter());
 	ret
     }
+
+    pub fn union_option(&self, b: Option<&RSset<'a>>) -> RSset<'a> {
+	if let Some(b) = b {
+	    // TODO maybe find more efficient way
+	    let mut ret: RSset = b.clone();
+	    ret.identifiers.extend(self.identifiers.iter());
+	    ret
+	} else {
+	    self.clone()
+	}
+    }
 }
 
 
@@ -61,6 +73,7 @@ pub struct RSreaction<'a> {
 }
 
 impl<'a> RSreaction<'a> {
+    #[allow(dead_code)]
     pub fn new() -> Self {
 	RSreaction{ reactants:   RSset::new(),
 		    inihibitors: RSset::new(),
@@ -78,9 +91,14 @@ impl<'a> RSreaction<'a> {
 	    && self.inihibitors.is_disjoint(current_state)
     }
 
+    #[allow(dead_code)]
     pub fn products_clone(&self) -> RSset<'a> {
 	self.products.clone()
     }
+
+    pub fn products(&self) -> &RSset<'a> {
+	&self.products
+    }
 }