selfref.ok() helper to close #7329 (#7332)

* selfref.ok() helper to close #7329

* rename to dot prefix

* Update NEWS.md

* re-emphasize technical nature of .selfref.ok

---------

Co-authored-by: Michael Chirico <[email protected]>

Author: jangorecki

NAMESPACE

@@ -215,6 +215,7 @@ S3method(format_list_item, data.frame)
 export(fdroplevels, setdroplevels)
 S3method(droplevels, data.table)
 export(frev)
+export(.selfref.ok)
 
 # sort_by added in R 4.4.0, #6662, https://stat.ethz.ch/pipermail/r-announce/2024/000701.html
 if (getRversion() >= "4.4.0") S3method(sort_by, data.table)  

NEWS.md

@@ -311,6 +311,8 @@
 
 6. Using a double vector in `set()`'s `i=` and/or `j=` no longer throws a warning about preferring integer, [#6594](https://github.com/Rdatatable/data.table/issues/6594). While it may improve efficiency to use integer, there's no guarantee it's an improvement and the difference is likely to be minimal. The coercion will still be reported under `datatable.verbose=TRUE`. For package/production use cases, static analyzers such as `lintr::implicit_integer_linter()` can also report when numeric literals should be rewritten as integer literals.
 
+7. In rare situations a data.table object may lose its internal attribute that holds a self-reference. New helper function `.selfref.ok()` tests just that. It is only intended for technical use cases. See manual for examples.
+
 ## data.table [v1.17.8](https://github.com/Rdatatable/data.table/milestone/41) (6 July 2025)
 
 1. Internal functions used to signal errors are now marked as non-returning, silencing a compiler warning about potentially unchecked allocation failure. Thanks to Prof. Brian D. Ripley for the report and @aitap for the fix, [#7070](https://github.com/Rdatatable/data.table/pull/7070).

R/helpers.R

@@ -10,3 +10,10 @@ fctr = function(x, levels=unique(x), ..., sort=FALSE, rev=FALSE) {
   if (rev) levels = frev(levels)
   factor(x, levels=levels, ...)
 }
+
+# add a function for validating data.tables that might need setDT #7329
+.selfref.ok = function(x) {
+  if (!is.data.table(x))
+    stopf(".selfref.ok expects data.table class object.")
+  selfrefok(x, verbose=FALSE) > 0L
+}

inst/tests/tests.Rraw

@@ -21668,3 +21668,20 @@ local({
   ...123 = 'a'
   test(2339.11, DT[, .....123], DT)
 })
+
+# Add a function for validating data.tables that might need setDT #7329
+test(2340.00, .selfref.ok(data.frame(V1=1L)), error=".selfref.ok expects data.table class object")
+d1 = structure(list(V1=1L), class=c("data.table","data.frame"))
+test(2340.01, .selfref.ok(d1), FALSE)
+setDT(d1)
+test(2340.02, .selfref.ok(d1), TRUE)
+saveRDS(d1, f<-tempfile())
+d2 = readRDS(f)
+test(2340.03, .selfref.ok(d2), FALSE)
+invisible(file.remove(f))
+setDT(d2)
+test(2340.04, .selfref.ok(d2), TRUE)
+d3 = unserialize(serialize(d2, NULL))
+test(2340.05, .selfref.ok(d3), FALSE)
+setDT(d3)
+test(2340.06, .selfref.ok(d3), TRUE)

man/.selfref.ok.Rd

@@ -0,0 +1,36 @@
+\name{.selfref.ok}
+\alias{.selfref.ok}
+\title{Tests self reference of a data.table}
+\description{
+  In rare situations, as presented in examples below, a data.table object may lose its internal attribute that holds a self-reference. This function tests just that.
+
+  It is not expected that many end users will have need for this highly technical function about data.table internals.
+}
+\usage{
+  .selfref.ok(x)
+}
+\arguments{
+  \item{x}{ A data.table. }
+}
+\value{
+  \code{TRUE} if self reference attribute is properly set, \code{FALSE} otherwise.
+}
+\examples{
+d1 = structure(list(V1=1L), class=c("data.table","data.frame"))
+.selfref.ok(d1)
+setDT(d1)
+.selfref.ok(d1)
+
+saveRDS(d1, f<-tempfile())
+d2 = readRDS(f)
+.selfref.ok(d2)
+invisible(file.remove(f))
+setDT(d2)
+.selfref.ok(d2)
+
+d3 = unserialize(serialize(d2, NULL))
+.selfref.ok(d3)
+setDT(d3)
+.selfref.ok(d3)
+}
+\keyword{ data }