What's the difference between box::use and the double colon operator (i.e., ::)?

[SaintRod]

Hi, all:

I've scoured the web but haven't seen an explicit answer. What is the difference between box::use and loading a namespace via the double colon operator (i.e., library::namespace)?

I was recently introduced to box via the Rhino framework for Shiny development in R. I enjoyed using box so I've started using it for data analysis tasks. However, for such tasks I've traditionally used the double colon operator to reference a namespace and avoid library(dplyr) for example. I'm curious to learn more about the differences to determine if it makes sense to replace :: with box::use.

box::use(
  dplyr[mutate, filter, select]
)

DF |>
filter() |>
select() |>
mutate()

OR

box::use(
  dplyr = dplyr[mutate, filter, select]
)

DF |>
dplyr$filter() |>
dplyr$select() |>
dplyr$mutate()

vs

DF |>
dplyr::filter() |>
dplyr::select() |>
dplyr::mutate()

Thank you!

[trev-f]

IMO the convenient thing about box::use here is that it saves a lot of typing while still making it explicit that when you call mutate, filter, or select you're calling those functions from the dplyr package and not, for example, stats::filter.

If you're asking about performance differences then I can't comment on that. But I'm also of the belief that if you're concerned with performance differences between methods of calling functions then R may not be the best language for you.

[klmr]

Regarding performance:

I haven’t directly compared the performance of :: and ‘box’ $ but I believe they should be very close to each other, with ‘box’ $ probably being slightly faster(!):

1. both are implemented directly in C code (:: is a .Primitive() whereas $ is a regular .Call()/soon .External2(), but the FFI call overhead should be near identical)
2. I have extensively benchmarked $ to make it as fast as (I think) it can get
3. :: performs an additional lookup, for the package name, in the namespace registry
4. :: has additional logic to distinguish between the base namespace and other packages, which I believe is required for backwards compatibility reasons
5. :: acts in two stages after the namespace lookup: it first looks up the value, and then it checks whether the value is actually exported (and under what name; this is always the same name as the declared name, but this translation still happens); ‘box’ does not need to do this; it directly looks up the name in the environment of exported names.
6. ::, for some reason, uses full-blown eval() to evaluate a name in a namespace rather than something like findVarInFrame, which performs straightforward hash table lookup. This adds its own overhead.

[SaintRod]

Thank you both for your responses and thoughts!

[klmr]

There are two differences:

First off, ‘box’ supports loading modules, not just packages. Modules are a modern way of organising and reusing code which is more lightweight and powerful than packages. When organising hierarchical projects in Rhino, you are using modules. Packages have no equivalent functionality. For more details, refer to the Get started vignette.

Secondly, when using packages without ‘box’, you basically have to choose between two options:¹

1. attach all names globally (via library(pkgname))
2. don’t attach any names and qualify them all explicitly every time via pkgname::function().

‘box’ gives you a lot more choices. For starter, attachment doesn’t happen globally but locally in the current scope. So if a function attaches a package or module, this doesn’t affect other code outside that function. This makes it much less problematic to attach imports. Secondly, you can exert fine-grained control over what names from an import should be attached, unlike library(), which attaches all names. You can also give attached names aliases to avoid name clashes; for instance, you could use the following declaration:

box::use(
  dplyr[...],
  stats[..., filter = stat_filter],
)

This attaches all names from ‘dplyr’ as well as ‘stats’, but because the filter() function exists in both packages we attach the name from ‘stats’ using an alias. Now filter() calls dplyr::filter(), and stat_filter() calls stats::filter().

Generally speaking, the most robust way would be if we fully qualified all names all the time (i.e. what your second code does, dplyr::…). But this makes code a lot more verbose and often actively hurts readability. ‘box’ allows you to still be explicit with your imports without sacrificing readability. The style of your first code snippet corresponds to the established best practice in many modern programming languages, including Rust, Python, TypeScript, Haskell, (to some extent) C++, etc.

---

¹ Nowadays library() has the arguments exclude and include.only which let you specify a subset of names to attach. This didn’t exist when ‘box’ was first released. However, besides having bad ergonomics due to excessive verbosity², these arguments are also completely broken and cannot be used reliably: their effect is still global, and if a given package is imported twice via library() (or require()), only the first call takes effect; all subsequent calls are ignored. So if one piece of code attaches only one name, and a second piece of code tries to attach other/all names, attempting to access those other names will lead to a runtime error.

² Just compare these two code snippets; I know which one I find more readable:

library(dplyr, include.only = c("filter", "mutate", "select"))
library(tidyr, include.only = c("pivot_longer", "pivot_wider"))

box::use(
  dplyr[filter, mutate, select],
  tidyr[pivot_longer, pivot_wider],
)

[SaintRod]

Thank you again for your thoughts! I agree, I like box [a lot]. Incorporating box into data analyses has been simple. I've even retroactively incorporated box by qualifying/aliasing imports (as seen below) and replacing :: with $. In the future, to save time I'll do dplyr[filter, mutate, select] and call the functions directly without the $... fewer keystrokes.

In summary, yes, it "makes sense to replace :: with box::use" and there are multiple ways to do so.

# not aliased
box::use(
  dplyr[mutate, filter, select]
)

# aliased
box::use(
  dplyr = dplyr[mutate, filter, select]
)