.Last.updated manual entry

NEWS.md

@@ -71,7 +71,7 @@
     setnafill(DT, "locf")         ## DT in-place    0.367s
     ```
 
-7. New variable `.Last.updated` (similar to R's `.Last.value`) contains the number of rows affected by the most recent `:=` or `set()`, [#1885](https://github.com/Rdatatable/data.table/issues/1885).
+7. New variable `.Last.updated` (similar to R's `.Last.value`) contains the number of rows affected by the most recent `:=` or `set()`, [#1885](https://github.com/Rdatatable/data.table/issues/1885). For details see `?.Last.updated`.
 
 #### BUG FIXES
 

man/assign.Rd

@@ -44,6 +44,8 @@ set(x, i = NULL, j, value)
     DT[,`:=`(new1 = sum(colB), new2 = sum(colC))] # Functional form
 }
 
+The \code{\link{.Last.updated}} variable contains the number of rows updated by the most recent \code{:=} or \code{set} calls, which may be useful, for example, in production settings for testing assumptions about the number of rows affected by a statement; see \code{\link{.Last.updated}} for details.
+
 Note that for efficiency no check is performed for duplicate assignments, i.e. if multiple values are passed for assignment to the same index, assignment to this index will occur repeatedly and sequentially; for a given use case, consider whether it makes sense to create your own test for duplicates, e.g. in production code.
 
 All of the following result in a friendly error (by design) :
@@ -78,7 +80,7 @@ Since \code{[.data.table} incurs overhead to check the existence and type of arg
 \value{
 \code{DT} is modified by reference and returned invisibly. If you require a copy, take a \code{\link{copy}} first (using \code{DT2 = copy(DT)}).
 }
-\seealso{ \code{\link{data.table}}, \code{\link{copy}}, \code{\link{alloc.col}}, \code{\link{truelength}}, \code{\link{set}}
+\seealso{ \code{\link{data.table}}, \code{\link{copy}}, \code{\link{alloc.col}}, \code{\link{truelength}}, \code{\link{set}}, \code{\link{.Last.updated}}
 }
 \examples{
 DT = data.table(a = LETTERS[c(3L,1:3)], b = 4:7)

man/last.updated.Rd

@@ -0,0 +1,32 @@
+\name{.Last.updated}
+\alias{.Last.updated}
+\alias{Last.updated}
+\title{ Number of rows affected by last update }
+\description{
+    Returns number of rows affected by last \code{:=} or \code{set()}.
+}
+\usage{
+    .Last.updated
+}
+\value{
+    Integer.
+}
+\details{
+  Be aware that in the case of duplicate indices, multiple updates occur (duplicates are overwritten);
+  \code{.Last.updated} will include \emph{all} of the
+  updates performed, including duplicated ones. See examples.
+}
+\seealso{
+  \code{\link{:=}}
+}
+\examples{
+d = data.table(a=1:4, b=2:5)
+d[2:3, z:=5L]
+.Last.updated
+
+# updated count takes duplicates into account #2837
+DT = data.table(a = 1L)
+DT[c(1L, 1L), a := 2:3]
+.Last.updated
+}
+\keyword{ data }