aaa01_broadcast_operators: Details on Broadcasted Operators

In broadcast: Broadcasted Array Operations Like 'NumPy'

Details on Broadcasted Operators

Description

Base 'R' comes with relational (==, !=, etc.), arithmetic (+, -, *, /, etc.), and logical/bit-wise (&, |) operators.
'broadcast' provides 2 ways to use these operators with broadcasting.

The first (and simple) way is to use the broadcaster class, which comes with it's own method dispatch for the above mentioned operators.
This approach supports operator precedence, and for the average 'R' user, this is sufficient.

The second way is to use the large set of bc.- functions.
These offer much greater control and more operators than the previous method, and has less risk of running into conflicting methods.
But it does not support operator precedence.

Operators Overloaded via Broadcaster Class

The 'broadcast' package provides the broadcaster class, which comes with its own method dispatch for the base operators.
If at least one of the 2 arguments of the base operators has the broadcaster class attribute, and no other class (like bit64) interferes, broadcasting will be used.

The following arithmetic operators have a 'broadcaster' method: +, -, *, /, ^, %%, %/%
The following relational operators have a 'broadcaster' method: ==, !=, <, >, <=, >=
And finally, the & and | operators also have a 'broadcaster' method.

As the broadcaster operator methods simply overload the base operators, operator precedence rules are preserved for the broadcaster operator methods.

See also the Examples section below.

Available bc. functions

'broadcast' provides a set of functions for broadcasted element-wise binary operations with broadcasting.
These functions use an API similar to the outer function.

The following functions for simple operations are available:

• bc.rel: General relational operations.

• bc.b: Boolean (i.e. logical) operations;

• bc.i: integer arithmetic operations;

• bc.d: decimal arithmetic operations;

• bc.cplx: complex arithmetic operations;

• bc.str: string (in)equality, concatenation, and distance operations;

• bc.raw: operations that take in arrays of type raw and return an array of type raw;

• bc.bit: BIT-WISE operations, supporting the raw and integer types;

• bc.list: apply any 'R' function to 2 recursive arrays with broadcasting.
  
  

Note that the bc.rel method is the primary method for relational operators (==, !=, <, >, <=, >=), and provides what most user usually need in relational operators.
The various other bc. methods have specialized relational operators available for very specialised needs.

Attribute Handling

The bc. functions and the overloaded operators generally do not preserve attributes, unlike the base 'R' operators, except for (dim)names and the broadcaster class attribute (and related attributes).

Broadcasting often results in an object with more dimensions, larger dimensions, and/or larger length than the original objects.
This is relevant as some class-specific attributes are only appropriate for certain dimensions or lengths.
Custom matrix classes, for example, presumes an object to have exactly 2 dimensions.
And the various classes provided by the 'bit' package have length-related attributes.
So class attributes cannot be guaranteed to hold for the resulting objects when broadcasting is involved.

The bc. functions and the overloaded operators always preserve the "broadcaster" attribute, as this is necessary to chain together broadcasted operations.

Almost all functions provided by 'broadcast' are S3 or S4 generics;
methods can be written for them for specific classes, so that class-specific attributes can be supported when needed.

Unary operations (i.e. + x, - x) return the original object, with only the sign adjusted.

Examples

# maths ====

x <- 1:10
broadcaster(x) <- TRUE

y <- 1:10
broadcaster(y) <- TRUE

x + y / x
x + 1 # mathematically equivalent to the above, since x == y
(x + y) / x
2 * x/x # mathematically equivalent to the above, since x == y

dim(x) <- c(10, 1)
dim(y) <- c(1, 10)

x + y / x
(x + y) / x

(x + y) * x


# relational operators ====
x <- 1:10
y <- array(1:10, c(1, 10))
broadcaster(x) <- TRUE
broadcaster(y) <- TRUE

x == y
x != y
x < y
x > y
x <= y
x >= y

broadcast documentation built on Sept. 15, 2025, 5:08 p.m.