Regarding Modification By Reference

This help page describes how modification using "pass-by-reference" semantics is handled by the 'squarebrackets' package.
This help page does not explain all the basics of pass-by-reference semantics, as this is treated as prior knowledge.
All functions/methods in the 'squarebrackets' package with the word "set" in the name use pass-by-reference semantics.

Advantages and Disadvantages

The main advantage of pass-by-reference is that much less memory is required to modify objects, and modification is also generally faster.
But it does have several disadvantages.

First, the coercion rules are slightly different: see squarebrackets_coercion.

Second, if 2 or more variables refer to exactly the same object, changing one variable also changes the other ones.
I.e. the following code,

x <- y <- mutable_atomic(1:16)
sb_set(x, i = 1:6, rp = 8)

modifies not just x, but also y.
This is true even if one of the variables is locked (see bindingIsLocked).
I.e. the following code,

x <- mutable_atomic(1:16)
y <- x
lockBinding("y", environment())
sb_set(x, i = 1:6, rp = 8)

modifies both x and y without error, even though y is a locked constant.

Mutable vs Immutable Classes

With the exception of environments, most of base R's S3 classes are treated as immutable:
Modifying an object in 'R' will make a copy of the object, something called 'copy-on-modify' semantics.

A prominent mutable S3 class is the data.table class, which is a mutable data.frame class, and supported by 'squarebrackets'.
Similarly, 'squarebrackets' adds a class for mutable atomic objects:
mutable_atomic.

Material vs Immaterial objects

Most objects in 'R' are material objects:
the values an object contains are actually stored in memory.
For example, given x <- rnorm(1e6), x is a material object:
1 million values (decimal numbers, in this case) are actually stored in memory.

In contrast, ActiveBindings are immaterial:
They are objects that, when accessed, call a function to generate values on the fly, rather than actually storing values.

Since immaterial objects do not actually store the values in memory, the values obviously also cannot be changed in memory.
Therefore, Pass-by-Reference semantics don't work on immaterial objects.

ALTREP

The mutable_atomic constructors (i.e. mutable_atomic, as.mutable_atomic, etc.) will automatically materialize ALTREP objects, to ensure consistent behaviour for 'pass-by-reference' semantics.

A data.table can have ALTREP columns.
A data.tables will coerce the column to a materialized column when it is modified, even by reference.

Mutability Rules With Respect To Recursive Objects

Lists are difficult objects in that they do not contain elements, they simply point to other objects, that one can access via a list.
When a recursive object is of a mutable class, all its subsets are treated as mutable, as long as they are part of the object.
On the other hand, When a recursive object is of an immutable class, its recursive subsets retain their original mutability.

Example 1: Mutable data.tables
A data.table is a mutable class.
So all columns of the data.table are treated as mutable;
There is no requirement to, for instance, first change all columns into the class of mutable_atomic to modify these columns by reference.

Example 2: Immutable lists
A regular list is an immutable class.
So the list itself is immutable, but the recursive subsets of the list retain their mutability.
If you have a list of data.table objects, for example, the data.tables themselves remain mutable.
Therefore, the following pass-by-reference modification will work without issue:

x <- list(
 a = data.table::data.table(cola = 1:10, colb = letters[1:10]),
 b = data.table::data.table(cola = 11:20, colb = letters[11:20])
)
myref <- x$a
sb2_set(myref, vars = "cola", tf = \(x)x^2)

Notice in the above code that myref has the same address as x$a, and is therefore not a copy of x$a.
Thus changing myref also changes x$a.
In other words: myref is what could be called a "View" of x$a.

Input Variable

Methods/functions that perform in-place modification by reference only works on objects that actually exist as an actual variable, similar to functions in the style of some_function(x, ...) <- value.
Thus things like any of the following,
sb_set(1:10, ...), sb2_set(x$a, ...), or sb_set(base::letters),
will not work.

Lock Binding

Mutable classes are, as the name suggests, meant to be mutable.
Locking the binding of a mutable object is mostly fruitless (but not completely; see the currentBindings function).
To ensure an object cannot be modified by any of the methods/functions from 'squarebrackets', 2 things must be true:

• the object must be an immutable class.

• the binding must be locked (see lockBinding).
  
  

Protection

Due to the properties described above in this help page, 'squarebrackets' protects the user from do something like the following:

# letters = base::letters
sb_set(letters, i = 1, rp = "XXX")

'squarebrackets' will give an error when running the code above, because:

1. most addresses in baseenv() are protected;

2. immutable objects are disallowed (you'll have to create a mutable object, which will create a copy of the original, thus keeping the original object safe from modification by reference);

3. locked bindings are disallowed.

Examples

# the following code demonstrates how locked bindings,
# such as `base::letters`,
# are being safe-guarded

x <- list(a = base::letters)
myref <- x$a # view of a list
address(myref) == address(base::letters) # TRUE: point to the same memory
#> [1] TRUE
bindingIsLocked("letters", baseenv()) # base::letters is locked ...
#> [1] TRUE
bindingIsLocked("myref", environment()) # ... but this pointer is not!
#> [1] FALSE

if(requireNamespace("tinytest")) {
  tinytest::expect_error(
    sb_set(myref, i = 1, rp = "XXX") # this still gives an error though ...
  )
}
#> Loading required namespace: tinytest
#> ----- PASSED      : <-->
#>  call| eval(expr, envir) 

is.mutable_atomic(myref) # ... because it's not of class `mutable_atomic`
#> [1] FALSE


x <- list(
  a = as.mutable_atomic(base::letters) # `as.mutable_atomic()` makes a copy
)
myref <- x$a # view of a list
address(myref) == address(base::letters) # FALSE: it's a copy
#> [1] FALSE
sb_set(
  myref, i = 1, rp = "XXX"  # modifies x, does NOT modify `base::letters`
)
print(x) # x is modified
#> $a
#>  [1] "XXX" "b"   "c"   "d"   "e"   "f"   "g"   "h"   "i"   "j"   "k"   "l"  
#> [13] "m"   "n"   "o"   "p"   "q"   "r"   "s"   "t"   "u"   "v"   "w"   "x"  
#> [25] "y"   "z"  
#> mutable_atomic 
#> typeof:  character 
#> 
base::letters # but this still the same
#>  [1] "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p" "q" "r" "s"
#> [20] "t" "u" "v" "w" "x" "y" "z"