From 2f245404e53388a94fc7b8ae0246a5d508061f21 Mon Sep 17 00:00:00 2001 From: Michael Chirico Date: Sat, 19 Oct 2024 21:38:19 -0700 Subject: [PATCH] Extensive NEWS item for planned eventual un-export of S3 methods (#89) --- NEWS | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/NEWS b/NEWS index 5a44c11..7bc7128 100644 --- a/NEWS +++ b/NEWS @@ -24,4 +24,24 @@ 1. The signature of `identical.integer64()` loses `extptr.as.ref=`, which is unavailable for R<4.2.0, but gains `...` to allow this argument in newer versions, #37. This retains the transparency of having all arguments named in the signature (and thus in `?identical.integer64` as well as available for tab-completion) while also retaining the old R version dependency R 3.3.0. +1. {bit64} exports many S3 methods directly. Calling S3 methods directly is generally bad form; we should rely on the S3 dispatch system for this. Needing to export an S3 method is usually indicative of some deep issue that's otherwise hard to work around. + + I plan to un-export most if not all S3 methods in future versions. In this release, there will be no change in behavior besides this notice in the NEWS. Going forward, I see two types of S3 exports: (1) exports that have no discoverable direct usage (that is, a global GitHub search, which includes the CRAN mirror, turned up _no_ R code calling them directly, except perhaps in `:::` form, which would be unaffected by un-export); and (2) exports that _are_ observed to be called directly by some number of downstreams. With the former, I am more comfortable un-exporting more aggressively; with the latter, I will take a more gradual approach. + + Here are the S3 methods that are currently exported, for which I found no record of them being called directly: + + `-.integer64`, `:.default`, `:.integer64`, `!.integer64`, `!=.integer64`, `[.integer64`, `[[.integer64`, `[[<-.integer64`, `*.integer64`, `/.integer64`, `&.integer64`, `%/%.integer64`, `%%.integer64`, `%in%.default`, `%in%.integer64`, `^.integer64`, `+.integer64`, `<.integer64`, `<=.integer64`, `==.integer64`, `>.integer64`, `>=.integer64`, `|.integer64`, `all.equal.integer64`, `as.bitstring.integer64`, `as.integer64.factor`, `as.integer64.integer64`, `as.integer64.NULL`, `as.list.integer64`, `as.logical.integer64`, `cbind.integer64`, `ceiling.integer64`, `cummax.integer64`, `cummin.integer64`, `cumprod.integer64`, `cumsum.integer64`, `diff.integer64`, `duplicated.integer64`, `floor.integer64`, `hashdup.cache_integer64`, `hashfin.cache_integer64`, `hashfun.integer64`, `hashmap.integer64`, `hashmaptab.integer64`, `hashmapuni.integer64`, `hashmapupo.integer64`, `hashpos.cache_integer64`, `hashrev.cache_integer64`, `hashrin.cache_integer64`, `hashtab.cache_integer64`, `hashuni.cache_integer64`, `hashupo.cache_integer64`, `is.double.default`, `is.double.integer64`, `is.finite.integer64`, `is.infinite.integer64`, `is.nan.integer64`, `is.sorted.integer64`, `is.vector.integer64`, `keypos.integer64`, `length<-.integer64`, `log10.integer64`, `log2.integer64`, `match.default`, `match.integer64`, `mean.integer64`, `median.integer64`, `mergeorder.integer64`, `mergesort.integer64`, `mergesortorder.integer64`, `na.count.integer64`, `nties.integer64`, `nunique.integer64`, `nvalid.integer64`, `order.default`, `order.integer64`, `orderdup.integer64`, `orderfin.integer64`, `orderkey.integer64`, `ordernut.integer64`, `orderpos.integer64`, `orderqtl.integer64`, `orderrnk.integer64`, `ordertab.integer64`, `ordertie.integer64`, `orderuni.integer64`, `orderupo.integer64`, `prank.integer64`, `print.bitstring`, `prod.integer64`, `qtile.integer64`, `quantile.integer64`, `quickorder.integer64`, `quicksort.integer64`, `quicksortorder.integer64`, `radixorder.integer64`, `radixsort.integer64`, `radixsortorder.integer64`, `ramorder.integer64`, `ramsort.integer64`, `ramsortorder.integer64`, `range.integer64`, `rank.default`, `rbind.integer64`, `round.integer64`, `scale.integer64`, `shellorder.integer64`, `shellsort.integer64`, `shellsortorder.integer64`, `sign.integer64`, `signif.integer64`, `sort.integer64`, `sortfin.integer64`, `sortnut.integer64`, `sortorderdup.integer64`, `sortorderkey.integer64`, `sortorderpos.integer64`, `sortorderrnk.integer64`, `sortordertab.integer64`, `sortordertie.integer64`, `sortorderuni.integer64`, `sortorderupo.integer64`, `sortql.integer64`, `sorttab.integer64`, `sortuni.integer64`, `sqrt.integer64`, `summary.integer64`, `table.integer64`, `tiepos.integer64`, `trunc.integer64`, `unipos.integer64` + + Here are the S3 methods that are currently exported for which I _do_ find record of them being called directly: + + `abs.integer64`, `as.character.integer64`, `as.data.frame.integer64`, `as.double.integer64`, `as.integer.integer64`, `as.integer64.bitstring`, `as.integer64.character`, `as.integer64.double`, `as.integer64.integer`, `as.integer64.logical`, `c.integer64`, `format.integer64`, `identical.integer64`, `is.na.integer64`, `lim.integer64`, `max.integer64`, `min.integer64`, `print.integer64`, `rank.integer64`, `seq.integer64`, `str.integer64`, `sum.integer64`, `unique.integer64` + + In the next release (provisionally, 4.7.0), I will add a `warning()` to any S3 method in the former classification, while nothing will change for the latter classification. I may reach out to authors observed to call the methods directly. + + In the subsequent release (provisionally, 4.8.0), I will un-export any S3 method in the former classification, and add a `warning()` to any S3 method in the latter classification. + + In the sub-subsequent release (provisionally, 4.9.0), I will un-export any S3 method in the latter classification. + + Please reach out (e.g., the GitHub log for #76) if you have any concerns about this plan. + # bit64 NEWS for versions 0.8-3 through 4.5.2 are now in [NEWS.0](https://github.com/r-lib/bit64/blob/master/NEWS.0)