document sugar operand lengths, lifetimes, and assignment

Author: kevinushey

ChangeLog

@@ -1,3 +1,30 @@
+2026-09-30  Kevin Ushey <kevinushey@gmail.com>
+
+	* inst/include/Rcpp/traits/sugar_operand.h: New trait for how sugar
+	expressions hold their operands: vectors by reference, and nested
+	expressions and views by value, so stored expressions don't dangle
+	* inst/include/Rcpp/traits/is_elementwise.h: New trait for whether a
+	sugar expression can be written in place into storage it may read from
+	* inst/include/Rcpp/sugar/tools/check_sizes.h: New helpers checking that
+	sugar operands, and vectors assigned into views, have matching lengths
+	* inst/include/RcppCommon.h: Include the above
+	* inst/include/Rcpp/sugar/sugar_forward.h: Idem
+	* inst/include/Rcpp/sugar/: Hold operands via sugar_operand, declare
+	elementwise operands, and check operand lengths
+	* inst/include/Rcpp/stats/dpq/dpq.h: Idem
+	* inst/include/Rcpp/sugar/block/SugarBlock_3.h: Also fix the type of the
+	third operand
+	* inst/include/Rcpp/vector/Vector.h: Evaluate sugar expressions that
+	aren't elementwise before assigning them in place
+	* inst/include/Rcpp/vector/RangeIndexer.h: Idem, and check lengths
+	* inst/include/Rcpp/vector/MatrixColumn.h: Idem
+	* inst/include/Rcpp/vector/MatrixRow.h: Idem
+	* inst/include/Rcpp/vector/MatrixBase.h: Add a const get_ref()
+	* inst/tinytest/cpp/sugar_expressions.cpp: New tests
+	* inst/tinytest/test_sugar.R: Idem
+	* vignettes/rmd/Rcpp-sugar.Rmd: Document operand lengths, storing
+	expressions, and assignment
+
 2026-09-22  Iñaki Ucar <iucar@fedoraproject.org>
 
 	* inst/include/Rcpp/sugar/matrix/col.h: Fix Col constructor using ncol()

vignettes/rmd/Rcpp-sugar.Rmd

@@ -191,7 +191,8 @@ arithmetic expression must be of the same type (for example they should be both
 
 The lhs and the rhs can either have the same size or one of them could
 be a primitive value of the appropriate type, for example adding a
-`NumericVector` and a `double`.
+`NumericVector` and a `double`. Unlike \proglang{R}, \sugar does not recycle
+vectors of different sizes; see the section on expressions and assignment.
 
 ## Binary logical operators
 
@@ -518,6 +519,69 @@ functions (\textsl{i.e.} you) should place an \code{RNGScope} at the
 appropriate level of your code.
 
 
+# Expressions and assignment
+
+\sugar expressions are evaluated lazily: `x + y` builds an object describing
+the computation, and its elements are only computed when the expression is
+assigned to a vector or otherwise consumed, for example by `sum()`.
+
+## Operand lengths
+
+Unlike \proglang{R}, \sugar does not recycle: the vectors combined by an
+expression must all have the same length, and an error is signalled
+otherwise. Likewise, a vector assigned into a range, row or column (as in
+`m(_, 0) = x`) must have the length of that target. Single values, like the
+`2.0` in `x + 2.0`, can be combined with vectors of any length.
+
+## Storing expressions
+
+An expression holds the vectors it reads by reference, and any nested
+expressions by value. It can be stored, for example in an `auto` variable,
+and evaluated later, as long as the vectors it reads are still alive:
+
+```cpp
+NumericVector x, y;
+
+// fine: x and y outlive e
+auto e = x * 2.0 + y;
+NumericVector z = e;
+```
+
+An expression reading from a temporary vector, however, has to be
+evaluated in the statement that creates it:
+
+```cpp
+// wrong: the clone is destroyed at the end of
+// the statement, while e still refers to it
+auto e = clone(x) + 1.0;
+
+// fine
+NumericVector z = clone(x) + 1.0;
+```
+
+## Assignment
+
+Assigning an expression to an existing vector of the same length writes the
+result into that vector's storage. As with any modification made through an
+\pkg{Rcpp} vector, this is visible through every other reference to the same
+\proglang{R} object, including the argument passed in from \proglang{R}:
+
+```cpp
+// [[Rcpp::export]]
+void twice(NumericVector x) {
+    // modifies the caller's vector
+    x = x * 2.0;
+}
+```
+
+When the lengths differ, a new vector is allocated instead.
+
+An expression may read from the vector it is assigned to, as in
+`x = rev(x)`. Expressions whose elements only depend on the corresponding
+elements of their operands (arithmetic, comparisons, mathematical functions,
+`ifelse()`, and so on) are written directly; others are first evaluated into
+a temporary vector.
+
 # Performance
 \label{sec:performance}
 
@@ -658,7 +722,7 @@ public:
         RESULT_R_TYPE>::type STORAGE;
 
     Sapply(const VEC& vec_, Function fun_) :
-        vec(vec_), fun(fun_){}
+        vec(vec_.get_ref()), fun(fun_){}
 
     inline STORAGE operator[]( int i ) const {
         return converter_type::get(fun(vec[i]));
@@ -669,7 +733,7 @@ public:
     }
 
 private:
-    const VEC& vec;
+    typename Rcpp::traits::sugar_operand<VEC>::type vec;
     Function fun;
 };
 
@@ -801,18 +865,22 @@ is the manifestation of the _CRTP_.
 
 
 The constructor of the `Sapply` class template is straightforward, it
-simply consists of holding the reference to the input expression and the
-function.
+simply consists of holding the input expression and the function.
 
 ```cpp
 Sapply(const VEC& vec_, Function fun_):
-    vec(vec_), fun(fun_){}
+    vec(vec_.get_ref()), fun(fun_){}
 
 private:
-    const VEC& vec;
+    typename Rcpp::traits::sugar_operand<VEC>::type vec;
     Function fun;
 ```
 
+The input is held through `sugar_operand`: by reference when it is a vector,
+and by value when it is itself a \sugar expression. Those are typically
+temporaries, so holding them by reference would leave `Sapply` referring to
+destroyed objects once the statement that created it ends.
+
 ### Implementation
 
 The indexing operator and the `size` member function is what
@@ -830,6 +898,13 @@ inline int size() const {
 }
 ```
 
+Expressions whose $i^{\text{th}}$ element only depends on the
+$i^{\text{th}}$ elements of their operands can say so by declaring
+`typedef Rcpp::traits::elementwise_operands<VEC> rcpp_elementwise`, which
+lets them be written in place when assigned to one of those operands.
+`Sapply` does not, since the function it applies may read any element of
+the vector being assigned to.
+
 # Summary
 
 TBD