Classes and objects

In S7: An Object Oriented System Meant to Become a Successor to S3 and S4

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

This vignette dives into the details of S7 classes and objects, building on the basics discussed in vignette("S7"). It will cover validators, the finer details of properties, and finally how to write your own constructors.

library(S7)

Validation

S7 classes can have an optional validator that checks that the values of the properties are OK. A validator is a function that takes the object (called self) and returns NULL if its valid or returns a character vector listing the problems.

Basics

In the following example we create a Range class that enforces that @start and @end are single numbers, and that @start is less than @end:

Range <- new_class("Range",
  properties = list(
    start = class_double,
    end = class_double
  ),
  validator = function(self) {
    if (length(self@start) != 1) {
      "@start must be length 1"
    } else if (length(self@end) != 1) {
      "@end must be length 1"
    } else if (self@end < self@start) {
      sprintf(
        "@end (%i) must be greater than or equal to @start (%i)",
        self@end,
        self@start
      )
    }
  }
)

You can typically write a validator as a series of if-else statements, but note that the order of the statements is important. For example, in the code above, we can't check that self@end < self@start before we've checked that @start and @end are length 1.

As we'll discuss shortly, you can also perform validation on a per-property basis, so generally class validators should be reserved for interactions between properties.

When is validation performed?

Objects are validated automatically when constructed and when any property is modified:

x <- Range(1, 2:3)
x <- Range(10, 1)

x <- Range(1, 10)
x@start <- 20

You can also manually validate() an object if you use a low-level R function to bypass the usual checks and balances of @:

x <- Range(1, 2)
attr(x, "start") <- 3
validate(x)

Avoiding validation

Imagine you wanted to write a function that would shift a property to the left or the right:

shift <- function(x, shift) {
  x@start <- x@start + shift
  x@end <- x@end + shift
  x
}
shift(Range(1, 10), 1)

There's a problem if shift is larger than @end - @start:

shift(Range(1, 10), 10)

While the end result of shift() will be valid, an intermediate state is not. The easiest way to resolve this problem is to set the properties all at once:

shift <- function(x, shift) {
  props(x) <- list(
    start = x@start + shift,
    end = x@end + shift
  )
  x
}
shift(Range(1, 10), 10)

The object is still validated, but it's only validated once, after all the properties have been modified.

Properties

So far we've focused on the simplest form of property specification where you use a named list to supply the desired type for each property. This is a convenient shorthand for a call to new_property(). For example, the property definition of range above is shorthand for:

Range <- new_class("Range",
  properties = list(
    start = new_property(class_double),
    end = new_property(class_double)
  )
)

Calling new_property() explicitly allows you to control aspects of the property other than its type. The following sections show you how to add a validator, provide a default value, compute the property value on demand, or provide a fully dynamic property.

Validation

You can optionally provide a validator for each property. For example, instead of validating the length of start and end in the validator of our Range class, we could implement those at the property level:

prop_number <- new_property(
  class = class_double,
  validator = function(value) {
    if (length(value) != 1L) "must be length 1"
  }
)

Range <- new_class("Range",
  properties = list(
    start = prop_number,
    end = prop_number
  ),
  validator = function(self) {
    if (self@end < self@start) {
      sprintf(
        "@end (%i) must be greater than or equal to @start (%i)",
        self@end,
        self@start
      )
    }
  }
)

Range(start = c(1.5, 3.5))
Range(end = c(1.5, 3.5))

Note that property validators shouldn't include the name of the property in validation messages as S7 will add it automatically. This makes it possible to use the same property definition for multiple properties of the same type, as above.

Default value

The defaults of new_class() create an class that can be constructed with no arguments:

Empty <- new_class("Empty",
  properties = list(
    x = class_double,
    y = class_character,
    z = class_logical
  ))
Empty()

The default values of the properties will be filled in with "empty" instances. You can instead provide your own defaults by using the default argument:

Empty <- new_class("Empty",
  properties = list(
    x = new_property(class_numeric, default = 0),
    y = new_property(class_character, default = ""),
    z = new_property(class_logical, default = NA)
  )
)
Empty()

A quoted call becomes a standard function promise in the default constructor, evaluated at the time the object is constructed.

