mvbutils-utils {mvbutils}R Documentation

Miscellaneous utilities

Description

Miscellaneous utilities.

Usage

clip( x, n=1)
cq( ...)
deparse.names.parsably( x)
empty.data.frame( ...)
exists.mvb( x, pos = -1, envir = pos.to.env(pos), frame, mode = "any", inherits = FALSE)
expanded.call( nlocal=sys.parent())
find.funs(pos=1, ...)
index( lvector)
is.dir( dir)
legal.filename( name)
lsall( ...)
lib.pos() # used only to hack this-is-escaped-codenormal-bracket31bracket-normal
masked( pos)
masking( pos=1)
mkdir( dirlist)
my.all.equal( x, y)
named( x)
option.or.default( opt.name, default=NULL)
pos( substrs, mainstrs, any.case = FALSE, names.for.output)
print.cat( x, ...)
print.nullprint( x, ...)
put.in.session( ...)
returnList( ...)
safe.rbind( df1, df2)
to.regexpr( x)
yes.no( prompt, default)

Arguments

x, y, n, ..., nlocal, lvector, dir, name, pos, envir, frame, mode, inherits, dirlist, opt.name, default, substrs,
mainstrs, any.case, names.for.output, df1, df2, prompt see "Arguments by function"

Details

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.

exists.mvb is pretty much like exists but has a pos rather than a where argument.

find.funs finds "function" objects in one or more environments, optionally matching a pattern.

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.

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.

legal.filename coerces its character argument into a similar-looking string that is a legal filename on any (?) system.

lib.pos is used by mvbutils in hacking library, to make sure packages get attached below ROOT task. You'll probably never need to call this directly.

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 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.

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.

option.or.default returns the named option value if it exists, otherwise the supplied default.

pos will either search for several literal patterns in a single target, or vice versa– 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. pos is very slow and should probably be rewritten.

print: if class(x)=="cat", the character vector x will be printed by cat(x,sep="\n"). If class(x)=="nullprint", then print(x) will not print anything.

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 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.

to.regexpr converts literal strings to their equivalent regexprs, e.g. by doubling backslashes.

yes.no cats the prompt argument and waits for user input. if the user input pmatches "yes" or "YES", then yes.no returns TRUE; if the input pmatches 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.

Value

clip vector of the same mode as x.
cq character vector.
empty.data.frame data.frame
expanded.call a call object
find.funs a character vector of function names
is.dir logical vector
is.nonzero TRUE or FALSE
legal.filename character( 1)
masked character vector.
masking character vector.
mkdir logical vector of success/failure
named vector of the same mode as x
option.or.default option value
pos numeric matrix, one column per match found plus one ; at least one column guaranteed
returnList list or single object
safe.rbind data.frame
to.regexpr character
yes.no TRUE or FALSE

Arguments by function

clip
x:a vector or list
clip
n:integer saying how many elements to clip from the end of x
cq
...:quoted or unquoted character strings, to be substituted and then concatenated
deparse.names.parsably
x:any object for deparsename objects treated specially
empty.data.frame
...:named length-1 vectors of appropriate mode, e.g. "first.col=''"
exists.mvb
x:string, pos = integer, envir = environment, frame = frame number, mode & inherits as for exists
expanded.call
nlocal:frame to retrieve arguments from. Normally, use the default; see mlocal.
find.funs
...:extra arguments for objects. Usually just "pattern" for regexp searches.
index
lvector:vector of TRUE/FALSE/NA
is.dir
dir:character vector of files to check existence and directoriness of.
legal.filename
name:character string to be modified
find.funs
pos:list of environments, or vector of char or numeric positions in search path.
lsall
...:as for ls, except that all.names will be coerced to TRUE
masking, masked
pos:position in search path
mkdir
dirlist:character vector of directories to create
my.all.equal
x, y:anything
named
x:character vector which will become its own names attribute
option.or.default
opt.name:character(1)
option.or.default
default:value to be returned if there is no option called "opt.name"
pos
substrs:character vector of patterns (literal not regexpr)
pos
mainstrs:character vector to search for substrs in.
pos
any.case:logical– ignore case?
pos
names.for.output:character vector to label rows of output matrix; optional
print.cat, print.nullprint
x:thing to print
print.cat, print.nullprint
...:args for print (ignored)
put.in.session
...:a named set of objects, to be assigned into the mvb.session.info search environment
returnList
...:named or un-named arguments, just as for return before R 1.8.
safe.rbind
df1, df2:data.frame or list
to.regexpr
x:character vector
yes.no
prompt:string to put before asking for input
yes.no
default:value to return if user just presses <ENTER>

Author(s)

Mark Bravington

Examples

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" (a factor with levels ""yes"")
f <- function( a=9, b) expanded.call(); f( 3, 4) # list( a=3, b=4)
find.funs( "package:base", patt="an") # "transform" etc.
is.dir( getwd()) # TRUE
legal.filename( "a:b\\c/d&f") # "a.b.c.d&f"
sapply( named( cq( alpha, beta)), nchar) # c( alpha=5, beta=4)
option.or.default( "my.option", 5) # probably 5
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)
levels( rbind( data.frame( x=1), data.frame( x="cat"))$x)
# NULL, because "x" acquires mode "character"; a bug, I think
levels( safe.rbind( data.frame( x=1), data.frame( x="cat"))$x)
# c( "1", "cat")
to.regexpr( "a[[") # "a\\[\\["
## Not run: 
mkdir( "subdirectory.of.getwd")
yes.no( "OK (Y/N)? ")
masking( 1)
masked( 5)
## End(Not run)

[Package mvbutils version 1.1.1 Index]