[Rd] print.POSIXct doesn't seem to use tz argument, as per its example

[Martin Maechler]

>>>>> Jennifer Lyon <jennifer.s.lyon at gmail.com>
>>>>>     on Thu, 15 Dec 2016 09:33:30 -0700 writes:

> On the documentation page for DateTimeClasses, in the Examples section,
> there are the following two lines:
> 
> format(.leap.seconds)         # the leap seconds in your time zone
> print(.leap.seconds, tz = "PST8PDT")  # and in Seattle's
> 
> The second line (using print) seems to ignore the tz argument, and prints
> the dates in my time zone, while:
> 
> format(.leap.seconds, tz = "PST8PDT")
> 
> does print the dates in PST. The code in
> https://github.com/wch/r-source/blob/trunk/src/library/base/R/datetime.R
> around line 234 looks like the ... argument is passed to print, not to
> format.
> 
> print.POSIXct <-
> print.POSIXlt <- function(x, ...)
> {
>     max.print <- getOption("max.print", 9999L)
>     if(max.print < length(x)) {
>         print(format(x[seq_len(max.print)], usetz = TRUE), ...)
>         cat(' [ reached getOption("max.print") -- omitted',
>             length(x) - max.print, 'entries ]\n')
>     } else print(if(length(x)) format(x, usetz = TRUE)
>                  else paste(class(x)[1L], "of length 0"), ...)
>     invisible(x)
> }
> 
> The documentation for print() on this page seems to be silent on tz as an
> argument, but I do believe the example using print() does not work as
> advertised.

> Thanks.
> 
> Jen

Thank you, Jen!
Indeed,  both your observation and your diagnosis are correct:
This has been a misleading example and needs amending (or the
code is changed, see below).

The most simple fix would be to replace  'print('  by
'format('; then the example would work as advertized.
That change has two drawbacks still:

1) format(.) examples on the help of print.POSIXct() where
   format.POSIXct() is *not* documented 

2) It *would* make sense that print.POSIXct() allowed for a 'tz' argument
   (and maybe 'usetz' too).  This/these would be (an) extra
   argument(s) rather than passing '...' not just to print() but
   also to format()rathere

My personal preference would tend to add both
     tz = ""
and  usetz = TRUE
to the formal arguments of print.POSIXct and pass them to the
format(.) calls.

Martin


> sessionInfo()
> R version 3.3.2 (2016-10-31)
> Platform: x86_64-pc-linux-gnu (64-bit)
> Running under: Ubuntu 14.04.5 LTS
> 
> locale:
>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
>  [9] LC_ADDRESS=C               LC_TELEPHONE=C
> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
> 
> attached base packages:
> [1] stats     graphics  grDevices utils     datasets  methods   base