Stopwatch <- new_class("Stopwatch", properties = list(
  start_time = new_property(
    class = class_POSIXct,
    default = quote(Sys.time())
  ),
  elapsed = new_property(
    getter = function(self) {
      difftime(Sys.time(), self@start_time, units = "secs")
    }
  )
))
args(Stopwatch)
round(Stopwatch()@elapsed)
round(Stopwatch(Sys.time() - 1)@elapsed)

Computed properties

It's sometimes useful to have a property that is computed on demand. For example, it'd be convenient to pretend that our range has a length, which is just the distance between @start and @end. You can dynamically compute the value of a property by defining a getter:

Range <- new_class("Range",
  properties = list(
    start = class_double,
    end = class_double,
    length = new_property(
      getter = function(self) self@end - self@start,
    )
  )
)

x <- Range(start = 1, end = 10)
x

Computed properties are read-only:

x@length <- 20

Dynamic properties

You can make a computed property fully dynamic so that it can be read and written by also supplying a setter.

A setter is a function with arguments self and value that returns a modified object.

For example, we could extend the previous example to allow the @length to be set, by modifying the @end of the vector:

Range <- new_class("Range",
  properties = list(
    start = class_double,
    end = class_double,
    length = new_property(
      class = class_double,
      getter = function(self) self@end - self@start,
      setter = function(self, value) {
        self@end <- self@start + value
        self
      }
    )
  )
)

x <- Range(start = 1, end = 10)
x

x@length <- 5
x

Common Patterns

getter, setter, default, and validator can be used to implement many common patterns of properties.

Deprecated properties

A setter + getter can be used to to deprecate a property:

Person <- new_class("Person", properties = list(
 first_name = class_character,
 firstName = new_property(
    class_character,
    default = quote(first_name),
    getter = function(self) {
      warning("@firstName is deprecated; please use @first_name instead", call. = FALSE)
      self@first_name
    },
    setter = function(self, value) {
      if (identical(value, self@first_name)) {
        return(self)
      }
      warning("@firstName is deprecated; please use @first_name instead", call. = FALSE)
      self@first_name <- value
      self
    }
  )
))

args(Person)

hadley <- Person(firstName = "Hadley")

hadley <- Person(first_name = "Hadley") # no warning

hadley@firstName

hadley@firstName <- "John"

hadley@first_name  # no warning

Required properties

You can make a property required by the constructor either by:

• relying on the validator to error with the default value, or by
• setting the property default to a quoted error call.

Person <- new_class("Person", properties = list(
 name = new_property(
   class_character,
   validator = function(value) {
     if (length(value) != 1 || is.na(value) || value == "")
       "must be a non-empty string"
   }
 )
))

try(Person())

try(Person(1)) # class_character$validator() is also checked.

Person("Alice")

Person <- new_class("Person", properties = list(
 name = new_property(
   class_character,
   default = quote(stop("@name is required")))
))

try(Person())

Person("Alice")

Frozen properties

You can mark a property as read-only after construction by providing a custom setter.

Person <- new_class("Person", properties = list(
 birth_date = new_property(
   class_Date,
   setter = function(self, value) {
     if(!is.null(self@birth_date)) {
       stop("@birth_date is read-only", call. = FALSE)
     }
     self@birth_date <- as.Date(value)
     self
   }
)))

person <- Person("1999-12-31")

try(person@birth_date <- "2000-01-01")

Constructors

You can see the source code for a class's constructor by accessing the constructor property:

Range@constructor

In most cases, S7's default constructor will be all you need. However, in some cases you might want something custom. For example, for our range class, maybe we'd like to construct it from a vector of numeric values, automatically computing the min and the max. To implement this we could do:

Range <- new_class("Range",
  properties = list(
    start = class_numeric,
    end = class_numeric
  ),
  constructor = function(x) {
    new_object(S7_object(), 
               start = min(x, na.rm = TRUE), 
               end = max(x, na.rm = TRUE))
  }
)

range(c(10, 5, 0, 2, 5, 7))

A constructor must always end with a call to new_object(). The first argument to new_object() should be an object of the parent class (if you haven't specified a parent argument to new_class(), then you should use S7_object() as the parent here). That argument should be followed by one named argument for each property.

There's one drawback of custom constructors that you should be aware of: any subclass will also require a custom constructor.

S7 documentation built on April 3, 2025, 10:50 p.m.