Description Usage Arguments Details Value Examples
Look for an object in the whole workspace including all environments defined within it (possibly recursively) and return ALL the environment(s) where the object is found. User-defined environments are also searched. Note that both the "recursive search" and the "user-defined environments search" makes this function quite different from functions find and exists of the base package. Optionally, the search can be limited to a specified environment, as opposed to carrying it out in the whole workspace. Still, all user-defined environments defined inside the specified environment are searched.
1 2 3 4 5 6 7 8 9 10 |
obj |
object to be searched given as the object itself or as a character string. If given as an object, expressions are accepted (see details on how expressions are handled). |
envir |
environment where the search for |
envmap |
data frame containing a lookup table with name-address pairs of environment names and
addresses to be used when searching for environment |
globalsearch |
when |
n |
non-negative integer indicating the number of levels to go up from the calling function environment
to evaluate |
return_address |
whether to return the address of the environments where the object is found in addition to their names. |
include_functions |
whether to include funtion execution environments as environments where the object
is searched for. Set this flag to |
silent |
run in silent mode? If not, the search history is shown,
listing all the environments that are searched for object |
An object is found in an environment if it is reachable from within that environment. An object is considered reachable in an environment if either one of the following occurs:
it exists in the given environment
it exists in a user-defined environment defined inside the given environment or in any environment recursively defined inside them
Note that obj_find
differs from base functions find
and exists
in that obj_find
searches for the object inside user-defined environments within any given environment in a recursive way.
In particular, compared to:
find
: obj_find
searches for objects inside user-defined environments while find
is not
able to do so (see examples).
exists
: obj_find
never searches for objects in the parent environment of envir
when envir
is not NULL
, as is the case with the exists
function when its inherits
parameter is set to TRUE
(the default).
If it is wished to search for objects in parent environments, simply set envir=NULL
and globalsearch=TRUE
, in which case the object will be searched in the whole workspace
and the environments where it is found will be returned.
When the object is found, an array containing the names of all the environments where the object is found is returned.
When envir
is not NULL
attached packages are not included in the search for obj
,
unless of course envir
is itself a package environment.
When given as an object, obj
can be an expression. If the expression is an attribute of a list
or an array element, the object contained therein is searched for.
Ex: if alist$var = "x"
then object x
is searched.
If envmap
is passed it should be a data frame providing an address-name pair lookup table
of environments and should contain at least the following columns:
location
for user-defined environments, the name of the environment where the environment
is located; otherwise NA
.
pathname
the full environment path to reach the environment separated by $
(e.g. "env1$env$envx"
)
address
the 8-digit (32-bit architectures) thru 16-digit (64-bit architectures) memory address
of the environment given in pathname
enclosed in < > (e.g. "<0000000007DCFB38>"
(64-bit architectures))
Be ware that Linux Debian distributions may have a 12-digit memory address representation.
So the best way to know is to check a memory address by calling e.g. 'address("x")'.
Passing an envmap
lookup table is useful for speedup purposes, in case several calls to this
function will be performed in the context of an unchanged set of defined environments.
Such envmap
data frame can be created by calling get_env_names.
Use this parameter with care, as the matrix passed may not correspond to the actual mapping of existing
environments to their addresses and in that case results may be different from those expected.
The return value depends on the value of parameter return_address
: when FALSE
(the default) it returns an array containing the names of the environments where the object obj
is found; when TRUE
it returns a list with two attributes: "env_full_names"
and
"env_addresses"
with respectively the environment names and addresses where the object is found.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | # Define a variable in the global environment
x = 4
# Create new environments, some nested
env1 = new.env()
with(env1, envx <- new.env())
env1$x = 3
env1$envx$x = 2
env1$y = 5
# Look for objects (crawling environments recursively)
obj_find(x) # "env1" "env1$envx" "R_GlobalEnv"
obj_find("x") # "env1" "env1$envx" "R_GlobalEnv"
obj_find("x", envir=env1) # "env1" "envx" (as the search is limited to the env1 environment)
obj_find("y") # "env1"
obj_find(nonexistent) # NULL (note that NO error is raised even if the object does not exist)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.