x <- array(1:20, c(4, 5))
y <- array(1:5 * 100, c(1, 5))
z <- array(20:1, c(4, 5))
print(x)
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] 1 5 9 13 17
#> [2,] 2 6 10 14 18
#> [3,] 3 7 11 15 19
#> [4,] 4 8 12 16 20
print(y)
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] 100 200 300 400 500
print(z)
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] 20 16 12 8 4
#> [2,] 19 15 11 7 3
#> [3,] 18 14 10 6 2
#> [4,] 17 13 9 5 1Operator Overloading
1 Introduction
Sometimes broadcasting is needed in a large mathematical expression, involving multiple variables, where precedence is of importance. For example in an expression like this:
x / (y + z) + a
Using the bc.* functions for that, while possible, may be inconvenient. It may be more convenient to use the base operators directly, whilst still keeping the broadcasting property.
To this end, the ‘broadcast’ package provides the broadcaster class, which comes with its own method dispatch for the base operators.
2 Example
Consider the matrices x, y and z:
Suppose we wish to compute x + y / z;
The following is wrong:
bc.d(x, y, "+") |> bc.d(y, "/")
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] 1.01 1.025 1.030000 1.0325 1.034
#> [2,] 1.02 1.030 1.033333 1.0350 1.036
#> [3,] 1.03 1.035 1.036667 1.0375 1.038
#> [4,] 1.04 1.040 1.040000 1.0400 1.040…because division must come before addition, according to standard math precedence rules.
We could do the following:
bc.d(y, z, "/") |> bc.d(x, "+")
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] 6.000000 17.50000 34.00000 63.00000 142.0000
#> [2,] 7.263158 19.33333 37.27273 71.14286 184.6667
#> [3,] 8.555556 21.28571 41.00000 81.66667 269.0000
#> [4,] 9.882353 23.38462 45.33333 96.00000 520.0000…but as the mathematical expression involves more and more variables with a greater variety of operators, it comes more and more taxing to keep track of the operator precedence.
Instead, one can designate all arrays as a “broadcaster”; all base operators that involve a broadcaster will use the overloaded variant provided by the ‘broadcast’ package - like so:
broadcaster(x) <- TRUE
broadcaster(y) <- TRUE
broadcaster(z) <- TRUE
x + y / z
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] 6.000000 17.50000 34.00000 63.00000 142.0000
#> [2,] 7.263158 19.33333 37.27273 71.14286 184.6667
#> [3,] 8.555556 21.28571 41.00000 81.66667 269.0000
#> [4,] 9.882353 23.38462 45.33333 96.00000 520.0000
#> broadcasterActually, not all arrays necessarily need to be a broadcaster.
Overloaded arithmetic operations that involve a broadcaster, will result in a broadcaster.
So technically, one could just make the array that is used first - according to the mathematical rules of precedence - as a broadcaster, and broadcasting will continue to be used.
In this case, the mathematically first preceding array is y.
To demonstrate, we’ll un-set x and z as broadcaster, and you’ll see broadcasting still occurs:
broadcaster(x) <- FALSE
broadcaster(z) <- FALSE
x + y / z
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] 6.000000 17.50000 34.00000 63.00000 142.0000
#> [2,] 7.263158 19.33333 37.27273 71.14286 184.6667
#> [3,] 8.555556 21.28571 41.00000 81.66667 269.0000
#> [4,] 9.882353 23.38462 45.33333 96.00000 520.0000
#> broadcaster
3 Overload method tables
The overloaded operators from the ‘broadcast’ package attempts to mimic the base operators accurately, except that broadcasting is used (obviously).
The following tables overview the behaviour of the operators.
3.1 Regular Arithmetic operators
If both sides of the operators given here are numeric or logical, the following holds:
| operator | action | function call |
|---|---|---|
| + | add | bc.d |
| - | substract | bc.d |
| * | multiply | bc.d |
| / | divide | bc.d |
| ^ | raise to power | bc.d |
| %/% | floored integer divide | bc.i |
| %% | modulo | bc.i |
3.2 Complex Arithmetic operators
If at least one of the arguments of the operators given here are complex, the following holds:
| operator | action | function call |
|---|---|---|
| + | add | bc.cplx |
| - | substract | bc.cplx |
| * | multiply | bc.cplx |
| / | divide | bc.cplx |
3.3 Logical Operators
If both sides of the operators given here are complex, numeric or logical, the following holds:
| operator | action | function call |
|---|---|---|
| & | and | bc.b |
| | | or | bc.b |
3.4 Bit-wise operators
If both sides of the operators given here are type of raw, the following holds:
| operator | action | function call |
|---|---|---|
| & | bit-wise and | bc.bit |
| | | bit-wise or | bc.bit |
3.5 Relational operators
For relational operators, ‘broadcast’ first finds the “highest” (or most complex) atomic type of both sides, coerces both sides to said type, and then performs the broadcasted relational operation. Recursive types are not supported.
The types, from complex to simple, are: character, complex, numeric (also known as double), integer, logical, and raw.
4 Derived operators
There is no overload for xor(), as xor() is defined using the existing base relational and logical (or bit-wise, for type of raw) operators.
There is also no overload for the %d==%, %d!=%, etc. operators, as they too are defined using the existing base relational and logical operators.
5 Base operators vs Overloaded operators
Although the operators overloaded by ‘broadcast’ attempt to mimic the base operators accurately, the are a few differences.
Most notably, the broadcasted operators do not preserve attributes.
Broadcasting often results in an object with more dimensions, larger dimensions, and/or larger length than the original objects.
Therefore, the names, dimnames, and dim attributes often no longer fit the new object.
Moreover, class attributes are related to dimensions or length.
For example, the matrix class presumes the object to have 2 dimensions, and the various classes from the ‘bit’ package use length-related attributes for their functionality.
So even class attributes cannot be guaranteed to hold for the resulting objects.
Only some class attributes, like the ‘broadcaster’ class (and related) attributes, will be preserved, if present.
6 Overloaded operators vs bc.* functions
Overloading the operators is primarily useful for encuring correct mathematical precedence, and to reduce the amount of typing.
However, the many bc.* functions provide much greater control than the simple operators can provide.
For example:
The & and | operators provide logical AND and OR, respectively for all atomic types except type raw; for type raw, the & and | operators provide BIT-WISE AND and OR, respectively.
But what if you want to use logical AND/OR for raw arrays, or bit-wise AND/OR for integer arrays?
When using the overloaded operators, using logical AND/OR for type raw necessitates converting the vector/array to type logical, thus making a copy.
With the bc.*() functions, this is not necessary.
Want to use logical AND/OR? Use bc.b(), it supports several types including raw.
Want to use bit-wise AND/OR? Use bc.bit(), it supports not only raw, but integer as well.
7 Compatibility with Custom Methods
Consider a classed vector like the following:
x <- 1:10
class(x) <- "someclass"
print(class(x))
#> [1] "someclass"Setting a vector or array as a “broadcaster” using the broadcaster()<- function, will add the “broadcaster” class attribute;
but note that the “broadcaster” class will be placed last in the class attribute:
broadcaster(x) <- TRUE
print(class(x))
#> [1] "someclass" "broadcaster"Notice how the “broadcaster” class comes after the “someclass” class.
Let’s make a quick ’n dirty (and not at all smart) + method for “somceclass”, which will just print some text:
`+.someclass` <- function(e1, e2) {print("someclass method called")}What will happen? Will the + method for the broadcaster be called, or the + method for “someclass”?
Well, since the “broadcaster” class is intentionally placed last, operator methods for the overriding classes will always “win” over the “broadcaster” class. In this case, if there are methods for the base operators (such as +, -, etc.) for the “someclass” class, the method for “someclass” will be called, rather than the broadcaster method:
y <- array(1:10, c(1, 10))
class(y) <- "someclass"
broadcaster(y) <- TRUE
x + y
#> [1] "someclass method called"
#> [1] "someclass method called"Notice how the + method for “someclass” is called, rather than the + method for the broadcaster.
This ensures compatibility with custom classes.
After all, some classes may not be intended to be broadcasted, or they may not be compatible with the base ‘R’ way of arithmetic (which is what ‘broadcast’ mimics), or they may need careful handling of attributes.
Authors of these custom classes can make their methods use broadcasting if a broadcaster vector/array is detected, if they so choose; only they know what is appropriate for their classes and what isn’t.