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.
obj_find(
obj,
envir = NULL,
envmap = NULL,
globalsearch = TRUE,
n = 0,
return_address = FALSE,
include_functions = FALSE,
silent = TRUE
)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).
environment where the search for obj should be carried out.
It defaults to NULL which means obj is searched in the calling environment
(i.e. in the environment calling this function), unless globalsearch=TRUE in which case
it is searched in the whole workspace.
data frame containing a lookup table with name-address pairs of environment names and
addresses to be used when searching for environment env. It defaults to NULL which means that the
lookup table is constructed on the fly with the environments defined in the envir environment
--if not NULL--, or in the whole workspace if envir=NULL.
See the details section for more information on its structure.
when envir=NULL it specifies whether the search for obj should be done
globally, i.e. in the whole workspace, or just within the calling environment.
non-negative integer indicating the number of levels to go up from the calling function environment
to evaluate obj. It defaults to 0 which implies that obj is evaluated in the environment
of the calling function (i.e. the function that calls obj_find()).
whether to return the address of the environments where the object is found in addition to their names.
whether to include funtion execution environments as environments where the object
is searched for. Set this flag to TRUE with caution because there may be several functions where the
same object is defined, for instance functions that are called as part of the object searching process!
run in silent mode? If not, the search history is shown,
listing all the environments that are searched for object obj. It defaults to TRUE.
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.
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.
# NOT RUN {
# 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)
# }
Run the code above in your browser using DataLab