From e611e76ef849c55624839437691b23447485dcd8 Mon Sep 17 00:00:00 2001 From: Dirk Eddelbuettel Date: Tue, 16 Sep 2025 12:51:53 -0500 Subject: [PATCH] Minor documentation refresh for two utility functions --- ChangeLog | 6 +++++ R/RcppExports.R | 31 ++++++----------------- man/armadillo_set_seed.Rd | 43 ++++++++++++++------------------ man/armadillo_set_seed_random.Rd | 33 ------------------------ man/armadillo_version.Rd | 19 ++++++-------- src/RcppArmadillo.cpp | 34 +++++++------------------ 6 files changed, 50 insertions(+), 116 deletions(-) delete mode 100644 man/armadillo_set_seed_random.Rd diff --git a/ChangeLog b/ChangeLog index c0bc7225..88ec8d42 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2025-09-16 Dirk Eddelbuettel + + * src/RcppArmadillo.cpp: Refresh documentation for seed setting function + * man/armadillo_set_seed.Rd: Regenerated, also for *_random() variant + * man/armadillo_version.Rd: Regenerated + 2025-09-11 Dirk Eddelbuettel * README.md: Link to ldlasb2 repo and its 'benchmarks' writeup diff --git a/R/RcppExports.R b/R/RcppExports.R index 4c54e2e6..3033073e 100644 --- a/R/RcppExports.R +++ b/R/RcppExports.R @@ -14,37 +14,22 @@ armadillo_version <- function(single) { .Call(`_RcppArmadillo_armadillo_version`, single) } -#' Set the Armadillo Random Number Generator to a random value -#' -#' @details -#' Depending on whether RcppArmadillo was compiled for the C++98 standard -#' (currently the default) or for C++11 (optional), two different RNGs may be used. -#' This function resets either. For C++98, the R programming language's RNG is used. -#' For C++11, the RNG included in the \code{} library is used only when -#' \code{#define ARMA_USE_CXX11_RNG} is placed before \code{#include }. -#' Otherwise, the R programming language's RNG will be used. -#' @return The function is invoked for its side effect and has no return value. -#' @note This has been found to not work as espected in \pkg{RStudio} -#' as its code also uses the system RNG library. You may have to either -#' not run within \pkg{RStudio} or change your code to use a different RNG such -#' as the one from R. -#' @seealso The R documentation on its RNGs all of which are accessible via \pkg{Rcpp}. +#' @rdname armadillo_set_seed armadillo_set_seed_random <- function() { invisible(.Call(`_RcppArmadillo_armadillo_set_seed_random`)) } -#' Set the Armadillo Random Number Generator to the given value +#' @title Set the Armadillo Random Number Generator to given or random value #' #' @param val The seed used to initialize Armadillo's random number generator. #' @details -#' Depending on whether RcppArmadillo was compiled for the C++98 standard -#' (currently the default) or for C++11 (optional), two different RNGs may be used. -#' This function resets either. For C++98, the R programming language's RNG is used. -#' For C++11, the RNG included in the \code{} library is used only when -#' \code{#define ARMA_USE_CXX11_RNG} is placed before \code{#include }. -#' Otherwise, the R programming language's RNG will be used. +#' Armadillo can switch between two random number generator implementations depending +#' on the compilation standard used. Under normal circumstances RcppArmadillo will connect +#' Armadillo to the R random number generator which also implies that \code{set.seed()} +#' should be used from R. To use this function, one also needs to undefine \code{ARMA_RNG_ALT} +#' so that the Armadillo generators are used. #' @return The function is invoked for its side effect and has no return value. -#' @note This has been found to not work as espected in \pkg{RStudio} +#' @note This has been found to not work as expected in \pkg{RStudio} #' as its code also uses the system RNG library. You may have to either #' not run within \pkg{RStudio} or change your code to use a different RNG such #' as the one from R. diff --git a/man/armadillo_set_seed.Rd b/man/armadillo_set_seed.Rd index 4b65e5b0..998eb8e4 100644 --- a/man/armadillo_set_seed.Rd +++ b/man/armadillo_set_seed.Rd @@ -1,38 +1,33 @@ -\name{armadillo_set_seed} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RcppExports.R +\name{armadillo_set_seed_random} +\alias{armadillo_set_seed_random} \alias{armadillo_set_seed} -\title{Set the Armadillo Random Number Generator to the given value} +\title{Set the Armadillo Random Number Generator to given or random value} \usage{ +armadillo_set_seed_random() + armadillo_set_seed(val) } \arguments{ - \item{val}{The seed used to initialize Armadillo's random - number generator.} +\item{val}{The seed used to initialize Armadillo's random number generator.} } \value{ -The function is invoked for its side effect and has no -return value. -} -\description{ -Set the Armadillo Random Number Generator to the given -value +The function is invoked for its side effect and has no return value. } \details{ -Depending on whether RcppArmadillo was compiled for the C++98 standard -(currently the default) or for C++11 (optional), two different RNGs may be used. -This function resets either. For C++98, the R programming language's RNG is used. -For C++11, the RNG included in the \code{} library is used only when - \code{#define ARMA_USE_CXX11_RNG} is placed before \code{#include }. - Otherwise, the R programming language's RNG will be used. +Armadillo can switch between two random number generator implementations depending +on the compilation standard used. Under normal circumstances RcppArmadillo will connect +Armadillo to the R random number generator which also implies that \code{set.seed()} +should be used from R. To use this function, one also needs to undefine \code{ARMA_RNG_ALT} +so that the Armadillo generators are used. } \note{ -This has been found to not work as espected in -\pkg{RStudio} as its code also uses the system RNG library. -You may have to either not run within \pkg{RStudio} or -change your code to use a different RNG such as the one -from R. +This has been found to not work as expected in \pkg{RStudio} +as its code also uses the system RNG library. You may have to either +not run within \pkg{RStudio} or change your code to use a different RNG such +as the one from R. } \seealso{ -The R documentation on its RNGs all of which are accessible -via \pkg{Rcpp}. +The R documentation on its RNGs all of which are accessible via \pkg{Rcpp}. } - diff --git a/man/armadillo_set_seed_random.Rd b/man/armadillo_set_seed_random.Rd deleted file mode 100644 index 107df9a1..00000000 --- a/man/armadillo_set_seed_random.Rd +++ /dev/null @@ -1,33 +0,0 @@ -\name{armadillo_set_seed_random} -\alias{armadillo_set_seed_random} -\title{Set the Armadillo Random Number Generator to a random value} -\usage{ -armadillo_set_seed_random() -} -\value{ -The function is invoked for its side effect and has no -return value. -} -\description{ -Set the Armadillo Random Number Generator to a random value -} -\details{ -Depending on whether RcppArmadillo was compiled for the C++98 standard -(currently the default) or for C++11 (optional), two different RNGs may be used. -This function resets either. For C++98, the R programming language's RNG is used. -For C++11, the RNG included in the \code{} library is used only when - \code{#define ARMA_USE_CXX11_RNG} is placed before \code{#include }. - Otherwise, the R programming language's RNG will be used. -} -\note{ -This has been found to not work as espected in -\pkg{RStudio} as its code also uses the system RNG library. -You may have to either not run within \pkg{RStudio} or -change your code to use a different RNG such as the one -from R. -} -\seealso{ -The R documentation on its RNGs all of which are accessible -via \pkg{Rcpp}. -} - diff --git a/man/armadillo_version.Rd b/man/armadillo_version.Rd index 38df5e22..45ca9928 100644 --- a/man/armadillo_version.Rd +++ b/man/armadillo_version.Rd @@ -1,3 +1,5 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/RcppExports.R \name{armadillo_version} \alias{armadillo_version} \title{Report the version of Armadillo} @@ -5,25 +7,20 @@ armadillo_version(single) } \arguments{ - \item{single}{A logical vector indicating whether a - single return values is requested, or a named vector with - three elements \code{major}, \code{minor} and - \code{patch}.} +\item{single}{A logical vector indicating whether a single return values is requested, +or a named vector with three elements \code{major}, \code{minor} and \code{patch}.} } \value{ -Depending on the value of \code{single}, either a single -number describing the Armadillo version or a named vector -with three elements \code{major}, \code{minor} and -\code{patch}. +Depending on the value of \code{single}, either a single number describing +the Armadillo version or a named vector with three elements \code{major}, \code{minor} +and \code{patch}. } \description{ Report the version of Armadillo } \details{ -The version is defined by Armadillo in the header -\code{arma_version.hpp}. +The version is defined by Armadillo in the header \code{arma_version.hpp}. } \seealso{ Armadillo header file \code{arma_version.hpp}. } - diff --git a/src/RcppArmadillo.cpp b/src/RcppArmadillo.cpp index 01c1ebf8..f0300391 100644 --- a/src/RcppArmadillo.cpp +++ b/src/RcppArmadillo.cpp @@ -1,7 +1,7 @@ // RcppArmadillo.cpp: Rcpp/Armadillo glue // -// Copyright (C) 2010 - 2024 Dirk Eddelbuettel, Romain Francois and Douglas Bates +// Copyright (C) 2010 - 2025 Dirk Eddelbuettel, Romain Francois and Douglas Bates // // This file is part of RcppArmadillo. // @@ -49,45 +49,29 @@ Rcpp::IntegerVector armadillo_version(bool single) { // Per request of Gábor Csárdi in https://github.com/RcppCore/RcppArmadillo/issues/11 // -//' Set the Armadillo Random Number Generator to a random value -//' -//' @details -//' Depending on whether RcppArmadillo was compiled for the C++98 standard -//' (currently the default) or for C++11 (optional), two different RNGs may be used. -//' This function resets either. For C++98, the R programming language's RNG is used. -//' For C++11, the RNG included in the \code{} library is used only when -//' \code{#define ARMA_USE_CXX11_RNG} is placed before \code{#include }. -//' Otherwise, the R programming language's RNG will be used. -//' @return The function is invoked for its side effect and has no return value. -//' @note This has been found to not work as espected in \pkg{RStudio} -//' as its code also uses the system RNG library. You may have to either -//' not run within \pkg{RStudio} or change your code to use a different RNG such -//' as the one from R. -//' @seealso The R documentation on its RNGs all of which are accessible via \pkg{Rcpp}. +//' @rdname armadillo_set_seed // [[Rcpp::export]] void armadillo_set_seed_random() { arma::arma_rng::set_seed_random(); // set the seed to a random value } -//' Set the Armadillo Random Number Generator to the given value +//' @title Set the Armadillo Random Number Generator to given or random value //' //' @param val The seed used to initialize Armadillo's random number generator. //' @details -//' Depending on whether RcppArmadillo was compiled for the C++98 standard -//' (currently the default) or for C++11 (optional), two different RNGs may be used. -//' This function resets either. For C++98, the R programming language's RNG is used. -//' For C++11, the RNG included in the \code{} library is used only when -//' \code{#define ARMA_USE_CXX11_RNG} is placed before \code{#include }. -//' Otherwise, the R programming language's RNG will be used. +//' Armadillo can switch between two random number generator implementations depending +//' on the compilation standard used. Under normal circumstances RcppArmadillo will connect +//' Armadillo to the R random number generator which also implies that \code{set.seed()} +//' should be used from R. To use this function, one also needs to undefine \code{ARMA_RNG_ALT} +//' so that the Armadillo generators are used. //' @return The function is invoked for its side effect and has no return value. -//' @note This has been found to not work as espected in \pkg{RStudio} +//' @note This has been found to not work as expected in \pkg{RStudio} //' as its code also uses the system RNG library. You may have to either //' not run within \pkg{RStudio} or change your code to use a different RNG such //' as the one from R. //' @seealso The R documentation on its RNGs all of which are accessible via \pkg{Rcpp}. // [[Rcpp::export]] void armadillo_set_seed(unsigned int val) { - //Rcpp::Rcout << "Setting value " << val << std::endl; arma::arma_rng::set_seed(val); // set the seed to given value }