more details on compareVersion

git-svn-id: https://svn.r-project.org/R/trunk@87243 00db46b3-68df-0310-9c12-caf00c1e9a41

Author: ripley

src/library/base/man/ns-reflect.Rd

@@ -1,6 +1,6 @@
 % File src/library/base/man/ns-reflect.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 2003-2020 R Core Team
+% Copyright 2003-2024 R Core Team
 % Distributed under GPL 2 or later
 
 \name{ns-reflect}
@@ -48,10 +48,16 @@ getNamespaceVersion(ns)
   and subject to change.
 
   \code{getNamespaceName} and \code{getNamespaceVersion} return the name
-  and version of the namespace \code{ns}.
+  and version of the namespace \code{ns} as character strings.
 
   \code{getNamespaceUsers} returns a character vector of the names of
   the namespaces that import namespace \code{ns}.
 }
+\note{
+  Comparison of versions should use \code{\ink{compareVersion} or
+\preformatted{
+    as.package_version(getNamespaceVersion(ns))
+}
+}
 \keyword{internal}
 \author{Luke Tierney}

src/library/utils/R/packages.R

@@ -753,7 +753,7 @@ download.packages <- function(pkgs, destdir, available = NULL,
         bulkdown <- matrix(character(), 0L, 3L)
     else
         bulkdown <- NULL
-   
+
     retval <- matrix(character(), 0L, 2L)
     for(p in unique(pkgs))
     {
@@ -825,7 +825,7 @@ download.packages <- function(pkgs, destdir, available = NULL,
         urls <- bulkdown[,3]
         destfiles <- bulkdown[,2]
         ps <- bulkdown[,1]
-                                           
+
         res <- try(download.file(urls, destfiles, "libcurl", mode = "wb", ...))
         if(!inherits(res, "try-error") && res == 0L) {
             if (length(urls) > 1) {
@@ -842,7 +842,7 @@ download.packages <- function(pkgs, destdir, available = NULL,
         } else
             for(p in ps)
                 warning(gettextf("download of package %s failed", sQuote(p)),
-                        domain = NA, immediate. = TRUE)            
+                        domain = NA, immediate. = TRUE)
     }
 
     retval
@@ -1043,8 +1043,11 @@ compareVersion <- function(a, b)
 {
     if(is.na(a)) return(-1L)
     if(is.na(b)) return(1L)
+    ## The nest two could be skipped if(inherits(x), "numeric_version")
+    ## but the saving would be small.
     a <- as.integer(strsplit(a, "[.-]")[[1L]])
     b <- as.integer(strsplit(b, "[.-]")[[1L]])
+    ## This does not handle malformed inputs which will give an error.
     for(k in seq_along(a))
         if(k <= length(b)) {
             if(a[k] > b[k]) return(1) else if(a[k] < b[k]) return(-1L)

src/library/utils/man/compareVersion.Rd

@@ -1,6 +1,6 @@
 % File src/library/utils/man/compareVersion.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2007 R Core Team
+% Copyright 1995-2024 R Core Team
 % Distributed under GPL 2 or later
 
 \name{compareVersion}
@@ -19,6 +19,8 @@ compareVersion(a, b)
   \code{0} if the numbers are equal, \code{-1} if \code{b} is later
   and \code{1} if \code{a} is later (analogous to the C function
   \code{strcmp}).
+
+  Gives an \R error on malformed inputs.
 }
 \details{
   \R package version numbers are of the form \code{x.y-z} for integers