R object-oriented programming with or without references

R object-oriented programming with or without references [R logo]

Help pages for package ‘R.oo’ version 1.6.5

R.oo-package | Package R.oo
charToInt | Converts a vector of ASCII characters into a vector of integers
charToInt.default | Converts a vector of ASCII characters into a vector of integers
Class | The Class class describes an Object class
dimension | Gets the dimension of the object
dimension.default | Gets the dimension of the object
equals | Compares an object with another
equals.default | Compares an object with another
Exception | The Exception class to be thrown and caught
extend | Extends a object
extend.default | Extends a object
getConstructorS3 | Get a constructor method
getConstructorS3.default | Get a constructor method
getName.environment | Gets the name of an environment
getName.environment | Gets the name of an environment
hashCode | Gets an integer hashcoded for R objects
hashCode.default | Gets an integer hashcoded for R objects
InternalErrorException | InternalErrorException represents internal errors
intToChar | Converts a vector of integers into a vector of ASCII characters
intToChar.default | Converts a vector of integers into a vector of ASCII characters
ll | Generates a list of informative properties of all members of an environment
ll.default | Generates a list of informative properties of all members of an environment
Object | The root class that every class must inherit from
objectSize | Gets the size of the object in bytes
objectSize.default | Gets the size of the object in bytes
objectSize.environment | Gets the size of an environment in bytes
objectSize.environment | Gets the size of an environment in bytes
Package | The Package class provides methods for accessing package information
R.oo | Package R.oo
RccViolationException | An RccViolationException indicates a violation of the R Coding Conventions (RCC)
Rdoc | Class for converting Rdoc comments to Rd files
RdocException | RdocException are thrown by the Rdoc compiler
setConstructorS3 | Defines a class in S3/UseMethod style
setConstructorS3.default | Defines a class in S3/UseMethod style
throw | Throws an Exception
throw.default | Throws an Exception
throw.error | Throws (rethrows) an object of class 'error'
throw.error | Throws (rethrows) an object of class 'error'
trim | Converts to a string and removes leading and trailing whitespace
trim.default | Converts to a string and removes leading and trailing whitespace
typeOfClass | Gets the type of a class (S3 or S4)
typeOfClass.default | Gets the type of a class (S3 or S4)


Gets the arguments of a function as a character string

Description

Gets the arguments (with default values) of a function as a character string, which can be used for debugging purposes etc. Used by: classinfo().

Usage

