Chapter 28 Environment
By using Environment class, you can keep the environment you want to access as a variable and retrieve variables and functions from the environment.
28.1 Creating Environment object
This section shows you how to create an object of the Environment class.
Environment env(); // Global environment
Environment env = Environment::global_env(); // Global environment
Environment env("package:stats"); // Environment of package "stats"
Environment env(1); // The i-th environment in onbject search path (i = 1 is global environment)To check the object search path, use search() function in R.
> search()
[1] ".GlobalEnv" "tools:RGUI" "package:stats"
[4] "package:graphics" "package:grDevices" "package:utils"
[7] "package:datasets" "package:methods" "Autoloads"
[10] "package:base" 28.2 Accessing object in a environment
You can use the [] operator or get() member function to access variables and functions in an environment through Environment class object. If you access variables or functions that do not exist in that environment, R_NilValue (NULL) will be returned.
// Retrieving the global environment
Environment env = Environment::global_env();
// Retrieving object "x" from the global environment
NumericVector x = env["x"];
// Changing the value of the variable x in the global environment
x[0] = 100;28.3 Creating new environment
A new empty environment can be created by using the function new_env() function.
28.3.1 new_env(size = 29)
Returns a new environment. The argument size specifies the initial size of the hash table of the environment to be created.
28.3.2 new_env(parent, size = 29)
Returns a new environment whose parent environmnet is the parent. The argument size specifies the initial size of the hash table of the environment to be created.
28.4 Member functions
28.4.1 get(name)
Retrieves the object with its name specified by the argument name. If it can not be found, it returns R_NilValue.
28.4.2 ls(all)
Returns a list of objects in this environment as a CharacterVector. If the argument all is true, all objects are displayed, false excludes objects whose name begins with ..
28.4.3 find(name)
Retrieves the object with the name specified by the argument name from this environment or its parent environment. If the object is not found, the binding_not_found exception is thrown.
28.4.4 exists(name)
Returns true if there is an object with the name specified by the argument name in this environment.
28.4.5 assign( name, x )
Assign the value x to the object with the name specified by the character string name in this environment. Returns true if it succeeds.
28.4.6 isLocked()
Returns true if this environment is locked.
28.4.7 remove(name)
Removes the object with the name specified by the string name from this environment. Returns true if it succeeds.
28.4.8 lock(bindings = false)
Locks this environment. If binding = true, it also locks bindings of this environment. (The “binding” is linking between name of the object and data of the object in R.)
28.4.9 lockBinding(name)
Lock the binding (i.e. variable) specified by the string name in this environment.
28.4.10 unlockBinding(name){
Unlock the binding (i.e. variable) specified by the string name in this environment.
28.4.11 bindingIsLocked(name)
Returns true if the binding (i.e. variable) specified by the string name in this environment is locked.
28.4.12 bindingIsActive(name)
Returns true if the binding (i.e. variable) specified by the string name in this environment is active.
28.4.13 is_user_database()
Returns true if this environment inherits “UserDefinedDatabase”.
28.4.14 parent()
Returns the parent environment of this environment.
28.4.15 new_child(hashed)
Creates a new environment whose parent is this environment. If hashed == true, the created environment uses hash table.
28.5 Static member functions
###Environment::global_env()
Returns the global environment.
###Environment::empty_env()
Returns the empty environment.
###Environment::base_env()
Returns the environment of base package.
###Environment::base_namespace()
Returns the namespace of base package.
28.5.1 Environment::Rcpp_namespace()
Returns the namespace of Rcpp package.
28.5.2 Environment::namespace_env(package)
Returns the namespace of the package whose name is specified by argument package. If you use Environment::namespace_env(), you can call package functions without preloading the package with the library() function in R. This is equivalent to calling package function with the form PACKAGE::FUNCTION(). In addition, you can also access functions that are not exported in the package. This is equivalent to calling with the form PACKAGE:::FUNCTION() in R.