A toy package designed to showcase and serve as a reference/tutorial for S7 development. To be used in conjunction with the S7 package webs
Updated readme, need to add documentation
+51
-57
-1
NAMESPACE
-1
NAMESPACE
+4
-17
R/big_num.R
+4
-17
R/big_num.R
···
1
1
# TODO: pull out latter part of statement and rewrite as `is_node(x)`
2
2
node_or_na <- function(value) S7_inherits(value, node) || is.na(value) # predicate to check if `value` is a `node` or `NA`, pulled out to reduce duplication
3
+
# TODO: change to use unions if possible? `NA | node`?
3
4
4
5
node <- new_class("node",
5
6
package = "BigNum",
···
113
114
}
114
115
)
115
116
116
-
#' Infinite precision natural number using a singly linked list
117
-
#'
118
-
#' @description
119
-
#' TODO: WRITE THIS
120
-
#'
121
-
#' The `big_num` class is essentially a wrapper around [linked_list]
122
-
#' with a custom print method as well as some defined operators such as
123
-
#' `+`, `*`, and `^` with an integer.
124
-
#'
125
-
#' @export
126
-
#' @param num A string representation of a num.
127
117
big_num <- new_class("big_num",
128
118
parent = linked_list,
129
119
package = "BigNum",
···
131
121
new_object(linked_list(num))
132
122
}
133
123
)
134
-
135
-
# is.na <- new_external_generic("base", "is.na", "x")
136
-
# method(is.na, node) <- function(x) !S7_inherits(x, node)
137
124
138
125
is_even <- new_generic("is_even", c("x"))
139
126
method(is_even, big_num) <- function(x) x@head@VALUE %% 2 == 0
···
179
166
append_to_start(node(x), ll)
180
167
}
181
168
182
-
print <- new_external_generic("base", "print", "x")
183
-
method(print, linked_list) <- function(x) {
169
+
baseprint <- new_external_generic("base", "print", "x")
170
+
method(baseprint, linked_list) <- function(x) {
184
171
current <- x@head
185
172
while (S7_inherits(current)) {
186
173
cat(current@VALUE, "-> ")
···
190
177
191
178
invisible(x)
192
179
}
193
-
method(print, big_num) <- function(x) {
180
+
method(baseprint, big_num) <- function(x) {
194
181
len <- x@length
195
182
196
183
if (len == 0) {
-5
R/big_num_S3.R
-5
R/big_num_S3.R
···
51
51
structure(linked_list_s3(num), class = c("big_num_s3", "big_num_linked_list_s3"))
52
52
}
53
53
54
-
# is.na.node_s3 <- function(x) {
55
-
# \!inherits(x, "big_num_node_s3")
56
-
# }
57
-
58
54
#' @export
59
55
is_even_s3 <- function(x) {
60
56
UseMethod("is_even_s3")
···
69
65
UseMethod("bn_append_s3")
70
66
}
71
67
72
-
# TODO: fix this later
73
68
#' @export
74
69
bn_append_s3.big_num_node_s3 <- function(x, ll) {
75
70
if (!inherits(ll$state$head, "big_num_node_s3")) {
+3
R/zzz.R
+3
R/zzz.R
···
1
+
# As the website states, S7 uses this instead of `@export` to register methods.
2
+
# https://rconsortium.github.io/S7/reference/methods_register.html
1
3
.onLoad <- function(lib, pkg) {
2
4
S7::methods_register()
3
5
}
4
6
7
+
# The following is also taken from the website:
5
8
# enable usage of <S7_object>@name in package code
6
9
#' @rawNamespace if (getRversion() < "4.3.0") importFrom("S7", "@")
7
10
NULL
+43
-16
README.md
+43
-16
README.md
···
2
2
3
3
Written for `S7 0.2.0.`
4
4
5
+
```
6
+
pak::pkg_install("VisruthSK/BigNum")
7
+
```
8
+
9
+
## Why S7?
10
+
11
+
This package was created for a number of reasons. Chief among those is to provide a worked example of S7 in a package context, but it was also written to purvey the benefits of S7. So here I wish to address some reasons why S7 is best, and why you should seriously consider using S7 the next time you need a class for something. This is almost entirely subjective, and as an op-ed, the points I make are personal. There are certainly many contexts where S7 is not appropriate (one could argue that this package is best suited to R6), but there are also many places where you *could* use S7; I'm more focused on the latter.
12
+
13
+
S7 is formal. I first encountered S3 when speaking to Dr Bodwin; the topic came up somehow and she showed me how flexible S3 is with an example, something like:
14
+
15
+
```{r}
16
+
x <- 1:10
17
+
class(x) <- "test"
18
+
mean.test <- function(x){
19
+
"HELLO WORLD"
20
+
}
21
+
22
+
mean(x)
23
+
#> [1] "HELLO WORLD"
24
+
```
25
+
26
+
I was shocked at how easy it was to defined a class and write its method for a generic, especially since my knowledge of OOP was mostly in Java (which is very verbose.) The flexibility offers a lot of obvious benefits, but it does come with some drawbacks. Firstly, I think it can be a bit hard to understand; I still find S3 object construction a bit strange. For example, if I wanted to skip `x`'s declaration, I could've written instead:
27
+
28
+
```{r}
29
+
mean.test <- function(x){
30
+
"HELLO WORLD"
31
+
}
32
+
33
+
mean(structure(1:10, class = "test"))
34
+
```
35
+
36
+
but I think this is harder to reason about. The idea of just giving `1:10` a class without really defining what that class is, is strange to me. S7 makes it very clear what things are; I find this easier to reason about.
37
+
5
38
## Overview
6
39
7
40
***This project is a work in progress, needs reviews and revisions to check for consistency and such. Some best practices for S7 development (e.g. [documentation](https://github.com/RConsortium/S7/issues/315)) haven't been established yet though.***
···
14
47
15
48
["The S7 package is a new OOP system designed to be a successor to S3 and S4." - R Consortium Object-Oriented Programming Working Group.](https://rconsortium.github.io/S7/)
16
49
17
-
S7 is a new way to do OOP in R, and it is fantastic. That quote links to the official S7 website, which contains a great deal of information regarding S7--its origins, features, compatibility, specifications, etc. Any developer who wishes to use S7 should certainly study that website. It is quite cogent and detailed, and I use it as a reference all the time–its practically an extra chapter of Advanced R. This package is meant to be used in conjunction with the S7 website, hopefully serving as a (slightly non-contrived) total which can be used to understand how S7 can work in practice. Since S7 is so new, and is still technically experimental, major changes to the API aren't unusual. As such, for this project to be effective, it must be kept in time with S7 as the OOP system matures. Best practice, as and when they are developed, should be implemented to serve as an effective, worked out example for S7 package development.
50
+
S7 is a new way to do OOP in R, and I think it is fantastic. The quote above links to the official S7 website, which contains a great deal of information regarding S7--its origins, features, compatibility, specifications, etc. I think any developer who wishes to use S7 should certainly study that website. It is quite cogent and detailed, and I use it as a reference all the time–its practically an extra chapter of Advanced R. This package is meant to be used in conjunction with the S7 website, hopefully serving as a (slightly non-contrived) implementation which can be used to understand how S7 can work in practice.
51
+
52
+
Some goals of the project, viz. with regards to S7:
18
53
19
-
S7 is in use by a number of people already–some are writing about their experiences as well. One I happened upon is this [blog post](https://blog.djnavarro.net/posts/2024-02-25_s7/) by Dr. Navarro detailing how they used S7 to make some of her latest artwork. Like all of Dr Navarro's posts, it is well worth a read.
54
+
Since S7 is so new, and is still technically experimental, major changes to the API [aren't off the table](https://rconsortium.github.io/S7/index.html?q=experimental#s7). As such, for this project to be effective, it will be updated with S7 as the OOP system matures. The package's major version will follow S7, which is why this (will) release into 2.0.0. Best practices, as and when they are developed, will be implemented to serve as an effective, worked out example for S7 package development.
20
55
21
56
### BigNum
22
57
23
58
So what is BigNum? And why this project?
24
59
25
-
Firstly, it is important to note that this is a *toy* package. Whilst the package will build, and expose an API one can use to create `big_num` objects, I do not think one *should* use these as infinite precision numbers (for that purpose, look towards packages like [Rmpfr](https://cran.r-project.org/web/packages/Rmpfr/index.html).) This package's implementation is very rough and many properties one would expect from "numbers" are missing–negative numbers, subtraction, division, modulus, etc. are all not implemented. The point of this package is not to veritably implement infinite precision numbers, but rather to show how S7 can be used in a package to make some basic data structures and work with some generics/functions. The package itself is very simple and has a relatively concise and simple implementation. Since this package's purpose is pedagogical, there isn't much point in implementing all the aforementioned features.
60
+
Firstly, it is important to note that this is wholly a *toy* package. Whilst the package will build, and expose an API one can use to create `big_num` objects, I do not think one *should* use these as arbitrary precision numbers (look towards packages like [Rmpfr](https://cran.r-project.org/web/packages/Rmpfr/index.html).) This package's implementation is very rough and many properties one would expect from "numbers" are missing–negation, subtraction, division, modulus, etc. are all not implemented. The point of this package is not to veritably implement infinite precision numbers, but rather to show how S7 can be used in a package to make some basic data structures and work with some generics/functions. The package itself is very simple and has a relatively concise implementation. Since this package's purpose is pedagogical, there isn't much point in implementing the aforementioned features.
26
61
27
-
So why BigNum specifically? Well, mostly because it's easy to implement. The BigNum project is taken from my CSC 203 class, a course in OOP at Cal Poly. As such, I already had all the methods implemented and a clear idea of what I needed to do and how, with the main work being in porting logic to R as opposed to devising the methods and classes needed. This greatly simplified dev time since I had a reference implementation to use. **Importantly,** **this (along with my lack of experience) could lead to unidiomatic R/S7 code and design patterns.** **If you notice anything strange, please open an issue/PR!**
62
+
I wrote the S7 implementation first, and have since expanded to a S3 and S4 implementation (and might add a rough R6 one too?). These three versions (S3, S4, S7) have rough feature parity, but part of this project is to highlight the benefits of S7 so there are things you can't do (or at least, can't do as easily) in the other OOP structures.
63
+
64
+
So why BigNum specifically? Well, mostly because it's easy to implement. The BigNum project is taken from my CSC 203 class, a OOP course at Cal Poly. I already had all the methods implemented (in Java) and a clear idea of what I needed to do and how, with the main work being in porting design to R as opposed to novel thought. This greatly simplified dev time since I had a reference implementation to use. **Importantly,** **this (along with my lack of experience) could lead to unidiomatic R/S7 code and design patterns.** **If you notice anything strange, please open an issue/PR!**
28
65
29
-
I haven't developed an R package before, and so that provided additional motivation for me to create this project. That also means that this package is certainly written sub-optimally. Additionally, my experience with S7 is extremely limited–I would be extremely grateful for any and all R sourcerers who can rain issues and pull requests down from the heavens, fixing all my mistakes :)
66
+
I haven't developed an R package before, and so that provided additional motivation for me to create this project. That also means that this package is certainly written sub-optimally. Additionally, my experience with S7 is extremely limited–I would be extremely grateful for any and all R sourcerers who can rain issues and pull requests down from the heavens fixing all my mistakes :)
30
67
31
68
## References
32
69
33
70
Vaughan D, Hester J, Kalinowski T, Landau W, Lawrence M, Maechler M, Tierney L, Wickham H (2024). *S7: An Object Oriented System Meant to Become a Successor to S3 and S4*. R package version 0.2.0.9000, <https://github.com/RConsortium/S7>, <https://rconsortium.github.io/S7/>.
34
-
35
-
Navarro, Danielle. 2024. “Creating New Generative Art Tools in R with Grid, Ambient, and S7.” February 25, 2024. <https://blog.djnavarro.net/posts/2024-02-25_s7/>.
36
71
37
72
Henry L, Wickham H (2024). *rlang: Functions for Base Types and Core R and 'Tidyverse' Features*. R package version 1.1.4, <https://CRAN.R-project.org/package=rlang>.
38
73
···
44
79
45
80
## TODOs:
46
81
47
-
- Finish readme
48
-
49
-
- add more citations
50
-
51
82
- Write documentation
52
83
53
84
- Comment code
54
85
55
-
- Some basic comments for actual use of package
56
-
57
86
- Write tests
58
87
59
-
- Write a vignette?
60
-
61
-
- Website?
88
+
- Write a vignette?
-18
man/big_num.Rd
-18
man/big_num.Rd
···
1
-
% Generated by roxygen2: do not edit by hand
2
-
% Please edit documentation in R/big_num.R
3
-
\name{big_num}
4
-
\alias{big_num}
5
-
\title{Infinite precision natural number using a singly linked list}
6
-
\usage{
7
-
big_num(num = "")
8
-
}
9
-
\arguments{
10
-
\item{num}{A string representation of a num.}
11
-
}
12
-
\description{
13
-
TODO: WRITE THIS
14
-
15
-
The \code{big_num} class is essentially a wrapper around \link{linked_list}
16
-
with a custom print method as well as some defined operators such as
17
-
\code{+}, \code{*}, and \code{^} with an integer.
18
-
}