Class$argsToString(fcn, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.

Examples

  Class$argsToString(plot);
[Package R.oo version 1.6.5 Index]


Gets the arguments signature of a function

Description

Gets the arguments signature of a function.

Usage

Rdoc$argsToString(fcn, ...)

Arguments

fcn | A function.
... | Not used.

Value

Returns a list of character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


Gets a character string representing the object

Description

Gets a character string representing the object.

Usage

## S3 method for class 'BasicObject':
as.character(x, ...)

Value

Returns a character string representation of the object.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see BasicObject.


Returns a short string describing the class

Description

Returns a short string describing the class.

Usage

## S3 method for class 'Class':
as.character(x, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.

Examples

  print(as.character(Object))

  # gives:  "Class Object: no fields, 8 methods (no inherited)"


Gets a character string representing of the Exception

Description

. By default the format is: "[{POSIX date string}] {class name}: {msg}".

Usage

## S3 method for class 'Exception':
as.character(x, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Exception.

Examples

## Not run: For a complete example see help(Exception).


Gets a character string representing the Interface

Description

Gets a character string representing the Interface.

Usage

## S3 method for class 'Interface':
as.character(x, ...)

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Interface.


Gets a character string representing the object

Description

Gets a character string representing the object. In the class Object, this method simply returns the class name and the hashCode() value of the object.

Usage

## S3 method for class 'Object':
as.character(x, ...)

Arguments

... Not used.

Value

Returns a character string representation of the Object. By default it is "{class name}: {hash code}".

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.

Examples

  obj <- Object()
  as.character(obj)    # "Object: 0x016A80FC"


Gets a string representation of this package

Description

Gets a string representation of this package.

Usage

## S3 method for class 'Package':
as.character(x, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

print(R.oo)


Gets a string representing of the RCC violation

Description

Gets a string representing of the RCC violation of format "[{POSIX date string}] {class name}: {msg}, cf. http://www.maths.lth.se/help/R/RCC/".

Usage

## S3 method for class 'RccViolationException':
as.character(x, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see RccViolationException.

Examples

## Not run: For a complete example see help(Exception).


Gets a character string representing of the RdocException

Description

.

Usage

## S3 method for class 'RdocException':
as.character(x, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see RdocException.


8-bit ASCII table

Description

ASCII is the 8-bit ASCII table with ASCII characters from 0-255.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

charToInt() intToChar()

Examples

  ch <- ASCII[65+1];  # ch == "A"


Attach an BasicObject to the R search path

Description

Attach the members of an BasicObject to the R search path.

If trying to attach the same BasicObject twice without detaching it inbetween, a warning will be generated and nothing will be done.

Usage

## S3 method for class 'BasicObject':
attach(this, private=FALSE, pos=2, ...)

Arguments

private | If TRUE, private fields will also be attached, otherwise not.
pos | The position at in search path where the BasicObject should be inserted.
... | Not used.

Value

Returns TRUE if the BasicObject was attached, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*detach() and attach(), detach(). For more information see BasicObject.


Attaches an Object to the R search path

Description

Attach the members of an Object to the R search path.

If trying to attach the same Object twice without detaching it inbetween, a warning will be generated and nothing will be done.

Usage

## S3 method for class 'Object':
attach(this, private=FALSE, pos=2, ...)

Arguments

private | If TRUE, private fields will also be attached, otherwise not.
pos | The position at in search path where the Object should be inserted.
... | Not used.

Value

Returns TRUE if the Object was attached, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*detach() and attach(), detach(). For more information see Object.

Examples

## Not run: For a complete example see help(Object).


Attaches an Object locally to an environment

Description

Attaches an Object locally to an environment. By default, the fields of the Object are attached to the parent frame, that is, the calling environment.

Usage

## S3 method for class 'Object':
attachLocally(this, private=FALSE, fields=NULL, excludeFields=NULL, overwrite=TRUE, envir=parent.frame(), ...)

Arguments

private | If TRUE, private fields are included, otherwise not. This is only effective if fields==NULL.
fields | A character vector specifying elements to be copied. If NULL, all elements are considered.
excludeFields | A character vector specifying elements not to be copied. This has higher priority than fields.
overwrite | If FALSE, fields that already exists will not be copied.
envir | The environment where fields are copied to.
... | Not used.

Value

Returns (invisibly) a character vector of the fields copied.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*attach() For more information see Object.

Examples

foo <- function(object, arg1="some value", ...) {
  cat("Local objects in foo():\n")
  print(ls())

  attachLocally(object)

  cat("\nLocal objects in foo():\n")
  print(ls())

  for (name in ls()) {
    cat("\nObject '", name, "':\n", sep="")
    print(get(name, inherits=FALSE))
  }
}

a <- "A string"
obj <- Object()
obj$a <- "Another string"
obj$b <- NA
foo(obj)
print(a)


A root class like Object but without references

Description

R.oo
Class BasicObject

public class BasicObject

Usage

BasicObject(core=NULL)

Arguments

core The core value of the object.

Fields and Methods

Methods:
$ | -
$<- | -
[[ | -
[[<- | -
as.character | Gets a character string representing the object.
attach | Attach an BasicObject to the R search path.
detach | Detach an BasicObject from the R search path.
equals | Compares an object with another.
extend | Extends another class.
getFields | Returns the field names of an BasicObject.
getInstantiationTime | Gets the time when the object was instantiated.
hasField | Checks if a field exists or not.
hashCode | Gets a hash code for the object.
isReferable | Checks if the object is referable or not.
objectSize | Gets the size of the BasicObject in bytes.
print | Prints an BasicObject.

Methods inherited from logical:
as.data.frame, whichVector

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Converts a vector of ASCII characters into a vector of integers

Description

Converts a vector of ASCII characters to a equal length vector of ASCII integers.

Usage

## Default S3 method:
charToInt(ch, ...)

Arguments

ch | A character vector.
... | Not used.

Value

Returns an ASCII character vector.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

utf8Conversion. intToChar()

Examples

  i <- charToInt(unlist(strsplit("Hello world!", split=NULL)))
  # Gives: 72 101 108 108 111  32 119 111 114 108 100  33
  ch <- intToChar(c(72,101,108,108,111,32,119,111,114,108,100,33))
  # Gives: "H" "e" "l" "l" "o" " " "w" "o" "r" "l" "d" "!"


Checks the compiled Rd files

Description

Checks the compiled Rd files.

Usage

## S3 method for class 'Rdoc':
check(this, manPath=getManPath(this), verbose=FALSE, ...)

Arguments

manPath | The path to the Rd files (character string).
verbose | If TRUE, extra information is outputted.
... | Not used.

Details

Internally the tools package is used.

Value

Returns a printable object, which, if non-empty will show the errors.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


The Class class describes an Object class

Description

Package: R.oo
Class Class

Object
~~|
~~+--Class

Directly known subclasses:

public static class Class
extends Object

The Class class describes an Object class. First of all, this class is most commonly used internally and neither the end user nor the programmer need to no about the class Class.

Usage

Class(name=NULL, constructor=NULL)

Arguments

name | Name of the class.
constructor | Constructor (function) of any Object class.

Details

The class Class describes the Object class or one of its subclasses. All classes and constructors created by setConstructorS3() will be of class Class. Its methods provide ways of accessing static fields and static methods. Its print() method will print detailed information about the class and its fields and methods.

Fields and Methods

Methods:
$ | -
$<- | -
[[ | -
[[<- | -
argsToString | Gets the arguments of a function as a character string.
as.character | Returns a short string describing the class.
forName | Gets a Class object by a name of a class.
getDetails | Lists the fields and methods of a class.
getFields | Returns the field names of a class.
getKnownSubclasses | Gets all subclasses that are currently loaded.
getMethods | Returns the method names of class and its super classes.
getName | Gets the name of the class.
getPackage | Gets the package to which the class belongs.
getRdDeclaration | Gets the class declaraction in Rd format.
getRdHierarchy | Gets the class hierarchy in Rd format.
getRdMethods | Gets the methods of a class in Rd format.
getStaticInstance | Gets the static instance of this class.
getSuperclasses | Gets the super classes of this class.
isAbstract | Checks if a class is abstract or not.
isBeingCreated | Checks if a class is currently being initiated initiated.
isDeprecated | Checks if a class is deprecated or not.
isPrivate | Checks if a class is defined private or not.
isProtected | Checks if a class is defined protected or not.
isPublic | Checks if a class is defined public or not.
isStatic | Checks if a class is static or not.
newInstance | Creates a new instance of this class.
print | Prints detailed information about the class and its fields and methods.

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clone, detach, equals, extend, finalize, gc, getEnvironment, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, objectSize, print, registerFinalizer, save

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Clear fields that are defined to have cached values

Description

Clear fields that are defined to have cached values by assigning NULL to these fields.

Usage

## S3 method for class 'Object':
clearCache(this, ...)

Arguments

... Not used.

Value

Returns itself (invisible).

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

To clear the cached fields and run the garbage collector see *gc(). For more information see Object.


Clones an Object

Description

Creates an identical copy of the object and returns a reference to the new object.

Usage

## S3 method for class 'Object':
clone(this, ...)

Arguments

... Not used.

Details

Please note that no constructors are called during the creation of the clone and neither is any static class code called.

Value

A reference to the new object.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.

Examples

  o1 <- Object()
  o2 <- clone(o1)

  print(equals(o1, o2))


Compile source code files containing Rdoc comments into Rd files

Description

Compile source code files containing Rdoc comments into Rd files.

Note, the class and methods to be compiled have to be loaded into R by for instance library() or source() before calling this method.

Usage

Rdoc$compile(filename=".*[.]R$", destPath=getManPath(this), showDeprecated=FALSE, addTimestamp=TRUE, verbose=FALSE, source=FALSE, check=TRUE, debug=FALSE, ...)

Arguments

filename | The pathname or filename pattern of the Rdoc files to be compiled.
destPath | The path where the generated Rd files should be saved.
showDeprecated | If TRUE, Rd files are generated for deprecated objects too, otherwise not.
addTimestamp | If TRUE, a date and time stamp is added to the Rd header comments. This timestamp might be confusing for version control systems, which is why it can be turned off with FALSE.
source | If TRUE, the Rdoc files will be source()'ed first. This work of course only for Rdoc files that are R source files.
verbose | If TRUE, detailed compilation information is printed.
debug | If TRUE, extra debug information is printed.
... | Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


Creates the directory where the Rd files should be saved

Description

Creates the directory where the Rd files should be saved.

Usage

Rdoc$createManPath(...)

Arguments

... Not used.

Value

Returns TRUE if the directory was creates, FALSE if it already exists and throws an Exception if failed.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getManPath() For more information see Rdoc.


Creates a class-method name

Description

Creates a class-method name.

Usage

Rdoc$createName(class, method, escape=TRUE, ...)

Arguments

class | A class name (character string).
method | A method name (character string).
escape | If TRUE, non-valid filename characters are escaped into valid character strings.
... | Not used.

Value

Returns character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*escapeRdFilename(). For more information see Rdoc.


Gets the class declaration

Description

Gets the class declaration.

Usage

Rdoc$declaration(class, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


Detach an BasicObject from the R search path

Description

Detach, from the R search path, an BasicObject that has previously been attached. If the BasicObject was not attached, a warning will be generated and nothing will be done.

Usage

## S3 method for class 'BasicObject':
detach(this, ...)

Arguments

... Not used.

Value

Returns TRUE if the BasicObject was detached, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*attach() and attach(), detach(). For more information see BasicObject.


Detach an Object from the R search path

Description

Detach, from the R search path, an Object that has previously been attached. If the Object was not attached, a warning will be generated and nothing will be done.

Usage

## S3 method for class 'Object':
detach(this, ...)

Arguments

... Not used.

Value

Returns TRUE if the Object was detached, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*attach() and attach(), detach(). For more information see Object.

Examples

## Not run: For a complete example see help(Object).


Gets the dimension of the object

Description

Gets the dimension of the object similar to what dim() does, but instead of NULL it will return the length of a vector. If a function is passed, NULL is returned.

Usage

## Default S3 method:
dimension(object, ...)

Arguments

object | The object for which the dimension should be obtained.
... | Not used.

Value

Returns an integer vector or NULL.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

ll.default(). dim() and length().

Examples

  dimension(matrix(1:100, ncol=10))     # 10 10
  dimension(1:14)                       # 14
  dimension(data.frame(a=1:10, b=10:1)) # 10  2
  dimension(print)                      # NULL


Makes the fields and methods of an BasicObject accessable via the $ and the [[ operator

Description

Makes the fields and methods of an BasicObject accessable via the $ and the [[ operator.

Usage

  ## S3 method for class 'BasicObject':
  this$name
  ## S3 method for class 'BasicObject':
  this[[name]]

Arguments

name The name of the field or method to be accessed.

Value

Returns the value of a field or a method (function). If no such field or method exists, NULL is returned.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see BasicObject.


Makes the fields and methods of an Class accessable via the $ and the [[ operator

Description

Makes the fields and methods of an Class accessable via the $ operator. This method is never called explicitly, but through an indirect usage of the $ operator, e.g. obj$name or obj$getValue().

  1. This method will first search for a get<Name>() method, e.g. if name has the value "age", a getAge() will be looked for. If such a method exists it will be called with the Class as the first and only argument, e.g. getAge(this). A get<Name>() is only looked for if <name> is not a private field. A private field is a name beginning with a . (period). The rational for this naming convention is to be consistent with how ls() works, which will not list such members by default.
  2. If no such method exists, first then, this method will look a field in the Class can has the name name.
  3. If such neither exists, a method with name name will be searched for and returned.
  4. If no fields or methods are found at all, NULL is returned.

Usage

  ## S3 method for class 'Class':
  this$name
  ## S3 method for class 'Class':
  this[[name]]

Arguments

name | The name of the field or method to be accessed.
... | Not used.

Value

Returns the value of a field or a method (function). If no such field or method exists, NULL is returned.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.

Examples

## Not run: For a complete example see help(Class).


Makes the fields and methods of an Object accessable via the $ and the [[ operator

Description

Makes the fields and methods of an Object accessable via the $ operator. This method is never called explicitly, but through an indirect usage of the $ operator, e.g. obj$name or obj$getValue().

1) This method will first search for a get<Name>() method, e.g. if name has the value "age", a getAge() will be looked for. If such a method exists it will be called with the Object as the first and only argument, e.g. getAge(this).

A get<Name>() is only looked for if <name> is not a private field. A private field is a name beginning with a . (period). The rational for this naming convention is to be consistent with how ls() works, which will not list such members by default.

2) If no such method exists, first then, this method will look a field in the Object can has the name name.

3) If such neither exists, a method with name name will be searched for and returned.

4) Otherwise, a static field will be looked for.

5) If no fields or methods are found at all, NULL is returned.

Usage

  ## S3 method for class 'Object':
  this$name
  ## S3 method for class 'Object':
  this[[name]]

Arguments

name The name of the field or method to be accessed.

Value

Returns the value of a field or a method (function). If no such field or method exists, NULL is returned.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.

Examples

## Not run: For a complete example see help(Object).


Makes the fields and methods of an BasicObject assignable via the $<- and the [[<- operator

Description

Makes the fields and methods of an BasicObject assignable via the $<- and the [[<- operator.

Usage

  ## S3 method for class 'BasicObject':
  this$name <- value
  ## S3 method for class 'BasicObject':
  this[[name]] <- value

Arguments

name The name of the
set<Name>()
method or the name of the field to be assigned the new value.
value The value to be assigned.

Value

Returns itself, i.e. this, as all $<- methods must do.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see BasicObject.


Makes the fields and methods of an Class assignable via the $<- and the [[<- operator

Description

Makes the fields and methods of an Class assignable via the $<- operator. This method is never called explicitly, but through an indirect usage of the $<- operator, e.g. obj$name <- "foo".

  1. This method will first search for a
    set<Name>()
    method, e.g. if name has the value "age", a setAge() will be looked for. If such a method exists it will be called with the Class as the first argument and value as the second, e.g. setAge(this, value). A get<Name>() is only looked for if <name> is not a private field. A private field is a name beginning with a . (period). The rational for this naming convention is to be consistent with how ls() works, which will not list such members by default.
  2. If no such method exists it will assign the value to a (existing or a non-existing) field named name.

Because any

set<Name>()
is called first, it is possible to encapsulate (hide away) fields with certain names or to put restrictions to what values can be assigned to them.

Usage

  ## S3 method for class 'Class':
  this$name <- value
  ## S3 method for class 'Class':
  this[[name]] <- value

Arguments

name The name of the
set<Name>()
method or the name of the field to be assigned the new value.
value The value to be assigned.
... Not used.

Value

Returns itself, i.e. this, as all $<- methods must do.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.

Examples

## Not run: For a complete example see help(Class).


Makes the fields and methods of an Object assignable via the $<- and the [[<- operator

Description

Makes the fields and methods of an Object assignable via the $<- operator. This method is never called explicitly, but through an indirect usage of the $<- operator, e.g. obj$name <- "foo".

1) This method will first search for a set<Name>() method, e.g. if name has the value "age", a setAge() will be looked for. If such a method exists it will be called with the Object as the first argument and value as the second, e.g. setAge(this, value).

A set<Name>() is only looked for if <name> is a non-private field. A private field is a name beginning with a . (period). The rational for this naming convention is to be consistent with how ls() works, which will not list such members by default. Moreover, excluding private fields for the search of a set<Name>() will decrease the overhead for such field.

2) If no such method exists the value will be assigned to an existing field named name, if such exists.

3) Otherwise, the value will be assigned to a static field, if such exists.

4) In all other case, the value is assigned to a new field.

Because any set<Name>() is called first, it is possible to encapsulate (hide away) fields with certain names or to put restrictions to what values can be assigned to them.

Usage

  ## S3 method for class 'Object':
  this$name <- value
  ## S3 method for class 'Object':
  this[[name]] <- value

Arguments

name | The name of the set<Name>() method or the name of the field to be assigned the new value.
value | The value to be assigned.

Value

Returns itself, i.e. this, as all $<- methods must do.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.

Examples

## Not run: For a complete example see help(Object).


Compares an object with another

Description

Compares an object with another and returns TRUE if they are equal. The equal property must be

1) reflexive, i.e. equals(o1,o1) should be TRUE.

2) symmetric, i.e. equals(o1,o2) is TRUE if and only if equals(o2,o1) is TRUE.

3) transitive, i.e. equals(o1,o2) is TRUE and equals(o2,o3) is TRUE, then equals(o1,o3) should be TRUE.

5) consistent, i.e. equals(o1,o2) should return the same result on multiple invocations as long as nothing has changed.

6) equals(o1,NULL) should return FALSE.

By default identical() is used.

Usage

## Default S3 method:
equals(object, other, ...)

Arguments

object, other | Objects to be compared.
... | Not used.

Value

Returns TRUE if the objects are equal, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

identical().


Compares an object with another

Description

Compares an object with another and returns TRUE if they are equal. The equal property must be

1) reflexive, i.e. equals(o1,o1) should be TRUE.

2) symmetric, i.e. equals(o1,o2) is TRUE if and only if equals(o2,o1) is TRUE.

3) transitive, i.e. equals(o1,o2) is TRUE and equals(o2,o3) is TRUE, then equals(o1,o3) should be TRUE.

5) consistent, i.e. equals(o1,o2) should return the same result on multiple invocations as long as noting has changed.

6) equals(o1,NULL) should return FALSE.

By default, the method returns TRUE if and only if the two references compared refer to the same BasicObject, i.e. ( !is.null(obj) && (hashCode(this) == hashCode(obj)) ).

Usage

## S3 method for class 'BasicObject':
equals(this, other, ...)

Arguments

other | The other object this object should be compared to.
... | Not used.

Value

Returns TRUE if the objects are equal, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see BasicObject.


Compares an object with another

Description

Compares an object with another and returns TRUE if they are equal. The equal property must be

1) reflexive, i.e. equals(o1,o1) should be TRUE.

2) symmetric, i.e. equals(o1,o2) is TRUE if and only if equals(o2,o1) is TRUE.

3) transitive, i.e. equals(o1,o2) is TRUE and equals(o2,o3) is TRUE, then equals(o1,o3) should be TRUE.

5) consistent, i.e. equals(o1,o2) should return the same result on multiple invocations as long as nothing has changed.

6) equals(o1,NULL) should return FALSE.

By default, the method returns TRUE if and only if the two references compared refer to the same Object, i.e. ( !is.null(obj) && (hashCode(this) == hashCode(obj)) ).

Usage

## S3 method for class 'Object':
equals(this, other, ...)

Arguments

other | The other object this Object should be compared to.
... | Not used.

Value

Returns TRUE if the Object's are equal, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*hashCode(). For more information see Object.

Examples

  o1 <- Object()
  o2 <- clone(o1)
  equals(o1, o1)    # TRUE
  equals(o1, o2)    # FALSE


Escape non-valid characters in a filename

Description

Escape non-valid characters in a filename.

Usage

Rdoc$escapeRdFilename(filename, ...)

Arguments

filename | A filename (character string) to be escaped.
... | Not used.

Value

Returns character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


The Exception class to be thrown and caught

Description

Package: R.oo
Class Exception

Object
~~|
~~+--try-error
~~~~~~~|
~~~~~~~+--condition
~~~~~~~~~~~~|
~~~~~~~~~~~~+--error
~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~+--simpleError
~~~~~~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~~~~~~+--Exception

Directly known subclasses:
InternalErrorException, RccViolationException, RdocException

public static class Exception
extends simpleError

Creates an Exception that can be thrown and caught. The Exception class is the root class of all other Exception classes.

Usage

Exception(..., sep="", collapse=", ")

Arguments

... | One or several strings, which will be concatenated and contain informative message about the exception.
sep | The string to used for concatenating several strings.
collapse | The string to used collapse vectors together.

Fields and Methods

Methods:
as.character | Gets a character string representing of the Exception.
getCall | -
getLastException | Static method to get the last Exception thrown.
getMessage | Gets the message of the Exception.
getStackTrace | Gets the stack trace saved when the exception was created.
getStackTraceString | Gets the stack trace as a string.
getWhen | Gets the time when the Exception was created.
print | Prints the Exception.
printStackTrace | Prints the stack trace saved when the exception was created.
throw | Throws an Exception that can be caught.

Methods inherited from error:
as.character, throw

Methods inherited from condition:
as.character, conditionCall, conditionMessage, print

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clone, detach, equals, extend, finalize, gc, getEnvironment, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, objectSize, print, registerFinalizer, save

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

See also tryCatch() (and try()).

Examples

######################################################################
# 1. To catch a regular "error" exception thrown by e.g. stop().
######################################################################
x <- NA
y <- NA
tryCatch({
  x <- log(123);
  y <- log("a");
}, error = function(ex) {
  print(ex);
})
print(x)
print(y)

######################################################################
# 2. Always run a "final" expression regardless or error or not.
######################################################################
filename <- tempfile("R.methodsS3.example")
con <- file(filename)
tryCatch({
  open(con, "r");
}, error = function(ex) {
  cat("Could not open ", filename, " for reading.\n", sep="")
}, finally = {
  close(con)
  cat("The id of the connection is ",
       ifelse(is.null(con), "NULL", con), ".\n", sep="")
})

######################################################################
# 3. Creating your own Exception class
######################################################################
setConstructorS3("NegativeLogValueException", function(
  msg="Trying to calculate the logarithm of a negative value", value=NULL) {
  extend(Exception(msg=msg), "NegativeLogValueException",
    .value = value
  )
})

setMethodS3("as.character", "NegativeLogValueException", function(this, ...) {
  paste(as.character.Exception(this), ": ", getValue(this), sep="");
})

setMethodS3("getValue", "NegativeLogValueException", function(this, ...) {
  this$.value;
})

mylog <- function(x, base=exp(1)) {
  if (x < 0)
    throw(NegativeLogValueException(value=x))
  else
    log(x, base=base)
}

# Note that the order of the catch list is important:
l <- NA;
x <- 123;
tryCatch({
  l <- mylog(x);
}, NegativeLogValueException = function(ex) {
  cat(as.character(ex), "\n")
}, "try-error" = function(ex) {
  cat("try-error: Could not calculate the logarithm of ", x, ".\n", sep="")
}, error = function(ex) {
  cat("error: Could not calculate the logarithm of ", x, ".\n", sep="")
})
cat("The logarithm of ", x, " is ", l, ".\n\n", sep="")


Extends a object

Description

Simply speaking this method "extends" the class of an object. What is actually happening is that it creates an instance of class name ...className, by taking another object and add ...className to the class list and also add all the named values in ... as attributes.

The method should be used by the constructor of a class and nowhere else.

Usage

## Default S3 method:
extend(this, ...className, ...)

Arguments

this | Object to be extended.
...className | The name of new class.
... | Attribute fields of the new class.

Value

Returns an object of class ...className.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

Examples

setConstructorS3("MyDouble", function(value=0, ...) {
  extend(as.double(value), "MyDouble", ...)
})

setMethodS3("as.character", "MyDouble", function(object, ...) {
  fmtstr <- attr(object, "fmtstr")
  if (is.null(fmtstr))
    fmtstr <- "%.6f"
  sprintf(fmtstr, object)
})

setMethodS3("print", "MyDouble", function(object, ...) {
  print(as.character(object), ...)
})

x <- MyDouble(3.1415926)
print(x)

x <- MyDouble(3.1415926, fmtstr="%3.2f")
print(x)
attr(x, "fmtstr") <- "%e"
print(x)

setConstructorS3("MyList", function(value=0, ...) {
  extend(list(value=value, ...), "MyList")
})

setMethodS3("as.character", "MyList", function(object, ...) {
  fmtstr <- object$fmtstr
  if (is.null(fmtstr))
    fmtstr <- "%.6f"
  sprintf(fmtstr, object$value)
})

setMethodS3("print", "MyList", function(object, ...) {
  print(as.character(object), ...)
})

x <- MyList(3.1415926)
print(x)
x <- MyList(3.1415926, fmtstr="%3.2f")
print(x)
x$fmtstr <- "%e"
print(x)


Extends another class

Description

Simply speaking this method "extends another class". What is actually happening is that it creates an instance of class name ...className, by taking another BasicObject instance and add ...className to the class list and also add all the named values in ... as fields to the new instance.

The method should be used by the constructor of a class and nowhere else.

Usage

## S3 method for class 'BasicObject':
extend(this, ...className, ...)

Arguments

...className | The name of new class.
... | Named values representing the fields of the new instance.

Value

Returns an BasicObject of class className.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see BasicObject.


Extends another Interface class

Description

Extends another Interface class.

Usage

## S3 method for class 'Interface':
extend(this, ...className, ...)

Arguments

...className | The name of new interface.
... | Named values representing the fields of the new instance.

Value

Returns an Interface of class className.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Interface.


Extends another class

Description

Simply speaking this method "extends another class". What is actually happening is that it creates an instance of class name ...className, by taking another Object instance and add ...className to the class list and also add all the named values in ... as fields to the new instance.

The method should be used by the constructor of a class and nowhere else.

Usage

## S3 method for class 'Object':
extend(this, ...className, ..., ...fields=NULL)

Arguments

...className | The name of new class.
... | Named values representing the fields of the new instance.
...fields | An optional named list of fields. This makes it possible to specify a set of fields using a list object.

Details

The reason for the strange name of argument "...className" is that if one tries to set a field with a name that is a prefix of the name of this arguments and one at the same time does not specify the name of this argument one would run into strange errors. For instance, try extend(Object(), "MyClass", ...c=0).

Value

Returns an Object of class className.

Field modifiers

It is possible to specify modifiers to some of the fields. Currently it is only the cached modifier that is recognized. A field that is cached will be assigned NULL when *clearCache() (or *gc()) is called. To specify a modifier, append a comma separated list of modifiers followed by a colon, e.g. "cached:foo".

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.

Examples

## Not run: For a complete example see help(Object).


Finalizer methods called when object is clean out

Description

The finalizer method should never be called explicitly!. Finalizer methods called just before the object is about to be deleted by the garbage collector.

Usage

## S3 method for class 'Object':
finalize(this, ...)

Arguments

... Not used.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.

Examples

  setConstructorS3("MyClass", function() {
    extend(Object(), "MyClass")
  })

  setMethodS3("finalize", "MyClass", function(this) {
    cat(as.character(this), "is about to be removed from the memory!\n")
  })

  o <- MyClass()
  o <- MyClass()
  o <- MyClass()
  o <- MyClass()
  gc()

  ## Not run:
  MyClass: 0x01BE602C is about to be removed from the memory!
  MyClass: 0x01BFF634 is about to be removed from the memory!
  MyClass: 0x01C13584 is about to be removed from the memory!
           used (Mb) gc trigger (Mb)
  Ncells 229903  6.2     467875 12.5
  Vcells  53725  0.5     786432  6.0

## End(Not run)

  rm(o)
  ## Not run:
  MyClass: 0x01C578B0 is about to be removed from the memory!
           used (Mb) gc trigger (Mb)
  Ncells 229903  6.1     467875 12.3
  Vcells  53725  0.5     786432  6.0

## End(Not run)


Gets a Class object by a name of a class

Description

Gets a Class object by a name of a class. If no such class exists and exception is thrown.

Usage

Class$forName(name, ...)

Arguments

... Not used.

Value

Returns a Class.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

class(). setConstructorS3(). For more information see Class.

Examples

  print(Class$forName("Exception"))


Clear cached fields and calls the garbage collector

Description

Clear cached fields and calls the garbage collector. Cached fields are set to NULL when cleared.

Usage

## S3 method for class 'Object':
gc(this, ...)

Arguments

... Not used.

Value

Returns what gc() returns.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

To clear the fields without calling the garbage collector, see *clearCache(). For more information see Object.

Examples

setConstructorS3("CachedObject", function(...) {
  extend(Object(), "CachedObject",
    ...
  )
})

setMethodS3("as.character", "CachedObject", function(this, ...) {
  s <- NextMethod("as.character", this, ...)
  s <- sprintf("%s. RAM: %.2fkb.", s, objectSize(this)/1024)
  s
})

obj <- CachedObject(a=1, b=1:10^5, "cached:c"=1:10^6)
print(ll(obj))
print(obj) # [1] "CachedObject: 0x02466E28. RAM: 4297.16kb."

gc(obj)         # Clear all cached fields
print(ll(obj))
print(obj) # [1] "CachedObject: 0x02466E28. RAM: 391.05kb."


Gets the Author of this package

Description

Gets the Author of this package as specified by the DESCRIPTION file.

Usage

## S3 method for class 'Package':
getAuthor(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("R.oo")
  print(getAuthor(pkg))


Gets the Bundle that this package might belong to

Description

Gets the Bundle that this package might belong to as specified by the DESCRIPTION file.

Usage

## S3 method for class 'Package':
getBundle(this, ...)

Arguments

... Not used.

Details

The first call to this method is normally slow because all installed packages are scanned. The result of this first call is cached and used as the return value for all subsequent calls, which are then much faster.

Value

If the package is part of a bundle, the name of the bundle is returned. Otherwise, NULL is returned.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("R.oo")
  print(getBundle(pkg))


Gets the names of the other packages that is in the same bundle as this package

Description

Gets the names of the other packages that is in the same bundle as this package as specified by the DESCRIPTION file.

Usage

## S3 method for class 'Package':
getBundlePackages(this, ...)

Arguments

... Not used.

Details

The first call to this method is normally slow because all installed packages are scanned. The result of this first call is cached and used as the return value for all subsequent calls, which are then much faster.

Value

Returns a character vector of package names or NULL.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("R.oo")
  print(getBundle(pkg))


Gets the change log of this package

Description

Gets the change log of this package, that is, (by default) the NEWS (then the HISTORY and ChangeLog) file, which should is expected to be located in the root directory of the package, i.e. *getPath().

Usage

## S3 method for class 'Package':
getChangeLog(this, filenames=c("NEWS", "HISTORY", "ChangeLog"), newline="
", ...)

Arguments

filenames | A character vector of (non-case sensitive) filenames to be searched for.
newline | The character string to collapse lines in the file.
... | Not used.

Value

Returns the complete contents of the change log file as a character string. If not found, NULL is returned.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Gets all classes of a package

Description

Gets all classes of a package.

Usage

## S3 method for class 'Package':
getClasses(this, ...)

Arguments

... Not used.

Value

Returns a character vector of class names.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("R.oo")
  print(getClasses(pkg))


Gets the usage of a S4 class

Description

Gets the usage of a S4 class.

Usage

Rdoc$getClassS4Usage(class, ...)

Arguments

class | A class name (character string).
... | Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


Get a constructor method

Description

Get a constructor method.

Usage

## Default S3 method:
getConstructorS3(name, ...)

Arguments

name | The name of the constructor function.
... | Not used.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

setConstructorS3(). getMethodS3. isGenericS3.


Gets the contents of this package

Description

Gets the contents of this package, i.e. the parsed CONTENTS file.

Usage

## S3 method for class 'Package':
getContents(this, fields=NULL, ...)

Arguments

... Not used.

Value

Returns a data.frame.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

dcf. For more information see Package.


Gets the URL(s) from where this package can be installed

Description

Gets the URL(s) from where this package can be installed by first looking for comma or semicolon separated URLs at the optional ContribURL line in the DESCRIPTION file of the package. If no such line exists, getUrl() is used.

Usage

## S3 method for class 'Package':
getContribUrl(this, ...)

Arguments

... Not used.

Value

Returns a vector of character strings.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("R.oo")
  print(getContribUrl(pkg))


Gets the path to the data (data/) directory of this package

Description

Gets the path to the data (data/) directory of this package.

Usage

## S3 method for class 'Package':
getDataPath(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Gets the date when package was build

Description

Checks if the package is loaded onto the search path or not.

Usage

## S3 method for class 'Package':
getDate(this, ...)

Arguments

... Not used.

Value

TRUE if the packages has been loaded, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("base")
  print(isLoaded(pkg))       # TRUE


Gets the description of the package

Description

Gets the description of the package. Not to be mixed up with *getDescriptionFile().

Usage

## S3 method for class 'Package':
getDescription(this, replaceNewlines=" ", ...)

Arguments

replaceNewlines | If a character string, all newline characters are replaced with this string. Otherwise not.
... | Not used.

Value

A character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("base")
  print(getDescription(pkg))


Gets the description file of this package

Description

Gets the description file of this package, i.e. the parsed DESCRIPTION file.

Usage

## S3 method for class 'Package':
getDescriptionFile(this, fields=NULL, ...)

Arguments

fields | A vector of character strings of fields to be returned. If NULL, all available fields are returned.
... | Not used.

Value

Returns named vector of character strings.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Lists the fields and methods of a class

Description

Lists the fields and methods of a class (or an object).

Usage

## S3 method for class 'Class':
getDetails(this, private=FALSE, ...)

Arguments

... Not used.

Value

Returns an invisible character string of the class information.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

Examples

  getDetails(Exception)


Gets the URL(s) from where the developers version of this package can be installed

Description

Gets the URL(s) from where the developers version of this package can be installed by looking for comma or semicolon separated URLs at the optional DevelURL line in the DESCRIPTION file of the package.

Usage

## S3 method for class 'Package':
getDevelUrl(this, ...)

Arguments

... Not used.

Value

Returns a vector of character strings.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("R.oo")
  print(getDevelUrl(pkg))


Gets the path to the accompanying documentation (doc/) directory of this package

Description

Gets the path to the accompanying documentation (doc/) directory of this package.

Usage

## S3 method for class 'Package':
getDocPath(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  print(list.files(getDocPath(R.oo)))   # explicit call, or
  print(list.files(R.oo$docPath))       # as a virtual field


Gets the environment of this object

Description

Gets the environment of this object. This is the environment where the members of the Object are stored.

Usage

## S3 method for class 'Object':
getEnvironment(fun, ...)

Arguments

... Not used.

Value

Returns an environment.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.

Examples

  ll(R.oo)
  ll(envir=getEnvironment(R.oo))


Gets the environment of a loaded package

Description

Gets the environment of a loaded package.

Usage

## S3 method for class 'Package':
getEnvironment(this, ...)

Arguments

... Not used.

Value

Returns a environment, or NULL if the package was not loaded.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getPosition(). For more information see Package.


Gets the path to the example (R-ex/) directory of this package

Description

Gets the path to the example (R-ex/) directory of this package.

Usage

## S3 method for class 'Package':
getExamplePath(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Returns the field names of an BasicObject

Description

Returns the field names of an BasicObject.

Usage

## S3 method for class 'BasicObject':
getFields(this, private=FALSE, ...)

Arguments

private | If TRUE, private fields will also be returned, otherwise only public fields are returned.
... | Not used.

Value

Returns a character vector of field names.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

To check if a field exists or not, see *hasField(). For more information see BasicObject.


Returns the field names of a class

Description

Returns the field names of a class.

Usage

## S3 method for class 'Class':
getFields(this, private=FALSE, ...)

Arguments

private | If TRUE, private fields will also be returned, otherwise only public fields are returned.
... | Not used.

Value

Returns a character vector of field names.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.

Examples

  print(getFields(Exception))


Returns NULL

Description

Returns NULL.

Usage

## S3 method for class 'Interface':
getFields(...)

Arguments

... Ignored.

Value

Always returns NULL.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Interface.


Returns the field names of an Object

Description

Returns the field names of an Object.

Usage

## S3 method for class 'Object':
getFields(this, private=FALSE, ...)

Arguments

private | If TRUE, private fields will also be returned, otherwise only public fields are returned.
... | Not used.

Value

Returns a character vector of field names.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

To check if a field exists or not, see *hasField(). For more extensive information about the fields in an Object see *ll(). For more information see Object.

Examples

   obj <- Object()
   obj$x <- 1:100
   obj$y <- 100:1
   getFields(obj)

   ## Not run:
   gives:

   [1] "x" "y"

## End(Not run)


Gets the howToCite of this package

Description

Gets the howToCite of this package, i.e. the HOWTOCITE file, which should is expected to be located in the root directory of the package, i.e. *getPath().

Usage

## S3 method for class 'Package':
getHowToCite(this, newline="
", ...)

Arguments

newline | The character string to collapse lines in the file.
... | Not used.

Value

Returns the complete contents of the HOWTOCITE file as a character string. If not found, NULL is returned.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Gets the time when the object was instantiated

Description

Gets the time when the object was instantiated (created) as a POSIXt object.

Usage

## S3 method for class 'BasicObject':
getInstantiationTime(this, ...)

Arguments

... Not used.

Value

Returns a POSIXt object, which extends class POSIXct.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more about time formats and POSIX see DateTimeClasses. For more information see BasicObject.


Gets the time when the object was instantiated

Description

Gets the time when the object was instantiated (created) as a POSIXt object.

Usage

## S3 method for class 'Object':
getInstantiationTime(this, ...)

Arguments

... Not used.

Value

Returns a POSIXt object, which extends class POSIXct.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more about time formats and POSIX see DateTimeClasses. For more information see Object.

Examples

  obj <- Object()
  print(getInstantiationTime(obj))


Gets the memory location where the Object resides

Description

Gets the memory location where the Object resides.

Usage

## S3 method for class 'Object':
getInternalAddress(this, ...)

Arguments

... Not used.

Value

Returns a double (can hold 64-bit addresses, whereas an integer can only hold 32-bit addresses).

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

getName(). For more information see Object.

Examples

  obj <- Object()
  getInternalAddress(obj)    # 26979608


Gets the keywords defined in R with descriptions

Description

Gets the keywords defined in R with descriptions.

Usage

Rdoc$getKeywords(fullInfo=FALSE, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*setManPath() For more information see Rdoc.


Gets all subclasses that are currently loaded

Description

Gets all subclasses that are currently loaded.

Usage

## S3 method for class 'Class':
getKnownSubclasses(this, sort=TRUE, ...)

Arguments

... Not used.

Value

Returns a vector of character strings.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getSuperclasses(). For more information see Class.

Examples

  ## Not run:
  # Due to a bug in R CMD check (R v1.7.1) the MicroarrayData$read() call
  # below will call getKnownSubclasses(), which will generate
  #   "Error in exists(objectName, mode = "function") :
  #        [2003-07-07 23:32:41] Exception: F used instead of FALSE"
  # Note that the example still work, just not in R CMD check

  print(getKnownSubclasses(Exception))
  ## End(Not run)
  ## Not run:
  returns
  [1] "Exception" "try-error" "Object"

## End(Not run)


Gets the known subclasses

Description

Gets the known subclasses.

Usage

## S3 method for class 'classRepresentation':
getKnownSubclasses(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Static method to get the last Exception thrown

Description

Static method to get the last Exception instanciated.

Usage

Exception$getLastException(...)

Arguments

... Not used.

Value

Returns an Exception object.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Exception. See also tryCatch().

Examples

## Not run: For a complete example see help(Exception).


Gets the License of this package

Description

Gets the License of this package as specified by the DESCRIPTION file.

Usage

## S3 method for class 'Package':
getLicense(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("R.oo")
  print(getLicense(pkg))


Gets the Maintainer of this package

Description

Gets the Maintainer of this package as specified by the DESCRIPTION file.

Usage

## S3 method for class 'Package':
getMaintainer(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("R.oo")
  print(getMaintainer(pkg))


Gets the path to the directory where the Rd files will be saved

Description

Gets the path to the directory where the Rd files will be saved.

Usage

Rdoc$getManPath(...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*setManPath() For more information see Rdoc.


Gets the message of the Exception

Description

Gets the message of the Exception.

Usage

## S3 method for class 'Exception':
getMessage(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Exception.

Examples

## Not run: For a complete example see help(Exception).


Gets the message of the exception

Description

Gets the message of the exception and adds a message that clarifies that the error is likely due to an internal error and not due to the user. It also gives information how to contact the maintainer or author of the suspicous package. This information is retrieved from the DESCRIPTION file of the package. To help the package developer, information about the current version of R, the current version of the package etc are also returned so the user can easily cut'n'paste that information into a bug report.

Usage

## S3 method for class 'InternalErrorException':
getMessage(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see InternalErrorException.


Returns the method names of class and its super classes

Description

Returns the method names of class and its super classes as a list.

Usage

## S3 method for class 'Class':
getMethods(this, private=FALSE, deprecated=TRUE, unique=TRUE, ...)

Arguments

private | If TRUE, private methods are also returned, otherwise only public ones are returned.
deprecated | If TRUE, deprecated methods are also returned.
unqiue | If TRUE, only methods that are not implemented in one of the subclasses are returned for each class.
... | Not used.

Value

Returns a named list of named character strings.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.

Examples

  l <- getMethods(Exception)
  print(l)


Gets the name of the class

Description

Gets the name of the class.

Usage

## S3 method for class 'Class':
getName(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.

Examples

  print(getName(Object))   # "Object"
  print(getName(Class))    # "Class"


Gets the name of an environment

Description

Gets the name of an environment, e.g. "R_GlobalEnv" or "0x01ddd060".

Usage

## S3 method for class 'environment':
getName(env, ...)

Arguments

env | An environment.
... | Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

environmentName().

Examples

  name <- getName(globalenv())
  print(name)
  stopifnot(identical(name, "R_GlobalEnv"))

  getName(new.env())


Gets the name of this package

Description

Gets the name of this package.

Usage

## S3 method for class 'Package':
getName(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Gets the current name format

Description

Gets the current name format.

Usage

Rdoc$getNameFormat(...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*setNameFormat() For more information see Rdoc.


Gets the package to which the class belongs

Description

Gets the package to which the class belongs.

Usage

## S3 method for class 'Class':
getPackage(this, ...)

Arguments

... Not used.

Value

Returns a Package.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

Package. class(). setConstructorS3(). For more information see Class.

Examples

  print(getPackage(Object))


Gets the suspicious package likely to contain an error

Description

Gets the suspicious package likely to contain an error.

Usage

## S3 method for class 'InternalErrorException':
getPackage(this, ...)

Arguments

... Not used.

Value

Returns a Package object.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see InternalErrorException.


Gets the package of a method or an object

Description

Gets the package of a method or an object.

Usage

Rdoc$getPackageNameOf(objectName, mode="any", unique=TRUE, ...)

Arguments

objectName | An method or object name (character string).
mode | Mode of object (character string).
unique | If TRUE, only the first matching package is returned if more than one is found.
... | Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


Gets the library (system) path to this package

Description

Gets the library (system) path to this package.

Usage

## S3 method for class 'Package':
getPath(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Gets the search path position of the package

Description

Gets the search path position of the package.

Usage

## S3 method for class 'Package':
getPosition(this, ...)

Arguments

... Not used.

Value

An integer.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getEnvironment(). search(). For more information see Package.

Examples

  pkg <- Package("base")
  print(getPosition(pkg))


Static method to get a URL where the RCC can be found

Description

Static method to get a URL where one can find details about the R Code Convention (RCC). Currently the URL is http://www.maths.lth.se/help/R/RCC/.

Usage

RccViolationException$getRccUrl(...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see RccViolationException.

Examples

## Not run: For a complete example see help(RccViolationException).


Gets the class declaraction in Rd format

Description

Gets the class declaraction in Rd format.

Usage

## S3 method for class 'Class':
getRdDeclaration(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.


Gets the class declaration in Rd format

Description

Gets the class declaration in Rd format.

Usage

## S3 method for class 'classRepresentation':
getRdDeclaration(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Gets the class hierarchy in Rd format

Description

Gets the class hierarchy in Rd format.

Usage

## S3 method for class 'Class':
getRdHierarchy(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.


Gets the class hierarchy in Rd format

Description

Gets the class hierarchy in Rd format.

Usage

## S3 method for class 'classRepresentation':
getRdHierarchy(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Gets the methods of a class in Rd format

Description

Gets the methods of a class in Rd format.

Usage

## S3 method for class 'Class':
getRdMethods(class, visibilities=c("private", "protected", "public"), ...)

Arguments

visibilities | A character string specifying what types of methods to return.
... | Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.


Gets the methods in Rd format

Description

Gets the methods in Rd format.

Usage

## S3 method for class 'classRepresentation':
getRdMethods(class, visibility=c("public", "protected", "private"), trial=FALSE, ...)

Arguments

visibility | -
trial | -
... | Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Extracts the title string of a Rd file

Description

Extracts the title string of a Rd file corresponding the the specified method of the specified class.

Usage

Rdoc$getRdTitle(class, method, ...)

Arguments

method | The method to be search for.
class | The class the method belongs to.
... | Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


Gets the source of the exception

Description

.

Usage

## S3 method for class 'RdocException':
getSource(this, ...)

Arguments

... Not used.

Value

Returns the source.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see RdocException.


Gets the stack trace saved when the exception was created

Description

.

Usage

## S3 method for class 'Exception':
getStackTrace(this, ...)

Arguments

... Not used.

Value

Returns a list containing the stack trace.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*printStackTrace().
dump.frames().
tryCatch().
For more information see Exception.

Examples

## Not run: For a complete example see help(Exception).


Gets the stack trace as a string

Description

.

Usage

## S3 method for class 'Exception':
getStackTraceString(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getStackTrace(). For more information see Exception.


Gets the static instance of this class

Description

Gets the static instance of this class.

Usage

## S3 method for class 'Class':
getStaticInstance(this, ...)

Arguments

... Not used.

Value

Returns a reference to an Object.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.

Examples

  obj <- getStaticInstance(Object)


Gets the static instance of this objects class

Description

Gets the static instance of this objects class.

Usage

## S3 method for class 'Object':
getStaticInstance(this, ...)

Arguments

... Not used.

Value

Returns a reference to an Object.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.

Examples

  ex <- Exception("Oops!")
  obj <- getStaticInstance(ex)


Gets the super classes of this class

Description

Gets the super classes of this class.

Usage

## S3 method for class 'Class':
getSuperclasses(this, ...)

Arguments

... Not used.

Value

Returns a vector of character strings.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

class(). *getKnownSubclasses(). For more information see Class.

Examples

  print(getSuperclasses(RccViolationException))
  ## Not run:
  returns
  [1] "Exception" "try-error" "Object"

## End(Not run)


Gets the superclasses

Description

Gets the superclasses.

Usage

## S3 method for class 'classRepresentation':
getSuperclasses(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Gets the Title of this package

Description

Gets the Title of this package as specified by the DESCRIPTION file.

Usage

## S3 method for class 'Package':
getTitle(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("R.oo")
  print(getTitle(pkg))


Gets the URL of this package

Description

Gets the URL of this package as specified by the DESCRIPTION file.

Usage

## S3 method for class 'Package':
getUrl(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  pkg <- Package("R.oo")
  print(getUrl(pkg))


Gets the usage of a method

Description

Gets the usage of a method.

Usage

Rdoc$getUsage(method, class=NULL, ...)

Arguments

method | A method name (character string).
class | An optional class name (character string).
... | Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


Gets the version of this package

Description

Gets the version of this package.

Usage

## S3 method for class 'Package':
getVersion(this, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Gets the time when the Exception was created

Description

Gets the time, as a POSIX object, when the Exception was created.

Usage

## S3 method for class 'Exception':
getWhen(this, ...)

Arguments

... Not used.

Value

Returns a POSIX time object.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Exception.

Examples

## Not run: For a complete example see help(Exception).


Checks if a field exists or not

Description

Checks if a field exists or not.

Usage

## S3 method for class 'BasicObject':
hasField(this, field, ...)

Arguments

field | vector of fields to be checked if they exists or not.
... | Not used.

Value

Returns a logical vector indicating for each field if it exists or not.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

To get the fields of an Object, see *getFields(). For more information see BasicObject.


Checks if a field exists or not

Description

Checks if a field exists or not.

Usage

## S3 method for class 'Object':
hasField(this, field, ...)

Arguments

field | vector of fields to be checked if they exists or not.
... | Not used.

Value

Returns a logical vector indicating for each field if it exists or not.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

To get the fields of an Object, see *getFields(). For more extensive information about the fields in an Object see *ll(). For more information see Object.

Examples

   obj <- Object()
   obj$x <- 1:100
   obj$y <- 100:1
   hasField(obj, c("x", "a", "b", "y"))

   ## Not run:
   gives:

   [1] TRUE FALSE FALSE TRUE

## End(Not run)


Gets an integer hashcoded for R objects

Description

Gets an integer hashcoded for R objects.

Usage

## Default S3 method:
hashCode(object, ...)

Arguments

object | A vector or list of R objects.
... | Not used.

Details

A character string is converted into a hashcode following Java conventions by s[1]*31^(n-1) + s[2]*31^(n-2) + ... + s[n] using integer arithmetic, where s[i] is the i:th character of the string, n is the length of the string. The hash value of the empty string is zero.

For all other objects, by default as.integer() is called.

Value

Returns a vector of integer's.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Gets a hash code for the object

Description

Gets a hash code for the object.

Usage

## S3 method for class 'BasicObject':
hashCode(this, ...)

Arguments

... Not used.

Value

Returns an integer.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*equals() For more information see BasicObject.


Gets a hash code for the Object

Description

Gets a hash code for the Object. This makes it possible to put any Object in a hash table.

The hash code returned must:

1) be consistent, i.e. hashCode(obj) should return the same value on multiple invocations as long as nothing has changed.

2) tell same same thing as equals(), if equals(o1,o2) is TRUE, then hashCode(o1) == hashCode(o2) should also be TRUE.

Note that if equals(o1,o2) is FALSE, hashCode(o1) hashCode(o2) may be either equal or non-equal.

By default, the method returns the internal memory address where the Object is located.

Usage

## S3 method for class 'Object':
hashCode(this, ...)

Arguments

... Not used.

Value

Returns a double.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*equals() For more information see Object.

Examples

  obj <- Object()
  hashCode(obj)          # 26979608


Gets the class hierarchy

Description

Gets the class hierarchy.

Usage

Rdoc$hierarchy(class, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


The Interface class

Description

Package: R.oo
Class Interface

+--Interface

Directly known subclasses:

public class Interface

This class represents a special set of classes whose purpose is to provide methods (but not fields) shared by multiple different classes.

Usage

Interface(core=NA, ...)

Arguments

core | The core value.
... | Not used.

Methods

Methods:
extend | Extends another Interface class.
print | Prints an Interface.
uses | Specifies that an object uses this Interface.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


InternalErrorException represents internal errors

Description

Package: R.oo
Class InternalErrorException

Object
~~|
~~+--try-error
~~~~~~~|
~~~~~~~+--condition
~~~~~~~~~~~~|
~~~~~~~~~~~~+--error
~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~+--simpleError
~~~~~~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~~~~~~+--Exception
~~~~~~~~~~~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~~~~~~~~~~~+--InternalErrorException

Directly known subclasses:

public static class InternalErrorException
extends Exception

InternalErrorException represents internal errors that are likely to be due to implementation errors done by the author of a specific package and not because the user made an error. Errors that are due to unexpected input to functions etc falls under this error type.

Usage

InternalErrorException(..., package=NULL)

Arguments

... | Any arguments accepted by Exception
package | The name (character string) of the package where the error exists. Can also be a Package object. If NULL, the source of the error is assumed to be unknown.

Fields and Methods

Methods:
getMessage | Gets the message of the exception.
getPackage | Gets the suspicious package likely to contain an error.

Methods inherited from Exception:
as.character, getCall, getLastException, getMessage, getStackTrace, getWhen, print, printStackTrace, throw

Methods inherited from error:
as.character, throw

Methods inherited from condition:
as.character, conditionCall, conditionMessage, print

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clone, detach, equals, extend, finalize, gc, getEnvironment, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, objectSize, print, registerFinalizer, save

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For detailed information about exceptions see Exception.


Converts a vector of integers into a vector of ASCII characters

Description

Converts a vector of ASCII integers to a equal length vector of ASCII characters. To make sure that all values in the input vector are in the range [0,255], the input vector is taken modulo 256.

Usage

## Default S3 method:
intToChar(i, ...)

Arguments

i | An integer vector.
... | Not used.

Value

Returns a ASCII integer vector.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

utf8Conversion. charToInt()

Examples

  i <- charToInt(unlist(strsplit("Hello world!", split=NULL)))
  # Gives: 72 101 108 108 111  32 119 111 114 108 100  33
  ch <- intToChar(c(72,101,108,108,111,32,119,111,114,108,100,33))
  # Gives: "H" "e" "l" "l" "o" " " "w" "o" "r" "l" "d" "!"


Checks if a class is abstract or not

Description

Checks if a class is abstract or not. A class is abstract if it has abstract methods.

Usage

## S3 method for class 'Class':
isAbstract(this, ...)

Arguments

... Not used.

Value

Returns TRUE if the class is abstract, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

class(). setConstructorS3(). For more information see Class.

Examples

  if (isAbstract(RccViolationException))
    throw("The class RccViolationException should NOT be abstract.")


Checks if a class is currently being initiated initiated

Description

Checks if a class is currently being initiated initiated. When extending a class for the first time, which is typically done in a constructor, a static instance of the class is created by calling the constructor without parameters. This method provides a way to detect that second call inside the constructor.

Usage

## S3 method for class 'Class':
isBeingCreated(this, ...)

Arguments

... Not used.

Value

Returns TRUE if a static instance exists, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.

Examples

setConstructorS3("Car", function(brand=NULL, nbrOfWheels=0) {
  if(!isBeingCreated(Car)) {
    if (is.null(brand))
      throw("A car must have a brand")

    if (nbrOfWheels <= 0)
      throw("A car must have one or more wheels: ", nbrOfWheels)
  }

  extend(Object(), "Car",
    .brand = brand,
    .nbrOfWheels = nbrOfWheels
  )
})

setMethodS3("as.character", "Car", function(this, ...) {
  cat(class(this)[1], ":", this$.brand, " with ",
                     this$.nbrOfWheels, " wheels.", sep="");
})

print(Car("Volvo", 4))
print(Car("BMW", 4))
print(Car("Tyrrell P34", 6))
print(Car("T-Rex", 3))


Checks if a class is deprecated or not

Description

Checks if a class is deprecated or not.

Usage

## S3 method for class 'Class':
isDeprecated(this, ...)

Arguments

... Not used.

Value

Returns TRUE if the class is deprecated, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

class(). setConstructorS3(). For more information see Class.


Checks if a word is a Rd keyword

Description

Checks if a word is a Rd keyword.

Usage

Rdoc$isKeyword(word, ...)

Arguments

... Not used.

Value

Returns a logical.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getKeywords() For more information see Rdoc.


Checks if the package is installed on the search path or not

Description

Checks if the package is installed on the search path or not.

Usage

## S3 method for class 'Package':
isLoaded(this, ...)

Arguments

... Not used.

Value

TRUE if the packages has been loaded, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*load(). search(). For more information see Package.

Examples

  pkg <- Package("base")
  print(isLoaded(pkg))       # TRUE


Checks if a class is defined private or not

Description

Checks if a class is defined private or not.

Usage

## S3 method for class 'Class':
isPrivate(this, ...)

Arguments

... Not used.

Value

Returns TRUE if the class is private, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

class(). setConstructorS3(). For more information see Class.

Examples

  if (isPrivate(RccViolationException))
    throw("The class RccViolationException should NOT be private.")


Checks if a class is defined protected or not

Description

Checks if a class is defined protected or not.

Usage

## S3 method for class 'Class':
isProtected(this, ...)

Arguments

... Not used.

Value

Returns TRUE if the class is protected, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

class(). setConstructorS3(). For more information see Class.

Examples

  if (isProtected(RccViolationException))
    throw("The class RccViolationException should NOT be protected.")


Checks if a class is defined public or not

Description

Checks if a class is defined public or not. A class is public if it is neither private nor protected.

Usage

## S3 method for class 'Class':
isPublic(this, ...)

Arguments

... Not used.

Value

Returns TRUE if the class is public, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

class(). setConstructorS3(). For more information see Class.

Examples

  if (!isPublic(RccViolationException))
    throw("The class RccViolationException should be public.")


Checks if the object is referable or not

Description

Checks if the object is referable or not.

Usage

## S3 method for class 'BasicObject':
isReferable(this, ...)

Arguments

... Not used.

Value

Returns a logical value, which by default is TRUE for all BasicObject's.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see BasicObject.


Checks if the object is referable or not

Description

Checks if the object is referable or not.

Usage

## S3 method for class 'Object':
isReferable(this, ...)

Arguments

... Not used.

Value

Returns a logical value, which by default is TRUE for all Object's.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.


Checks if a class is static or not

Description

Checks if a class is static or not. A class is static if it has static methods.

Usage

## S3 method for class 'Class':
isStatic(this, ...)

Arguments

... Not used.

Value

Returns TRUE if the class is static, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

setConstructorS3(). For more information see Class.

Examples

  if (!isStatic(RccViolationException))
    throw("RccViolationException should be static because Exception is.")


Checks if a member is visible given its modifiers

Description

Checks if a member is visible given its modifiers.

Usage

Rdoc$isVisible(modifiers, visibilities, ...)

Arguments

modifiers | A character string of modifiers.
visibilities | A character string of visibility flags.
... | Not used.

Value

Returns TRUE if the modifiers are equal or higher than the visibility flags, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


Generates a list of informative properties of all members of an environment

Description

Generates a list of informative properties of all members of an environment.

Usage

## Default S3 method:
ll(pattern=".*", ..., private=FALSE, properties=getOption("R.oo::ll/properties"), sortBy=NULL, envir=parent.frame())

Arguments

pattern | Regular expression pattern specifying which members to return. If ".*", all names are matched.
... | A named vector of format functionName=value, where functionName() will be called on each member found. If the result matches the value, the member is returned, otherwise not.
private | If TRUE, also private members, i.e. members with a name starting with a . (period), will be listed, otherwise not.
properties | Names of properties to be returned. There must exist a function with the same name, because it will be called. This way one can extract any type of property by defining new methods.
sortBy | Name or index of column (property) to be sorted by. If NULL, the objects are listed in the order they are found.
envir | An environment, a search path index or a name of a package to be scanned.

Value

Returns a data.frame containing information about all the members.

Default properties returned

It is possible to set the default value of argument properties by setting option "R.oo::ll/properties", e.g. options("R.oo::ll/properties"=c("data.class", "dimension")). If this option is not set when the package is loaded, it is set to c("data.class", "dimension", "objectSize").

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

ll.Object().

Examples

  ## Not run:
   To list all objects in .GlobalEnv:
   > ll()
                     member data.class dimension objectSize
   1                *tmp*     Person         1         428
   2  as.character.Person   function      NULL        1208
   3              country  character         1          44
   4        equals.Person   function      NULL        2324
   5             filename  character         1          84
   6               getAge   function      NULL         372
   7        getAge.Person   function      NULL         612
   8       getName.Person   function      NULL         628
   9      hashCode.Person   function      NULL        1196
   10        last.warning       list         1         192
   11                 obj     Person         1         428
   12              Person      Class      NULL        2292
   13              setAge   function      NULL         372
   14       setAge.Person   function      NULL        2088
   15             setName   function      NULL         372
   16      setName.Person   function      NULL         760
   17   staticCode.Person   function      NULL        2372

   To list all functions in the methods package:
   ll(mode="function", envir="methods")

   To list all numeric and character object in the base package:
   ll(mode=c("numeric", "character"), envir="base")

   To list all objects in the base package greater than 40kb:
   subset(ll(envir="base"), objectSize > 40000)
  ## End(Not run)


Generates a list of informative properties of all members of an Object

Description

Generates a list of informative properties of all members of an Object.

Usage

## S3 method for class 'Object':
ll(this, ...)

Arguments

... Any arguments accepted by the underlying function ll().

Value

Returns a data.frame containing information about all the members.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

ll.default(). For more information see Object.

Examples

  obj <- Object()
  obj$x <- 1:100
  obj$y <- 100:1
  ll(obj)

  ## Not run:
  gives:

    member data.class dimension objectSize
  1      x    numeric       100        424
  2      y    numeric       100        424
  ## End(Not run)


Generates a list of informative properties of all members of the package

Description

Generates a list of informative properties of all members of the package.

If the package is not loaded, it will be loaded, the members will be retrieved and then the package will be unloaded again.

Usage

## S3 method for class 'Package':
ll(this, envir=pos.to.env(getPosition(this)), ...)

Arguments

... Not used.

Details

Note the difference from the default definition of ll() as inherited from the Object class. Here ll() has been redefined to list the members of the package, i.e. the members in the environment on search path that belongs to the package, whereas the original usage was to list the members of the Object. However, since the internal members of Package object is not of interest we decided on this definition instead.

Value

Returns a data.frame.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.

Examples

  ## Not run: ll(R.oo)


Static method to load an Object from a file or a connection

Description

Static method to load an Object from a file or a connection, which previously have been saved using save() of class Object.

Usage

Object$load(file, path=NULL, ...)

Arguments

file | Filename or connection from where to read the Object.
path | The path where the file exists.
... | Not used.

Details

Please note that no constructors are called when an Object is loaded and neither is any static class code called.

Value

Returns a reference to the loaded Object.

Type control

Typically this static method is called as <Object>$load(...) where <Object> is any Object class. When an Object has been loaded, it is verified that it inherits from <Object>. If it does not, an exception is thrown. Thus, Object$load(...) will load any Object, but MyClass$load(...) will only load an Object that inherits from MyClass. If loaded object is not of correct class, an exception is thrown.

Troubleshooting

Due to a bug, likely in R itself, one can not specify the file argument by its name, i.e. Object$load(file="foo.RData") will not work, but Object$load("foo.RData") work just fine.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*save() and save(), load(). For more information see Object.

Examples

## Not run: For a complete example see help(Object).


Loads a package

Description

Loads a package. This is an alternative way to use library() to load a package.

Usage

## S3 method for class 'Package':
load(this, ...)

Arguments

... Not used.

Value

TRUE if the packages is loaded, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*unload().
*isLoaded().
search().
For more information see Package.

Examples

  pkg <- Package("base")
  print(load(pkg))


Gets all methods inherited from a class in Rd format

Description

Gets all methods inherited from a class in Rd format.

Usage

Rdoc$methodsInheritedFrom(class, visibility=c("public", "protected", "private"), showDeprecated=FALSE, inheritedFrom=NULL, sort=TRUE, trial=FALSE, ...)

Arguments

... Not used.

Value

Returns a character string.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Rdoc.


Creates a new instance of this class

Description

Creates a new instance of this class. Important: It should always be possible to create a new Object by calling the constructor without arguments. This method is simply calling the constructor method of the class.

Usage

## S3 method for class 'Class':
newInstance(this, ...)

Arguments

... Not used.

Value

Returns a reference to an Object.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Class.

Examples

  obj <- newInstance(Object)

  # equivalent to

  obj <- Object()


Creates a new instance of the same class as this object

Description

Creates a new instance of the same class as this object.

Usage

## S3 method for class 'Object':
newInstance(this, ...)

Arguments

... Not used.

Value

Returns a reference to an instance of Object or a subclass thereof.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

newInstance.Class(). For more information see Object.


Non-documented objects

Description

This page contains aliases for all "non-documented" objects that R CMD check detects in this package.

Almost all of them are generic functions that have specific document for the corresponding method coupled to a specific class. Other functions are re-defined by setMethodS3() to default methods. Neither of these two classes are non-documented in reality. The rest are deprecated methods.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Returns a reference to the same Object with virtual fields turned off

Description

Returns a reference to the same Object with virtual fields turned off.

Usage

## S3 method for class 'Object':
novirtual(this, ...)

Arguments

... Not used.

Value

Returns an Object.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.


The root class that every class must inherit from

Description

R.oo
Class Object

public class Object

Object is the root class of all other classes. All classes must extends this class, directly or indirectly, which means that they all will inherit the methods in this class.

Usage

Object(core=NA)

Arguments

core The core value of each reference referering to the Object. By default, this is just the smallest possible R object, but there are situations where it is useful to have another kind of core, which is the case with the Class class. Note that this value belongs to the reference variable and not to the Object, which means it can not be referenced.

Fields and Methods

Methods:
$ | -
$<- | -
[[ | -
[[<- | -
as.character | Gets a character string representing the object.
attach | Attaches an Object to the R search path.
attachLocally | Attaches an Object locally to an environment.
clearCache | Clear fields that are defined to have cached values.
clone | Clones an Object.
detach | Detach an Object from the R search path.
equals | Compares an object with another.
extend | Extends another class.
finalize | Finalizer methods called when object is clean out.
gc | Clear cached fields and calls the garbage collector.
getEnvironment | Gets the environment of this object.
getFields | Returns the field names of an Object.
getInstantiationTime | Gets the time when the object was instantiated.
getInternalAddress | Gets the memory location where the Object resides.
getStaticInstance | Gets the static instance of this objects class.
hasField | Checks if a field exists or not.
hashCode | Gets a hash code for the Object.
isReferable | Checks if the object is referable or not.
ll | Generates a list of informative properties of all members of an Object.
load | Static method to load an Object from a file or a connection.
names | -
newInstance | Creates a new instance of the same class as this object.
novirtual | Returns a reference to the same Object with virtual fields turned off.
objectSize | Gets the size of the Object in bytes.
print | Prints an Object.
registerFinalizer | Registers a finalizer hook for the object.
save | Saves an Object to a file or a connection.
staticCode | Method that will be call each time a new instance of a class is created.

Defining static fields

To define a static field of an Object class, use a private field <.field> and then create a virtual field <field> by defining methods get<Field>() and set<Field>(). These methods should retrieve and assign the value of the field <.field> of the static instance of the class. The second example below shows how to do this. The example modifies also the static field already in the constructor, which is something that otherwise may be tricky.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

References

[1] H. Bengtsson, The R.oo package - Object-Oriented Programming with References Using Standard R Code, In Kurt Hornik, Friedrich Leisch and Achim Zeileis, editors, Proceedings of the 3rd International Workshop on Distributed Statistical Computing (DSC 2003), March 20-22, Vienna, Austria. http://www.ci.tuwien.ac.at/Conferences/DSC-2003/Proceedings/

Examples

#########################################################################
# Defines the class Person with private fields .name and .age, and
# with methods print(), getName(), setName(), getAge() and setAge().
#########################################################################
setConstructorS3("Person", function(name, age) {
  if (missing(name)) name <- NA;
  if (missing(age))  age <- NA;

  extend(Object(), "Person",
    .name=name,
    .age=age
  )
})

setMethodS3("as.character", "Person", function(this, ...) {
  paste(this$.name, "is", as.integer(this$.age), "years old.");
})

setMethodS3("equals", "Person", function(this, obj, ...) {
  ( identical(data.class(this), data.class(obj)) &&
    identical(this$getName(), obj$getName()) &&
    identical(this$getAge() , obj$getAge() )    );
})

setMethodS3("hashCode", "Person", function(this, ...) {
  # Get the hashCode() of the '.name' and the '.age' fields
  # using hashCode.default().
  hashCode(this$.name) * hashCode(this$.age);
})

setMethodS3("getName", "Person", function(this, ...) {
  this$.name;
})

setMethodS3("setName", "Person", function(this, newName, ...) {
  throw("It is not possible to change the name of a Person.");
})

setMethodS3("getAge", "Person", function(this, ...) {
  this$.age;
})

setMethodS3("setAge", "Person", function(this, newAge, ...) {
  if (!is.numeric(newAge))
    throw("Age must be numeric: ", newAge);
  if (newAge < 0)
    throw("Trying to set a negative age: ", newAge);
  this$.age <- newAge;
})

#########################################################################
# Code demonstrating different properties of the Object class using
# the example class Person.
#########################################################################

# Create an object (instance of) the class Person.
p1 <- Person("Dalai Lama", 67)

# 'p1' is an Object of class Person.
print(data.class(p1))  # "Person"

# Prints information about the Person object.
print(p1)            # "Dalai Lama is 67 years old."

# or equivalent (except that no generic method has to exist):

p1$print()           # "Dalai Lama is 67 years old."

# Shows that no generic method is required if the \$ operator is used:
print(p1$getName())  # "Dalai Lama"

# The following will call p1$getName() since there exists a get-()
# method for the 'name' property.
print(p1$name)       # "Dalai Lama"

# and equivalent when using the [[ operator.
print(p1[["name"]])  # "Dalai Lama"

# The following shows that p1$setName(68) is called, simply because
# there exists a set-() method for the 'name' property.
p1$age <- 68         # Will call p1$setAge(68)

# Shows that the age of the Person has been updated:
print(p1)            # "Dalai Lama is 68 years old."

# If there would not exists such a set-() method or field a new
# field would be created:
p1$country <- "Tibet"

# Lists all (non-private) members of the Person object:
print(ll(p1))

# which gives
#      member class      mode    typeof length  dim bytes
#   1 country  NULL character character      1 NULL    44

# The following will call p1$setName("Lalai Dama") which will
# throw an exception saying one can not change the name of
# a Person.
tryCatch(p1$name <- "Lalai Dama", error=print)

# The following will call p1$setAge(-4) which will throw an
# exception saying that the age must be a non-negative number.
tryCatch(p1$age <- -100, error=print)

# Attaches Object 'p1' to the search path.
attach(p1)

# Accesses the newly created field 'country'.
print(country)       # "Tibet"

# Detaches Object 'p1' from the search path. Note that all
# modifications to 'country' are lost.
country <- "Sweden"
detach(p1)
print(p1$country)    # "Tibet"

# Saves the Person object to a tempory file.
filename <- tempfile("R.methodsS3.example")
save(p1, filename)

# Deletes the object
rm(p1)

# Loads an Object (of "unknown" class) from file using the
# static method load() of class Object.
obj <- Object$load(filename)

# Prints information about the new Object.
print(obj)

# Lists all (non-private) members of the new Object.
print(ll(obj))

######################################################################
# Example illustrating how to "emulate" static fields using virtual
# fields, i.e. get- and set-methods.  Here we use a private static
# field '.count' of the static class instance 'MyClass', i.e.
# MyClass$.count.  Then we define a virtual field 'count' via method
# getCount() to access this static field.  This will make all queries
# for 'count' of any object to use the static field instead.  In the
# same way is assignment controlled via the setCount() method.  A
# side effect of this way of coding is that all MyClass instances will
# also have the private field '.count' (set to zero except for the
# static field that is).
######################################################################
setConstructorS3("MyClass", function(...) {
  # Create an instance (the static class instance included)
  this <- extend(Object(), "MyClass",
    .count = 0
  )

  # In order for a static field to be updated in the
  # constructor it has to be done after extend().
  this$count <- this$count + 1;

  # Return the object
  this;
})

setMethodS3("as.character", "MyClass", function(this, ...) {
  paste(class(this)[1], ": Number of instances: ", this$count, sep="");
})

# Get virtual field 'count', e.g. obj$count.
setMethodS3("getCount", "MyClass", function(this, ...) {
  MyClass$.count;
})

# Set virtual field 'count', e.g. obj$count <- value.
setMethodS3("setCount", "MyClass", function(this, value, ...) {
  MyClass$.count <- value;
})

# Create four instances of class 'MyClass'
obj <- lapply(1:4, MyClass)
print(obj)
print(MyClass$count)
print(obj[[1]]$count)

stopifnot(obj[[1]]$count == length(obj))
stopifnot(MyClass$count == length(obj))


Gets the size of the object in bytes

Description

Gets the size of the object in bytes. This method is just a wrapper for object.size.

Usage

## Default S3 method:
objectSize(...)

Arguments

... Arguments passed to object.size.

Value

Returns an integer.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

Internally object.size.


Gets the size of the BasicObject in bytes

Description

Gets the size of the BasicObject in bytes by summing the sizes of all its members. For this reason, the size of memory the BasicObject actually allocates might vary slighty.

Usage

## S3 method for class 'BasicObject':
objectSize(this, ...)

Arguments

... Not used.

Value

Returns an integer specifying the size of the object in number of bytes.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

object.size. For more information see BasicObject.


Gets the size of an environment in bytes

Description

Gets the size of an environment in bytes.

Usage

## S3 method for class 'environment':
objectSize(envir, ...)

Arguments

envir | An environment().
... | Arguments passed to ls().

Value

Returns an integer.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

Internally object.size.


Gets the size of the Object in bytes

Description

Gets the size of the Object in bytes by summing the sizes of all its members. For this reason, the size of memory the Object actually allocates might vary slighty.

Usage

## S3 method for class 'Object':
objectSize(this, ...)

Arguments

... Not used.

Value

Returns an integer specifying the size of the object in number of bytes.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

To clear fields that are declared cached, see *clearCache(). object.size. For more information see Object.

Examples

  obj <- Object()
  obj$x <- 1:100
  obj$y <- 100:1
  objectSize(obj)   # 856


The Package class provides methods for accessing package information

Description

Package: R.oo
Class Package

Object
~~|
~~+--Package

Directly known subclasses:

public class Package
extends Object

Creates a Package that can be thrown and caught. The Package class is the root class of all other Package classes.

Usage

Package(name=NULL)

Arguments

name Name of the package.

Fields and Methods

Methods:
as.character | Gets a string representation of this package.
getAuthor | Gets the Author of this package.
getBundle | Gets the Bundle that this package might belong to.
getBundlePackages | Gets the names of the other packages that is in the same bundle as this package.
getChangeLog | Gets the change log of this package.
getClasses | Gets all classes of a package.
getContents | Gets the contents of this package.
getContribUrl | Gets the URL(s) from where this package can be installed.
getDataPath | Gets the path to the data (data/) directory of this package.
getDate | Gets the date when package was build.
getDescription | Gets the description of the package.
getDescriptionFile | Gets the description file of this package.
getDevelUrl | Gets the URL(s) from where the developers version of this package can be installed.
getDocPath | Gets the path to the accompanying documentation (doc/) directory of this package.
getEnvironment | Gets the environment of a loaded package.
getExamplePath | Gets the path to the example (R-ex/) directory of this package.
getHistory | -
getHowToCite | Gets the howToCite of this package.
getLicense | Gets the License of this package.
getMaintainer | Gets the Maintainer of this package.
getName | Gets the name of this package.
getNews | -
getPath | Gets the library (system) path to this package.
getPosition | Gets the search path position of the package.
getTitle | Gets the Title of this package.
getUrl | Gets the URL of this package.
getVersion | Gets the version of this package.
isLoaded | Checks if the package is installed on the search path or not.
ll | Generates a list of informative properties of all members of the package.
load | Loads a package.
showChangeLog | Show the change log of this package.
showContents | Show the CONTENTS file of this package.
showDescriptionFile | Show the DESCRIPTION file of this package.
showHistory | -
showHowToCite | Show the HOWTOCITE file of this package.
showNews | -
unload | Unloads a package.
update | Updates the package is a newer version is available.

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clone, detach, equals, extend, finalize, gc, getEnvironment, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, objectSize, print, registerFinalizer, save

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

Examples

## Not run: # By defining .First.lib() as follows in zzz.R for a package, an
# instance of class Package with the same name as the package will
# be made available on the search path. More over, the code below
# will also inform the user that the package has been loaded:
#
#  > library(R.oo)
#  R.oo v0.52 (2003/04/13) was successfully loaded.
#
.First.lib <- function(libname, pkgname) {
  pkg <- Package(pkgname);
  assign(pkgname, pkg, pos=getPosition(pkg));
  cat(getName(pkg), " v", getVersion(pkg), " (", getDate(pkg), ")",
    " was successfully loaded.\n", sep="");
}

# The Package class works for any packages, loaded or not.

# Some information about the base package
pkg <- Package("base")
print(pkg)
# [1] "Package: base v1.6.2 (NA) is loaded (pos=5). The official webpage
#      is NA and the maintainer is R Core Team <R-core@r-project.org>. The
#      package is installed in c:/PROGRA~1/R/rw1062/library/base/."
print(list.files(Package("base")$dataPath))

# Some information about the R.oo package
print(R.oo)
# [1] "Package: R.oo v0.52 (2003/04/13) is loaded (pos=2). The official
#      webpage is http://www.braju.com/R/ and the maintainer is Henrik
#      Bengtsson <henrikb@braju.com>. The package is installed in
#      c:/PROGRA~1/R/rw1062/library/R.oo/."

# To check for updates and update a package, just do
update(R.oo)

## End(Not run)


Prints an BasicObject

Description

For all objects of class BasicObject, this method will print the value of as.character() of the object. Note that this function is not called if the argument is not an object of class BasicObject.

Usage

## S3 method for class 'BasicObject':
print(x, ...)

Arguments

... Not used.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

print.default() For more information see BasicObject.


Prints detailed information about the class and its fields and methods

Description

Prints detailed information about the class and its fields and methods.

Usage

## S3 method for class 'Class':
print(x, ...)

Arguments

... Arguments passed to *getDetails().

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getDetails() For more information see Class.

Examples

  print(Object)


Prints the Exception

Description

. By default the as.character() representation plus the stack trace is printed.

Usage

## S3 method for class 'Exception':
print(x, ...)

Arguments

... Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*as.character().
*getStackTrace().
*printStackTrace().
For more information see Exception.

Examples

## Not run: For a complete example see help(Exception).


Prints an Interface

Description

For all objects of class Interface, this method will print the value of as.character() of the object.

Usage

## S3 method for class 'Interface':
print(x, ...)

Arguments

... Not used.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Interface.


Prints an Object

Description

For all objects of class Object, this method will print the value of as.character() of the object. Note that this function is not called if the argument is not an object of class Object.

Usage

## S3 method for class 'Object':
print(x, ...)

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

print.default() For more information see Object.

Examples

## Not run: For a complete example see help(Object).


Prints the stack trace saved when the exception was created

Description

.

Usage

## S3 method for class 'Exception':
printStackTrace(this, ...)

Arguments

... Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getStackTrace(). tryCatch(). For more information see Exception.

Examples

## Not run: For a complete example see help(Exception).


Package R.oo

Description

Methods and classes for object-oriented programming in R with or without references. Large effort has been made on making definition of methods as simple as possible with a minimum of maintenance for package developers. The package has been developed since 2001 and is now considered very stable. This is a cross-platform package implemented in pure R that defines standard S3 classes without any tricks.

Please note that the Rdoc syntax/grammar used to convert Rdoc comments in code into Rd files is not strictly defined and is modified by the need of the author. Ideally, there will be a well defined Rdoc language one day.

Installation and updates

To install this package do

install.packages("R.oo")

To get the "devel" version, see http://www.braju.com/R/.

Dependancies and other requirements

This package requires a standard R installation and the R.methodsS3 package.

To get started

To get started, see:

  1. Object - Root class providing support for reference variables. Any class inheriting from this class supports reference variables.

Further readings

For a detailed introduction to the package see [1]. To define static fields, see help on Object.

How to cite this package

Whenever using this package, please cite [1] as

@INPROCEEDINGS{BengtssonH_2003,
 author       = {Henrik Bengtsson},
 title        = {The {R.oo} package - Object-Oriented Programming
                 with References Using Standard {R} Code},
 booktitle    = {Proceedings of the 3rd International Workshop on
                 Distributed Statistical Computing (DSC 2003)},
 year         = {2003},
 editor       = {Kurt Hornik and Friedrich Leisch and Achim Zeileis},
 address      = {Vienna, Austria},
 month        = {March},
 issn         = {1609-395X},
 howpublished = {http://www.ci.tuwien.ac.at/Conferences/DSC-2003/},
}

License

The releases of this package is licensed under LGPL version 2.1 or newer.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

References

[1] H. Bengtsson, The R.oo package - Object-Oriented Programming with References Using Standard R Code, In Kurt Hornik, Friedrich Leisch and Achim Zeileis, editors, Proceedings of the 3rd International Workshop on Distributed Statistical Computing (DSC 2003), March 20-22, Vienna, Austria. http://www.ci.tuwien.ac.at/Conferences/DSC-2003/Proceedings/


An RccViolationException indicates a violation of the R Coding Conventions (RCC)

Description

Package: R.oo
Class RccViolationException

Object
~~|
~~+--try-error
~~~~~~~|
~~~~~~~+--condition
~~~~~~~~~~~~|
~~~~~~~~~~~~+--error
~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~+--simpleError
~~~~~~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~~~~~~+--Exception
~~~~~~~~~~~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~~~~~~~~~~~+--RccViolationException

Directly known subclasses:

public static class RccViolationException
extends Exception

An RccViolationException indicates a violation of the R Coding Conventions (RCC). It is generated by setConstructorS3() and setMethodS3(). It is not meant to be caught, but instead the source code that violates the RCC should be fixed. For more information about RCC, see references below.

Usage

RccViolationException(...)

Arguments

... Any arguments accepted by the constructor of Exception, i.e. one or several character strings, which will be concatenated and contain informative message about why the RCC was violated.

Details

Since it is not possible to assert that the RCC is followed during the parsing of the source code, but first only when the source code is actually executed.

Fields and Methods

Methods:
as.character | Gets a string representing of the RCC violation.
getRccUrl | Static method to get a URL where the RCC can be found.

Methods inherited from Exception:
as.character, getCall, getLastException, getMessage, getStackTrace, getWhen, print, printStackTrace, throw

Methods inherited from error:
as.character, throw

Methods inherited from condition:
as.character, conditionCall, conditionMessage, print

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clone, detach, equals, extend, finalize, gc, getEnvironment, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, objectSize, print, registerFinalizer, save

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

See also try() and tryCatch(). For detailed information about exceptions see Exception. The R Coding Conventions (RCC) can be found at http://www.maths.lth.se/help/R/RCC/.

Examples

  ## Not run:
   setConstructorS3("myClass", function() { extends(Object(), .value=0) })
   setMethodS3("MyMethod", "myClass", function(this) { "Hullo!" })

## End(Not run)


Class for converting Rdoc comments to Rd files

Description

Package: R.oo
Class Rdoc

Object
~~|
~~+--Rdoc

Directly known subclasses:

public static class Rdoc
extends Object

Class for converting Rdoc comments to Rd files.

Usage

Rdoc()

Fields and Methods

Methods:
argsToString | Gets the arguments signature of a function.
check | Checks the compiled Rd files.
compile | Compile source code files containing Rdoc comments into Rd files.
createManPath | Creates the directory where the Rd files should be saved.
createName | Creates a class-method name.
declaration | Gets the class declaration.
escapeRdFilename | Escape non-valid characters in a filename.
getClassS4Usage | Gets the usage of a S4 class.
getKeywords | Gets the keywords defined in R with descriptions.
getManPath | Gets the path to the directory where the Rd files will be saved.
getNameFormat | Gets the current name format.
getPackageNameOf | Gets the package of a method or an object.
getRdTitle | Extracts the title string of a Rd file.
getUsage | Gets the usage of a method.
hierarchy | Gets the class hierarchy.
isKeyword | Checks if a word is a Rd keyword.
isVisible | Checks if a member is visible given its modifiers.
methodsInheritedFrom | Gets all methods inherited from a class in Rd format.
setManPath | Sets the path to the directory where the Rd files should be saved.
setNameFormat | Sets the current name format.

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clone, detach, equals, extend, finalize, gc, getEnvironment, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, objectSize, print, registerFinalizer, save

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

References

R developers, Guidelines for Rd files, http://developer.r-project.org/Rds.html, 2003

Examples

## Not run: # Set default author
author <- "Henrik Bengtsson, \url{http://www.braju.com/R/}"

# Show the file containing the Rdoc comments
rdocFile <- system.file("misc", "ASCII.R", package="R.oo")
file.show(rdocFile)

# Compile the Rdoc:s into Rd files (saved in the destPath directory)
destPath <- tempdir()
Rdoc$compile(rdocFile, destPath=destPath)

# List the generated Rd files
rdFiles <- list.files(destPath, full.names=TRUE)
print(rdFiles)

# Show one of the files
file.show(rdFiles[1])

# Clean up
file.remove(rdFiles)
## End(Not run)


RdocException are thrown by the Rdoc compiler

Description

Package: R.oo
Class RdocException

Object
~~|
~~+--try-error
~~~~~~~|
~~~~~~~+--condition
~~~~~~~~~~~~|
~~~~~~~~~~~~+--error
~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~+--simpleError
~~~~~~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~~~~~~+--Exception
~~~~~~~~~~~~~~~~~~~~~~~~~~~|
~~~~~~~~~~~~~~~~~~~~~~~~~~~+--RdocException

Directly known subclasses:

public static class RdocException
extends Exception

RdocException are thrown by the Rdoc compiler when it fails to generate a Rd file from an Rdoc comment.

Usage

RdocException(..., source=NULL)

Arguments

... | Any arguments accepted by Exception
source | Object specifying the source where the Rdoc error occured. This is commonly a filename character string.

.

Fields and Methods

Methods:
as.character | Gets a character string representing of the RdocException.
getSource | Gets the source of the exception.

Methods inherited from Exception:
as.character, getCall, getLastException, getMessage, getStackTrace, getWhen, print, printStackTrace, throw

Methods inherited from error:
as.character, throw

Methods inherited from condition:
as.character, conditionCall, conditionMessage, print

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clone, detach, equals, extend, finalize, gc, getEnvironment, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, objectSize, print, registerFinalizer, save

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For detailed information about exceptions see Exception.


Registers a finalizer hook for the object

Description

Registers a finalizer hook for the object. The finalizer hook calls *finalize() on the Object when it is garbage collected. This method is only intended to be called inside the constructor, if at all.

Usage

## S3 method for class 'Object':
registerFinalizer(this, ...)

Arguments

... Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

Internally, reg.finalizer() is used. For more information see Object.


Saves an Object to a file or a connection

Description

Saves an Object to a file or a connection.

Usage

## S3 method for class 'Object':
save(this, file=NULL, path=NULL, compress=TRUE, ..., safe=TRUE)

Arguments

file | Filename or connection to which the Object should be saved. If NULL, the Object will be save to a file named "{class name}.{memory location}.RData", e.g. "Object.26979608.RData".
path | The path where the file should be saved.
compress | If TRUE, the file is compressed to, otherwise not.
... | Other arguments accepted by save() in the base package.
safe | If TRUE and file is a file, then, in order to lower the risk for incomplete files, the object is first written to a temporary file, which is then renamed to the final name.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*load() and save(), load(). For more information see Object.

Examples

## Not run: For a complete example see help(Object).


Defines a class in S3/UseMethod style

Description

Defines a class in R.oo/S3 style. The class name is validated so it starts with a letter and it also gives a warning if its first letter is not captial. The reason for this is to enforce a naming convention that names classes with upper-case initial letters and methods with lower-case initial letters (this is also the case in for instance Java).

What this function currently does is simply creating a constructor function for the class.

Note: The constructor must be able to be called with no arguments, i.e. use default values for all arguments or make sure you use missing() or similar! For instance the following defintion is not correct: setConstructorS3("Foo", function(x) extend(Object(), "Foo", x=x)) whereas this one is setConstructorS3("Foo", function(x=NA) extend(Object(), "Foo", x=x))

Usage

## Default S3 method:
setConstructorS3(name, definition, private=FALSE, protected=FALSE, static=FALSE, abstract=FALSE, trial=FALSE, deprecated=FALSE, envir=parent.frame(), enforceRCC=TRUE, ...)

Arguments

name | The name of the class.
definition | The constructor defintion. Note: The constructor must be able to be called with no arguments, i.e. use default values for all arguments or make sure you use missing() or similar!
static | If TRUE this class is defined to be static, otherwise not. Currently this has no effect expect as an indicator.
abstract | If TRUE this class is defined to be abstract, otherwise not. Currently this has no effect expect as an indicator.
private | If TRUE this class is defined to be private.
protected | If TRUE this class is defined to be protected.
trial | If TRUE this class is defined to be a trial class, otherwise not. A trial class is a class that is introduced to be tried out and it might be modified, replaced or even removed in a future release. Some people prefer to call trial versions, beta version. Currently this has no effect expect as an indicator.
deprecated | If TRUE this class is defined to be deprecated, otherwise not. Currently this has no effect expect as an indicator.
envir | The environment for where the class (constructor function) should be stored.
enforceRCC | If TRUE, only class names following the R Coding Convention is accepted. If the RCC is violated an RccViolationException is thrown.
... | Not used.

Note: If a constructor is not declared to be private nor protected, it will be declared to be public.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

To define a method see setMethodS3. For information about the R Coding Conventions, see RccViolationException. For a thorough example of how to use this method see Object.

Examples

## Not run: For a complete example see help(Object).


Sets the path to the directory where the Rd files should be saved

Description

Sets the path to the directory where the Rd files should be saved. By default the path is ../man/ assuming that the current directory is ../R/, which is where source files commonly are placed.

Usage

Rdoc$setManPath(path="../man/", ...)

Arguments

... Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getManPath() For more information see Rdoc.


Sets the current name format

Description

Sets the current name format. Throws a RccViolationException if an unknown format is requested.

Usage

Rdoc$setNameFormat(nameFormat, ...)

Arguments

nameFormat | If "method.class", help files for methods belonging to classes are named <method>.<class>. If "class.method", help files for methods belonging to classes are named <class>.<method>. These are currently the only name formats supported.
... | Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getNameFormat() For more information see Rdoc.


Show the change log of this package

Description

Show the change log of this package. If the change log file does not exist, an exception is thrown.

Usage

## S3 method for class 'Package':
showChangeLog(this, filenames=c("NEWS", "HISTORY", "ChangeLog"), ...)

Arguments

filenames | A character vector of (non-case sensitive) filenames to be searched for.
... | Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*getChangeLog(). For more information see Package.


Show the CONTENTS file of this package

Description

Show the CONTENTS file of this package. If the CONTENTS file does not exist, an exception is thrown.

Usage

## S3 method for class 'Package':
showContents(this, ...)

Arguments

... Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Show the DESCRIPTION file of this package

Description

Show the DESCRIPTION file of this package. If the DESCRIPTION file does not exist, an exception is thrown.

Usage

## S3 method for class 'Package':
showDescriptionFile(this, ...)

Arguments

... Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Show the HOWTOCITE file of this package

Description

Show the HOWTOCITE file of this package. See also *getHowToCite(). If the HOWTOCITE file does not exist, an exception is thrown.

Usage

## S3 method for class 'Package':
showHowToCite(this, ...)

Arguments

... Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Package.


Method that will be call each time a new instance of a class is created

Description

Method that will be call each time a new instance of a class is created.

By extending this method it is possible to have static code that is called each time a new instance of a class is created.

Usage

## S3 method for class 'Object':
staticCode(static, ...)

Arguments

static | The static instance of this class.
... | Not used.

Details

The method extend() in the Object class will call this method just before returning and it will pass the static instance of the class as a reference. Note that method should never be called explicitly.

Any value returned by this method will be ignored.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Object.

Examples

## Not run: For a complete example see help(Object).


Throws an Exception

Description

Throws an exception similar to stop(), but with support for exception classes. The first argument (object) is by default pasted together with other arguments (...) and with seperator sep="". For instance, to throw an exception, write

throw("Value out of range: ", value, ".").

which is short for

throw(Exception("Value out of range: ", value, ".")).

Note that throw() can be defined for specific classes, which can then be caught (or not) using tryCatch().

Usage

## Default S3 method:
throw(...)

Arguments

... One or several strings that are concatenated and collapsed into on message string.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

See the Exception class for more detailed information.

Examples

  rbern <- function(n=1, prob=1/2) {
    if (prob < 0 || prob > 1)
      throw("Argument 'prob' is out of range: ", prob)
    rbinom(n=n, size=1, prob=prob)
  }

  rbern(10, 0.4)
  # [1] 0 1 0 0 0 1 0 0 1 0
  tryCatch(rbern(10, 10*0.4),
    error=function(ex) {}
  )


Throws (rethrows) an object of class 'error'

Description

Rethrows an 'error' object. The 'error' class was introduced in R v1.8.1 with the new error handling mechanisms.

Usage

## S3 method for class 'error':
throw(error, ...)

Arguments

error | An object or class 'error'.
... | Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

See the tryCatch() method etc. See the Exception class for more detailed information.


Throws an Exception that can be caught

Description

Throws an Exception that can be caught by tryCatch().

Usage

## S3 method for class 'Exception':
throw(this, ...)

Arguments

... Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Exception. See also tryCatch(). This method overrides (and is fully backward compatible with) the one defined in the R.methodsS3 package.

Examples

## Not run: For a complete example see help(Exception).


Converts to a string and removes leading and trailing whitespace

Description

Converts to a string and removes leading and trailing whitespace.

Usage

## Default S3 method:
trim(object, ...)

Arguments

object | A vector of R objects to be trimmed.
... | Not used.

Value

Returns a vector of character strings.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Gets the type of a class (S3 or S4)

Description

Gets the type of a class (S3 or S4).

Usage

## Default S3 method:
typeOfClass(object, ...)

Arguments

object | The object to be checks.
... | Not used.

Value

Returns a character string "S3", "S3-Object" or "S4", or NA if neither.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


Unloads a package

Description

Unloads a package. This is an alternative way to use detach() to unload a package. If the package is not loaded, it will quietly return.

Usage

## S3 method for class 'Package':
unload(this, ...)

Arguments

... Not used.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

*load().
*isLoaded().
search().
For more information see Package.

Examples

  pkg <- Package("boot")
  load(pkg)
  print(isLoaded(pkg))
  unload(pkg)
  print(isLoaded(pkg))


Updates the package is a newer version is available

Description

Updates the package is a newer version is available. If the package is part of a bundle, the whole bundle will be updated. This method is a convientent alternative to update.packages(), especially for non-CRAN packages.

Usage

## S3 method for class 'Package':
update(object, contribUrl=c(getContribUrl(this), getDevelUrl(this)), force=FALSE, reload=TRUE, verbose=TRUE, ...)

Arguments

contribUrl | The URL from where the package can be installed and updated. By default the URL according to the DESCRIPTION is assumed. If the URL is missing, CRAN is assumed.
force | If TRUE, the package will reinstalled even if it is up to date according to the version number.
verbose | If TRUE, more detailed information is returned.
... | Not used.

Value

Returns (invisibly) TRUE if the package was updated, otherwise FALSE.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

update.packages. For more information see Package.

Examples

## Not run: update(R.oo)


Specifies that an object uses this Interface

Description

Specifies that an object uses this Interface.

Usage

## S3 method for class 'Interface':
uses(this, ...)

Value

Returns a character vector of class names of Interface:s.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

For more information see Interface.