fixes #4519

man/internal.selfref.rd

@@ -0,0 +1,36 @@
+\name{.internal.selfref}
+\alias{.internal.selfref}
+\title{Internal Self-Reference Attribute in data.table}
+\description{
+The `.internal.selfref` attribute is an internal mechanism used by \code{data.table} to optimize memory management and performance. This attribute ensures that \code{data.table} objects can be modified by reference without unnecessary copying, enabling efficient data manipulation.
+}
+\usage{
+\code{.internal.selfref}
+}
+\details{
+The `.internal.selfref` attribute is a pointer that allows \code{data.table} objects to reference their own memory location. This avoids redundant memory allocation when performing in-place modifications such as adding or updating columns, filtering rows, or performing joins. 
+
+If the `.internal.selfref` attribute is lost or corrupted (e.g., due to operations that inadvertently break reference semantics), \code{data.table} falls back to standard \code{data.frame}-like behavior, which can lead to reduced performance due to copying.
+
+Users generally do not need to interact directly with `.internal.selfref`, but understanding its purpose can help debug issues related to memory usage or unexpected copying in \code{data.table} operations.
+
+Note that `.internal.selfref` is automatically managed by \code{data.table} and is not intended to be modified by users.
+}
+\value{
+The `.internal.selfref` attribute is an internal implementation detail and does not produce a value that users would typically interact with. It is invisible during regular \code{data.table} operations.
+}
+\seealso{
+\code{\link{data.table}}, \code{\link{setkey}}, \code{\link{merge}}, \code{\link{[.data.table}}
+}
+\examples{
+# Example to illustrate the presence of .internal.selfref
+dt <- data.table(A = 1:5, B = letters[1:5])
+attr(dt, ".internal.selfref")  # Check the internal self-reference attribute
+
+# Modify the data.table in-place
+dt[, C := A * 2]
+
+# Verify .internal.selfref is maintained
+attr(dt, ".internal.selfref")
+}
+\keyword{ internal }