mvbutils.operators: Utility operators

In mvbutils: General utilities, workspace organization, code and doc editing, live package maintenance, etc

Utility operators

Description

Succinct or convenience operators

Usage

a %&% b
x %**% y
a %!in% b
vector %except% condition    # does NOT strip attributes--- see *Value*
x %grepling% patt
x %has.name% name
x %is.not.a% what
x %is.a% what
x %is.not.an% what
x %is.an% what
name %in.names.of% x
x %matching% patt
a %not.in% b
a %not.in.range% b
x %perling% patt
x %that.end.with% suffix
x %that.start.with% prefix
x %that.match% patt
x %that.dont.match% patt
x %THAT.MATCH% patt
x %THAT.DONT.MATCH% patt
a %that.are.in% b       # does NOT strip attributes--- see *Value*
x %without.name% what   # does NOT strip attributes--- see *Value*
a %in.range% b
a %such.that% b         # does NOT strip attributes--- see *Value*
a %SUCH.THAT% b         # does NOT strip attributes--- see *Value*
from %upto% to
from %downto% to
x %where% cond          # also equiv mwhere(x,cond)
x %where.warn% cond
a %<-% value # really e.g. {x;y} %<-% list( 'yes', sqrt(pi)) to create x & y

Arguments

a, b, vector, condition, x, y, name, what, patt, from, to, cond, value, prefix, suffix

see Arguments by function.

Value

%&%	character vector. If either is zero-length, so is the result (unlike paste).
%**%	numeric, possibly a matrix
%upto%, %downto%	numeric
%is.a%, %in%, etc	logical
%<-%	technically NULL return, but it overwrites / creates objects; see below...
%has.name%, %in.names.of%	logical vector
All others	same type as first argument.
Note that attributes are _not_ stripped by the subsetting of %without.name%, %except%, %such.that%, %SUCH.THAT%, or %that.are.in% (as of v2.8.369)--- whereas base R does, which I view as a bug. However, attributes may still get stripped by the other %that... and %matching%, because (some of) those use unique. Possibly I should tweak those too, but I think they are inconsistently designed (e.g. %that.match% returns unique values, but %that.dont.match% uses subsetting) and I dont want to risk breaking more things...

Arguments by function

%&% a, b: character vectors to be pasted with no separator. If either is zero-length, so is the result (unlike paste).

%**% x, y: matrices or vectors to be multiplied using %*% but with less fuss about dimensions

%!in%, %that.are.in% a, b: vectors (character, numeric, complex, or logical).

%except% vector, condition: character or numeric vectors

%has.name%, %in.names.of% x, name: whether name (perhaps several) is in names(x). These differ only in the order of the parameters, but in some contexts one version seems more natural. Sugar for base::hasName.

%in.range%, %not.in.range% a, b: numeric vectors.

%is.a%, etc. x: object whose class is to be checked

%is.a%, etc. what: class name

%matching%, %that.match%, %that.dont.match%, %THAT.MATCH%, %THAT.DONT.MATCH%, %grepling%, %perling% x: character vector

%matching%, %that.match%, %that.dont.match%, %THAT.MATCH%, %THAT.DONT.MATCH%, %grepling%, %perling% patt: character vector of regexps, with perl syntax for %perling%. Use the upper-case versions for case-insensitive matching.

%that.start.with%, %that.end.with% : prefix & suffix: fixed (non-regex) strings that must match the start or end of x , as per startsWith and endsWith.

%such.that%, %SUCH.THAT% a: vector

%such.that%, %SUCH.THAT% b: expression containing a ., to subscript a with

%upto%, %downto% from, to: numeric(1)

%where%, %where.warn% x: data.frame

%where%, %where.warn% cond: unquoted expression to be evaled in context of x, then in the calling frame of %where% (or .GlobalEnv). Should evaluate to logical (or maybe numeric or character); NA is treated as FALSE. Wrap cond in parentheses to avoid trouble with operator precedence. NB %where% is equivalent to mwhere, which can be handily used in base-R pipes.

%without.name% x: object with names attribute

%without.name% what: character vector of names to drop

%<-% a, value: value should be a list, and a should be e.g. {x;y;z} with as many elements as value has. The elements of value are assigned, in order, to the objects named in a, which are created / overwritten in the calling environment.

Author(s)

Mark Bravington

See Also

bquote, mwhere

Examples

"a" %&% "b" # "ab"
matrix( 1:4, 2, 2) %**% matrix( 1:2, 2, 1) # c( 7, 10); '%*%' gives matrix result
matrix( 1:2, 2, 1) %**% matrix( 1:4, 2, 2) # c( 5, 11); '%*%' gives error
1:2 %**% matrix( 1:4, 2, 2) # '%*%' gives matrix result
1:5 %!in% 3:4 # c( TRUE, TRUE, FALSE, FALSE, TRUE)
1:5 %not.in% 3:4 # c( TRUE, TRUE, FALSE, FALSE, TRUE)
1:5 %that.are.in% 3:4 # c( 3, 4)
trf <- try( 1+"nonsense")
if( trf %is.not.a% "try-error") cat( "OK\n") else cat( "not OK\n")
1:5 %except% c(2,4,6) # c(1,3,5)
c( alpha=1, beta=2) %without.name% "alpha" # c( beta=2)
xx <- list( y=0, z='pterodactyl')
xx %has.name% 'y' # yep
xx %has.name% 'pringle' # nope
xx %has.name% cq( y, z) # yep and yep again
cq( y, z, zzz) %in.names.of% xx # same thing
1:5 %in.range% c( 2, 4) # c(F,T,T,T,F)
1:5 %not.in.range% c( 2, 4) # c(T,F,F,F,T)
c( "cat", "hat", "dog", "brick") %matching% c( "at", "ic") # cat hat brick
c( "cat", "hat", "dog", "brick") %that.match% c( "at", "ic") # cat hat brick; ...
# ... synonym for '%matching%'
c( "cat", "hat", "dog", "brick") %THAT.MATCH% c( "AT", "ic") # cat hat brick; case-insensitive
# ... synonym for '%matching%'
c( "cat", "hat", "dog", "brick") %that.dont.match% c( "at", "ic") # dog; ...
# ... like '%except%' but for regexps
c( "cat", "hat", "dog", "brick") %that.end.with% 'at' # cat hat
c( "cat", "hat", "dog", "brick") %that.start.with% 'br' # brick
1 %upto% 2 # 1:2
1 %upto% 0 # numeric( 0); use %upto% rather than : in for-loops to avoid unintended errors
1 %downto% 0 # 1:0
1 %downto% 2 # numeric( 0)
ff <- function( which.row) {
    x <- data.frame( a=1:3, b=4:6)
    x %where% (a==which.row)
  }
ff( 2) # data.frame( a=2, b=5)
x <- data.frame( start=1:3, end=c( 4, 5, 0))
x %where.warn% (start < end) # gives warning about row 3
(1:5) %such.that% (.>2) # 3,4,5
listio <- list( a=1,  b=2)
chars <- cq( a, b)
chars %SUCH.THAT% (listio[[.]]==2) # 'b'; %such.that% won't work because [[]] can't handle xtuples
{x;y} %<-% list( 'yes', sqrt(pi))
# x: [1] "yes"
# y: [1] 1.772

mvbutils documentation built on May 25, 2026, 5:09 p.m.