mvbutils-utils           package:mvbutils           R Documentation

_M_i_s_c_e_l_l_a_n_e_o_u_s _u_t_i_l_i_t_i_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Miscellaneous utilities.

_U_s_a_g_e:

     clip( x, n=1)
     cq( ...)
     deparse.names.parsably( x)
     empty.data.frame( ...)
     expanded.call( nlocal=sys.parent())
     find.funs(pos=1, ...)
     is.dir( dir)
     legal.filename( name)
     masked( pos)
     masking( pos=1)
     mkdir( dirlist)
     named( x)
     option.or.default( opt.name, default)
     pos( substrs, mainstrs, any.case = FALSE, names.for.output)
     print.cat( x, ...)
     print.nullprint( x, ...)
     returnList( ...)
     safe.rbind( df1, df2)
     to.regexpr( x)
     yes.no( prompt, default)

_A_r_g_u_m_e_n_t_s:

 x, n, ..., nlocal, dir, name, pos, dirlist, opt.name, default, substrs,: 

 mainstrs, any.case, names.for.output, df1, df2, prompt: see "Arguments
          by function"

_D_e_t_a_i_l_s:

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

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

     'is.dir' tests for directoriness.

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

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

     '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
     'print'ed 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' 'cat's the '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'.

_V_a_l_u_e:

    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

_A_r_g_u_m_e_n_t_s _b_y _f_u_n_c_t_i_o_n:

 _c_l_i_p x:a vector or list

 _c_l_i_p n:integer saying how many elements to clip from the end of 'x'

 _c_q ...:quoted or unquoted character strings, to be 'substitute'd and
     then concatenated

 _d_e_p_a_r_s_e._n_a_m_e_s._p_a_r_s_a_b_l_y x:any object for 'deparse'- 'name' objects
     treated specially

 _e_m_p_t_y._d_a_t_a._f_r_a_m_e ...:named length-1 vectors of appropriate mode, e.g.
     "first.col=''"

 _e_x_p_a_n_d_e_d._c_a_l_l nlocal:frame to retrieve arguments from. Normally, use
     the default; see 'mlocal'.

 _f_i_n_d._f_u_n_s ...:extra arguments for 'objects'. Usually just "pattern"
     for regexp searches.

 _i_s._d_i_r dir:character vector of files to check existence and
     directoriness of.

 _l_e_g_a_l._f_i_l_e_n_a_m_e name:character string to be modified

 _f_i_n_d._f_u_n_s pos:list of environments, or vector of char or numeric
     positions in search path.

 _m_a_s_k_i_n_g, _m_a_s_k_e_d pos:position in search path

 _m_k_d_i_r dirlist:character vector of directories to create

 _n_a_m_e_d x:character vector which will become its own 'names' attribute

 _o_p_t_i_o_n._o_r._d_e_f_a_u_l_t opt.name:character(1)

 _o_p_t_i_o_n._o_r._d_e_f_a_u_l_t default:value to be returned if there is no 'option'
     called '"opt.name"'

 _p_o_s substrs:character vector of patterns (literal not regexpr)

 _p_o_s mainstrs:character vector to search for 'substrs' in.

 _p_o_s any.case:logical- ignore case?

 _p_o_s names.for.output:character vector to label rows of output matrix;
     optional

 _p_r_i_n_t._c_a_t, _p_r_i_n_t._n_u_l_l_p_r_i_n_t x:thing to print

 _p_r_i_n_t._c_a_t, _p_r_i_n_t._n_u_l_l_p_r_i_n_t ...:args for 'print' (ignored)

 _r_e_t_u_r_n_L_i_s_t ...:named or un-named arguments, just as for 'return'
     before R 1.8.

 _s_a_f_e._r_b_i_n_d df1, df2:'data.frame' or 'list'

 _t_o._r_e_g_e_x_p_r x:character vector

 _y_e_s._n_o prompt:string to put before asking for input

 _y_e_s._n_o default:value to return if user just presses <ENTER>

_A_u_t_h_o_r(_s):

     Mark Bravington

_E_x_a_m_p_l_e_s:

     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)

