mvbutils.utils {mvbutils} | R Documentation |
Miscellaneous utilities.
as.cat( x) clip( x, n=1) cq( ...) deparse.names.parsably( x) empty.data.frame( ...) env.name.string( env) expanded.call( nlocal=sys.parent()) everyth( x, by=1, from=1) find.funs(pos=1, ..., exclude.mcache = TRUE, mode="function") find.lurking.envs(obj, delve=FALSE, trace=FALSE) generic.dll.loader( libname, pkgname) index( lvector) is.dir( dir) isF( x) isT( x) legal.filename( name) lsall( ...) masked( pos) masking( pos=1) mkdir( dirlist) most.recent( lvec) my.all.equal( x, y) named( x) nscat( fmt, ..., sep='\n', file='') nscatn( fmt, ..., sep='\n', file='') option.or.default( opt.name, default=NULL) pos( substrs, mainstrs, any.case = FALSE, names.for.output) put.in.session( ...) returnList( ...) safe.rbind( df1, df2) # Deprecated in 2013 scatn( fmt, ..., sep='\n', file='') to.regexpr( x) yes.no( prompt, default)
x, y, n, ..., by, env, from, exclude.mcache, nlocal, lvector, dir, name, pos, frame, mode, dirlist, lvec, opt.name, default, substrs, mainstrs, any.case, names.for.output, df1, df2, prompt, obj, delve, trace, fmt, sep, file, libname, pkgname |
see "Arguments by function" |
as.cat
makes a character vector print as if it was cat
ted rather than print
ed (one element per line, no extra quotes or backslashes, no [1] etc prefixes).
clip
removes the last n
elements of x
.
cq
is handy for typing cq( alpha, beta, gamma)
instead of cq( "alpha", "beta", "gamma")
. Certain strings DO still require quotes around them, e.g. cq( "NULL", "1-2")
).
deparse.names.parsably
is like deparse
except that name
objects get wrapped in a call to as.name
, so that they won't be evaluated accidentally.
empty.data.frame
creates a template data frame with 0 rows but with all columns of the appropriate type. Useful for rbind
ing to later.
env.name.string
returns a string naming an environment; its name
attribute if there is one, or the name of its path
attribute if applicable, concatenated with the first line of what would be shown if you print
ed the argument. Unlike environmentName
, this will always return a non-empty string.
expanded.call
returns the full argument list available to its caller, including defaults where arguments were not set explicitly. The arguments may not be those originally passed, if they were modified before the invocation of expanded.call
. Default arguments which depend on calculations after the invocation of expanded.call
will lead to an error.
everyth
extracts every by
-th element of x
, starting at position from
.
find.funs
finds "function" objects (or objects of other modes, via the "mode" arg) in one or more environments, optionally matching a pattern.
find.lurking.envs( myobj)
will search through myobj
and all its attributes, returning the size of each sub-object. The size of environments is returned as Inf. The search is completely recursive, except for environments and by default the inner workings of functions; attributes of the entire function are always recursed. Changing the delve
parameter to TRUE ensures full recursion of function arguments and function bodies, which will show e.g. the srcref
structure; try it to see why the default is FALSE. find.lurking.envs
can be very useful for working out e.g. why the result of a model-fitting function is taking up 1000000MB of disk space; sometimes this is due to unnecessary environments in well-concealed places.
generic.dll.loader
is to be called from the .onLoad
or .First.lib
of a package. It looks for its DLLs either directly in the "libs" directory, or in the appropriate sub-architecture directory below "libs".
index
returns the position(s) of TRUE elements. Unlike which
: attributes are lost; NA elements map to NAs; index(<<length 0 object>>)
is numeric(0)
; index( <<non-logical>>)
is NA.
is.dir
tests for directoriness.
isF
and isT
test a logical vector in the obvious way, with NA elements failing the test, to avoid teeeedious repetition of is( !is.na( my.complicated.expression) & my.complicated.expression) ...
.
legal.filename
coerces its character argument into a similar-looking string that is a legal filename on any (?) system.
lsall
is like ls
but coerces all.names=TRUE
.
masked
checks which objects in search()[pos]
are masked by identically-named objects higher in the search path. masking
checks for objects mask identically-named objects lower in the search path. Namespaces may make the results irrelevant.
mkdir
makes directories; unlike dir.create
, it can do several levels at once.
most.recent
returns the highest-so-far position of TRUE within a logical vector, or 0 if TRUE has not occurred yet; most.recent( c(F,T,F,T))
returns c(0,2,2,4).
my.all.equal
is like all.equal
, except that it returns FALSE in cases where all.equal
returns a non-logical-mode result.
named(x)
is just names(x) <- as.character( x); x
; useful for lapply
etc.
nscat
, nscatn
: see scatn
option.or.default
obsolete— use equivalent getOption()
instead.
pos
is probably to be eschewed in new code, in favour of gregexpr
with fixed=TRUE
, which is likely faster. (And I should rewrite it to use gregexpr
.) It's one of a few legacy functions in mvbutils
that pre-date improvements in base R. pos
will either search for several literal patterns in a single target, or vice versa– but not both. It returns a matrix showing the positions of the matching substrings, with as many columns as the maximum number of matches. 0 signifies "no match"; there is always at least one column even if there are no matches at all.
returnList
returns a list corresponding to old-style (pre-R 1.8) return
syntax. Briefly: a single argument is returned as itself. Multiple arguments are returned in a list. The names of that list are the argument names if provided; or, for any unnamed argument that is just a symbolic name, that symbolic name; or no name at all, for other unnamed arguments. You can duplicate pre-1.8 behaviour of return(...)
via return(returnList(...))
.
safe.rbind
( Deprecated in 2013 ) mimics rbind
, but works round an R bug (I reckon) where a column appears to be a numeric in one data.frame
but a factor in the other. But I now think you should just sort your column classes/types properly in advance, rather than mixing types and relying on somewhat arbitrary conversion rules.
scatn
is just cat( sprintf( fmt, ...), "", file=file, sep=sep)
. scatn
prints a newline afterwards, but not before; nscat
does the opposite; nscatn
does both. If you're just displaying a "title" before calling print
, use nscat
.
to.regexpr
converts literal strings to their equivalent regexps, e.g. by doubling backslashes. Useful if you want "fixed=TRUE" to apply only to a portion of your regexp.
yes.no
cat
s its "prompt" argument and waits for user input. if the user input pmatch
es "yes" or "YES", then yes.no
returns TRUE
; if the input pmatch
es no
or NO
then yes.no
returns FALSE
; if the input is ” and default
is set, then yes.no
returns default
; otherwise it repeats the question. You probably want to put a space at the end of prompt
.
as.cat |
character vector of class |
clip |
vector of the same mode as |
cq |
character vector |
empty.data.frame |
|
env.name.string |
a string |
expanded.call |
a |
everyth |
same type as |
find.funs |
a character vector of function names |
find.lurking.envs |
a |
generic.dll.loader |
a useless list |
is.dir |
logical vector |
is.nonzero |
TRUE or FALSE |
isF, isT |
vector of TRUE or FALSE |
legal.filename |
character( 1) |
masked |
character vector |
masking |
character vector |
mkdir |
logical vector of success/failure |
nscat |
NULL |
nscatn |
NULL |
most.recent |
integer vector the same length as |
named |
vector of the same mode as |
option.or.default |
option's value |
pos |
numeric matrix, one column per match found plus one; at least one column guaranteed |
returnList |
list or single object |
safe.rbind |
|
scatn |
NULL |
to.regexpr |
character |
yes.no |
TRUE or FALSE |
x: character vector that you want to be displayed via cat( x, sep="\n")
x: a vector or list
n: integer saying how many elements to clip from the end of x
...: quoted or unquoted character strings, to be substitute
d and then concatenated
x: any object for deparse
- name
objects treated specially
...: named length-1 vectors of appropriate mode, e.g. "first.col=”"
env: environment
nlocal: frame to retrieve arguments from. Normally, use the default; see mlocal
.
x: subsettable thing. by: step between values to extract. from: first position.
...: extra arguments for objects
. Usually just "pattern" for regexp searches.
exclude.mcache: if TRUE (default), don't look at mlazy
objects
mode: "function" to look for functions, "environment" to look for environments, etc
delve: whether to recurse into function arguments and function bodies
trace: just a debugging aid– leave as FALSE
libname, pkgname: as per .onLoad
lvector: vector of TRUE/FALSE/NA
dir: character vector of files to check existence and directoriness of.
x: logical vector (will be coerced to logical)
name: character string to be modified
pos: list of environments, or vector of char or numeric positions in search path.
...: as for ls
, except that all.names
will be coerced to TRUE
pos: position in search path
dirlist: character vector of directories to create
logical vector
x, y: anything
x: character vector which will become its own names
attribute
see scatn
opt.name: character(1)
default: value to be returned if there is no option
called "opt.name"
substrs: character vector of patterns (literal not regexpr)
mainstrs: character vector to search for substrs
in.
any.case: logical- ignore case?
names.for.output: character vector to label rows of output matrix; optional
...: a named set of objects, to be assign
ed into the mvb.session.info
search environment
...: named or un-named arguments, just as for return
before R 1.8.
df1, df2: data.frame
or list
fmt, ...: as per sprintf
; file, sep: as per cat
x: character vector
prompt: string to put before asking for input
default: value to return if user just presses <ENTER>
Mark Bravington
# as.cat ugly.bugly <- c( 'A rose by any other name', 'would annoy taxonomists') ugly.bugly #[1] "A rose by any other name" "would annoy taxonomists" as.cat( ugly.bugly) # calls print.cat--- no clutter #A rose by any other name #would annoy taxonomists clip( 1:5, 2) # 1:3 cq( alpha, beta) # c( "alpha", "beta") empty.data.frame( a=1, b="yes") # data.frame with 0 rows of columns "a" (numeric) and "b" (character) empty.data.frame( a=1, b=factor( c( "yes", "no")))$b # factor with levels c( "no", "yes") everyth( 1:10, 3, 5) # c( 5, 8) f <- function( a=9, b) expanded.call(); f( 3, 4) # list( a=3, b=4) find.funs( "package:base", patt="an") # "transform" etc. find.lurking.envs( cd) # what size #1 attr(obj, "source") 5368 #2 obj 49556 #3 environment(obj) <: namespace:mvbutils> Inf ## Not run: eapply( .GlobalEnv, find.lurking.envs) mypack:::.onLoad <- function( libname, pkgname) generic.dll.loader( libname, pkgname) #... or just copy the code into your .onLoad ## End(Not run) is.dir( getwd()) # TRUE isF( c( FALSE, TRUE, NA)) # T F F isT( c( FALSE, TRUE, NA)) # F T F legal.filename( "a:b\\c/d&f") # "a.b.c.d&f" most.recent( c( FALSE,TRUE,FALSE,TRUE)) # c( 0, 2, 2, 4) sapply( named( cq( alpha, beta)), nchar) # c( alpha=5, beta=4) pos( cq( quick, lazy), "the quick brown fox jumped over the lazy dog") # matrix( c( 5, 37), nrow=2) pos( "quick", c( "first quick", "second quick quick", "third")) # matrix( c( 7,8,0, 0,14,0), nrow=3) pos( "quick", "slow") # matrix( 0) f <- function() { a <- 9; return( returnList( a, a*a, a2=a+a)) } f() # list( a=9, 81, a2=18) scatn( 'Things %i', 1:3) nscat( 'Things %i', 1:3) nscatn( 'Things %i', 1:3) to.regexpr( "a{{") # "a\\{\\{" ## Not run: mkdir( "subdirectory.of.getwd") yes.no( "OK (Y/N)? ") masking( 1) masked( 5) ## End(Not run)