speed up bounds-checked element access and cache vector lengths (#1511)

* speed up bounds-checked element access and cache vector lengths

Closes #1510.

* update NEWS

* keep vector and matrix layouts unchanged

Caching the length in proxy_cache and the column count in Matrix added
data members, changing the layout of List, CharacterVector and Matrix.
Packages pass these by reference across shared libraries compiled
against different Rcpp versions: rust hands a List to revdbayes through
an XPtr function pointer, and lite, threshr and evmissing reach the same
path. In the 2026-10-06 reverse-dependency run revdbayes read a size
that rust never wrote and failed name lookup with 'Index out of bounds'.

ncol() is now derived from the cached length and nrow(), and proxy_cache
reads the length on demand; only the cold warning helper and the cached
atomic-vector length remain.

* update copyright headers

Author: kevinushey

ChangeLog

@@ -1,3 +1,20 @@
+2026-10-12  Kevin Ushey <kevinushey@gmail.com>
+
+	* inst/include/Rcpp/vector/traits.h: Update copyright
+	* inst/include/Rcpp/vector/Vector.h: Idem
+	* inst/include/Rcpp/vector/Matrix.h: Idem
+
+2026-09-30  Kevin Ushey <kevinushey@gmail.com>
+
+	* inst/include/Rcpp/vector/traits.h: Move the out-of-bounds warning into
+	a cold, out-of-line helper; add get_size() to the vector caches
+	* inst/include/Rcpp/vector/Vector.h: Return the length cached by
+	r_vector_cache from size() and length() rather than calling
+	Rf_xlength() each time
+	* inst/include/Rcpp/vector/Matrix.h: Derive ncol() from the cached
+	length and nrow() instead of reading the dim attribute; document that
+	no data members may be added, as the layout is shared across packages
+
 2026-09-22  Iñaki Ucar <iucar@fedoraproject.org>
 
 	* inst/include/Rcpp/sugar/matrix/col.h: Fix Col constructor using ncol()

inst/NEWS.Rd

@@ -27,6 +27,12 @@
       warnings (Iñaki in \ghpr{1508} closing \ghit{1497})
       \item The \code{col} constructor now uses \code{nrow} in an
       initialization (Iñaki in \ghpr{1509})
+      \item Bounds-checked element access is faster, \code{size()} of
+      atomic vectors uses the cached length, and \code{ncol()} no longer
+      reads the \code{dim} attribute; object layouts are unchanged, as
+      packages such as \pkg{rust} and \pkg{revdbayes} exchange Rcpp
+      objects across shared libraries (Kevin in \ghpr{1511} closing
+      \ghit{1510})
     }
     \item Changes in Rcpp Documentation:
     \itemize{

inst/include/Rcpp/vector/Matrix.h

@@ -3,7 +3,7 @@
 // Matrix.h: Rcpp R/C++ interface class library -- matrices
 //
 // Copyright (C) 2010 - 2025 Dirk Eddelbuettel and Romain Francois
-// Copyright (C) 2026        Dirk Eddelbuettel, Romain Francois and Iñaki Ucar
+// Copyright (C) 2026        Dirk Eddelbuettel, Romain Francois, Kevin Ushey and Iñaki Ucar
 //
 // This file is part of Rcpp.
 //
@@ -27,6 +27,10 @@ namespace Rcpp{
 
 template <int RTYPE, template <class> class StoragePolicy = PreserveStorage >
 class Matrix : public Vector<RTYPE, StoragePolicy>, public MatrixBase<RTYPE, true, Matrix<RTYPE,StoragePolicy> > {
+    // The only data member. Packages pass Rcpp objects by reference across
+    // shared-library boundaries (e.g. rust calls into revdbayes through XPtr
+    // function pointers), and the two sides may have been compiled against
+    // different Rcpp versions. Adding a member changes the layout they share.
     int nrows ;
 
 public:
@@ -92,14 +96,17 @@ class Matrix : public Vector<RTYPE, StoragePolicy>, public MatrixBase<RTYPE, tru
 
     explicit Matrix( const no_init_matrix& obj) : VECTOR(Rf_allocMatrix(RTYPE, obj.nrow(), obj.ncol())), nrows(obj.nrow()) {}
 
+    // A matrix has exactly nrow * ncol elements, so the column count follows
+    // from the (cached) length without reading the dim attribute. Only an
+    // empty matrix, which may still have columns, needs the attribute.
     inline int ncol() const {
-        return VECTOR::dims()[1];
+        return nrows == 0 ? VECTOR::dims()[1] : static_cast<int>( VECTOR::size() / nrows ) ;
     }
     inline int nrow() const {
         return nrows ;
     }
     inline int cols() const {
-        return VECTOR::dims()[1];
+        return ncol() ;
     }
     inline int rows() const {
         return nrows ;

inst/include/Rcpp/vector/Vector.h

@@ -1,7 +1,7 @@
 // Vector.h: Rcpp R/C++ interface class library -- vectors
 //
 // Copyright (C) 2010 - 2025  Dirk Eddelbuettel and Romain Francois
-// Copyright (C) 2026         Dirk Eddelbuettel, Romain Francois and Iñaki Ucar
+// Copyright (C) 2026         Dirk Eddelbuettel, Romain Francois, Kevin Ushey and Iñaki Ucar
 //
 // This file is part of Rcpp.
 //
@@ -263,17 +263,17 @@ class Vector :
     #endif
 
     /**
-     * the length of the vector, uses Rf_xlength
+     * the length of the vector, as cached by update()
      */
     inline R_xlen_t length() const {
-        return ::Rf_xlength( Storage::get__() ) ;
+        return cache.get_size() ;
     }
 
     /**
      * alias of length
      */
     inline R_xlen_t size() const {
-        return ::Rf_xlength( Storage::get__() ) ;
+        return cache.get_size() ;
     }
 
     /**

inst/include/Rcpp/vector/traits.h

@@ -1,7 +1,8 @@
 
 // traits.h: Rcpp R/C++ interface class library -- support traits for vector
 //
-// Copyright (C) 2010 - 2026 Dirk Eddelbuettel and Romain Francois
+// Copyright (C) 2010 - 2025 Dirk Eddelbuettel and Romain Francois
+// Copyright (C) 2026        Dirk Eddelbuettel, Romain Francois and Kevin Ushey
 //
 // This file is part of Rcpp.
 //
@@ -24,6 +25,16 @@
 namespace Rcpp{
 namespace traits{
 
+	// Kept out of line and marked cold so that the (almost never taken)
+	// warning path doesn't bloat element access and block optimization of
+	// hot loops, e.g. in sugar expressions.
+#if defined(__GNUC__)
+	__attribute__((noinline, cold))
+#endif
+	inline void warn_index_out_of_bounds(R_xlen_t i, R_xlen_t size) {
+		warning("subscript out of bounds (index %s >= vector size %s)", i, size); // #nocov
+	}
+
 	template <int RTYPE, template <class> class StoragePolicy = PreserveStorage >
 	class r_vector_cache{
 	public:
@@ -38,11 +49,12 @@ namespace traits{
 
 		inline void update( const VECTOR& v ) {
 			start = ::Rcpp::internal::r_vector_start<RTYPE>(v) ;
-			size = v.size();
+			size = ::Rf_xlength(v.get__());
 		}
 
 		inline iterator get() const { return start; }
 		inline const_iterator get_const() const { return start; }
+		inline R_xlen_t get_size() const { return size; }
 
 		inline proxy ref() { check_index(0); return start[0] ;}
 		inline proxy ref(R_xlen_t i) { check_index(i); return start[i] ; }
@@ -55,7 +67,7 @@ namespace traits{
 		void check_index(R_xlen_t i) const {
 #ifndef RCPP_NO_BOUNDS_CHECK
 			if (i >= size) {
-				warning("subscript out of bounds (index %s >= vector size %s)", i, size); // #nocov
+				warn_index_out_of_bounds(i, size); // #nocov
 			}
 #endif
 		}
@@ -80,6 +92,10 @@ namespace traits{
 		}
 		inline iterator get() const { return iterator( proxy(*p, 0 ) ) ;}
 		inline const_iterator get_const() const { return const_iterator( const_proxy(*p, 0) ) ; }
+		// Not cached: a size member here would change the layout of List and
+		// CharacterVector, which packages pass by reference across
+		// shared-library boundaries (see the note in Matrix.h).
+		inline R_xlen_t get_size() const { return ::Rf_xlength(p->get__()); }
 
 		inline proxy ref() { check_index(0); return proxy(*p,0) ; }
 		inline proxy ref(R_xlen_t i) { check_index(i); return proxy(*p,i);}
@@ -92,8 +108,9 @@ namespace traits{
 
 		void check_index(R_xlen_t i) const {
 #ifndef RCPP_NO_BOUNDS_CHECK
-			if (i >= p->size()) {
-				warning("subscript out of bounds (index %s >= vector size %s)", i, p->size()); // #nocov
+			R_xlen_t size = get_size() ;
+			if (i >= size) {
+				warn_index_out_of_bounds(i, size); // #nocov
 			}
 #endif
 		}