## Generated by ‘rhelium’ from Rd files: do not edit here
## Edit documentation in ‘local’ source files
#format wiki
#language en
#pragma section-numbers off
#acl IanRiley:read,write,delete,revert,admin All:read
#pragma keywords IanRiley R-project package rhelium roxygen2 devtools
#pragma supplementation-page on

= R Package ‘local’ =

Documentation for package ‘local’ version 2018.09.02. [[attachment:desc.txt|DESCRIPTION|target='_blank']]

<<TableOfContents(2)>>

------
== local-package ==

Collection of Local Functions

=== Description ===

A miscellaneous collection of utility and special purpose functions.

=== Details ===

Ideally this package should be installed at start up, which can be done by adding `options(defaultPackages = c(getOption("defaultPackages"), "local"))` to `.Rprofile`.

Also, this package expects that the path to the intial working directory (home folder) is set in `.Rprofile` using the likes of `options(home = "/Users/username/R")` (for MacOS, where 'username' is the users login name).

For a complete list, use `library(help = "local")`.

=== Version ===

2018.9.2

=== Author(s) ===

Ian Riley <<MailTo(i a n AT r i l e y DOT a s i a)>>

=== See Also ===

Useful links:

 * [[http://rileylink.net/moin.cgi/R_coding/local-package]]

------

== as.object ==

Assign Objects from Named Variables

=== Description ===

`as.object` can be used to assign (create) objects based on the names and values in named vectors or lists, or from column names and column values in data frames. If the source object is unnamed, names can be supplied as aruguments or as a character vector using the argument `to`. If names are supplied, they are used to replace (fully or partially) those in the source object.

=== Usage ===

{{{#!highlight r

as.object(x, ..., to = character(), replace = TRUE, return = TRUE,
  pos = 1, envir = as.environment(pos), inherits = FALSE)

}}}

=== Arguments ===

 x:: an object with with names, such as vector, list or data frame, or an object to which the `names` attribute can be applied.

 ...:: names to be applied to `x`, if unnamed, or to replace existing names.

 to:: a character vector of names to be applied to `x`, if unnamed, or to replace existing names.

 replace:: a logical value indicating whether existing objects should be replaced without warning.

 return:: a logical value indicating whether to return a character vector containing the names of the objects assigned.

 pos:: where to assign the objects. By default, uses the current environment. See `assign` for other possibilities.

 envir:: the environment to use. See `assign` for details.

 inherits:: should the enclosing frames of the environment be inspected?

=== Details ===

See `assign` for for futher details.

=== Value ===

This function is largely invoked for its side effect, that is, assigning values to objects created from the names and values from `x`. However, by default it returns a character vector of the names of objects assigned, as this might differ from the original name of the souce object if alternative names supplied by arguments `...` and `to`. The vector might be useful for subsequent operations on these object using `eval(as.name())`.

If alternative object names are given by arguments `...` and `to`, those given by `...` are used first. If there are more names provided than elements in the source object, the extras will be ignored and a warning given.

If there are blank names or insufficent names, the elements in the source object that correspond to the postion of these will not be assigned and a warning given.

If numerical values are provided via `...`, these will be converted to integers and prefixed by 'x' to created new object names.

If `replace` is FALSE and an attempt assignment would fail, then no assignments are made and an error message returned.

=== Examples ===

{{{#!highlight r

as.object(c(v1 = 1, v2 = 2)) # creates two objects, "v1" and "v2"
v1; v2
as.object(list(v1 = 1:2, v2 = 1:3, v3 = 1:4, 1:5)) # last item in list ignored with warning
v1; v2; v3
as.object(data.frame(v1 = 1:3, v2 = 4:6, v3 = 7:9)) 
v1; v2; v3
as.object(c(1,2), c("v1", "v2")) # provide names to unnamed structure
v1; v2
as.object(c(v1 = 1, v2 = 2), v3, v4) # replace names in named structure
v3; v4
as.object(c(1, 2), 5:6) # apply numbered names, "x5" and "x6" here
x5; x6

}}}

------

== checks ==

Are Some or No Values True?

=== Description ===

Given a set of logical vectors, check if some or all values false.

=== Usage ===

{{{#!highlight r

some(..., na.rm = FALSE)

none(..., na.rm = FALSE)

}}}

=== Arguments ===

 ...:: zero or more logical vectors. Other objects of zero length are ignored, and the rest are coerced to logical ignoring any class.

 na.rm:: logical: if true, NA values are removed before the result is computed.

=== Details ===

These functions are to compliment `all` and `any`. Refer to the respective help pages for those functons for more details.

=== Value ===

 `some` returns `TRUE` only if some but not all values are `TRUE`. If no values provided, `FALSE` is returned. If the values provided include one or more `NA` values, `TRUE` is still only returned if at least one `TRUE` and one `FALSE` values. Otherwise `NA` is returned (unless `na.rm = TRUE`).

 `none` returns `TRUE` only if no value is `TRUE`, including when no values provided. The latter is the distinction from `!all()`, which returns `FALSE` when no values are provided. If the values provided include one or more `NA` values, `FALSE` is returned if at least one value is `TRUE`. Otherwise `NA` is returned (unless `na.rm = TRUE`).

=== Examples ===

{{{#!highlight r

some(c(T, F, F)) # TRUE
some(c(T, T, T)) # FALSE because all TRUE
some(c(F, F, F)) # FALSE
some()           # FALSE 

none(c(F, F, F)) # TRUE
none(c(T, F, F)) # FALSE
none()           # TRUE

}}}

------

== contractSeqs ==

Contract sequences with continous elements as ranges

=== Description ===

Contract sequences with continous elements as ranges

=== Usage ===

{{{#!highlight r

contractSeqs(x, rng = "-", sep = ",", conj = sep, empty = "")

## S3 method for class 'numeric'
contractSeqs(x, rng = "-", sep = ",", conj = sep,
  empty = "")

## S3 method for class 'character'
contractSeqs(x, rng = "-", sep = ",", conj = sep,
  empty = "")

## Default S3 method:
contractSeqs(x, ...)

}}}

=== Arguments ===

 x:: a numeric integer vector, or string or character vector that can be coerced into a numeric vector.

 rng:: a character string to indicate a range.

 sep:: a character srting for separating values.

 conj:: a charater string to separate the last to values instead of sep.

 empty:: a charater string to returned, if processing of `x` fails.

=== Value ===

A formatted string with ranges contracted and each element delimited as spedcific by `sep` and `conj`.

=== Examples ===

{{{#!highlight r

s <- "1,2,3,4,8,9,16,15,14,19"
contractSeqs(s)
s1 <- unlist(strsplit(s, ","))
contractSeqs(s1)
contractSeqs(as.numeric(s1), sep= "; ", conj = " and ")

}}}

------

== escRegex ==

Escape Regex Charaters in a String

=== Description ===

Regex metacharacters to escape: `. \ | ( ) [ { ^ $ * + ?`

=== Usage ===

{{{#!highlight r

escRegex(x)

}}}

=== Arguments ===

 x:: a character vector, or an object that can be coerced to character by `as.character(x)`.

=== Value ===

Charaters in x are escaped, e.g., the dot "." is escaped to "\.".

=== Examples ===

{{{#!highlight r

pattern <- escRegex(".")
gsub(pattern, '-', '12.05.2018')

}}}

------

== %p% ==

Paste Suffix on Strings

=== Description ===

Add suffix to strings by appending strings provided.

=== Usage ===

{{{#!highlight r

e1 %p% e2

}}}

=== Arguments ===

 e1:: character strings (or elements that can be coerced to character) to be wrapped. This can be a vector, list or nested lists. If longer than `e2`, then `e2` is recycled.

 e2:: character strings (or elements that can be coerced to character) to be applied as suffixes. If longer than `e1`, then `e1` is recycled.

=== Details ===

The shorter of the two arguments is recycled, so the returned result is always the length of the longer argument. Names are preserved, with names of the first argument taking precedence.

=== Value ===

A character vector (or structure as supplied) with each element appended with the strings provided. The struture of the first argument will be retained, but this may fail if second arguement is longer. Name are preserved, with the first argument taking precedence.

=== Examples ===

{{{#!highlight r

# e2 shorter and recycled
letters[1:10] %p% 1:5
# e1 shorter and recycled
letters[1:10] %p% 1:20
# names preserved
setNames(1:5, letters[1:5]) %p% "_"

}}}

------

== %w% ==

Wrap Prefix and Suffix around Strings

=== Description ===

Wrap (bracket) strings by adding suffix and prefix to each string provided.

=== Usage ===

{{{#!highlight r

e1 %w% e2

}}}

=== Arguments ===

 e1:: character strings (or elements that can be coerced to character) to be wrapped. This can be a vector, list or nested lists.

 e2:: character vector (or list) of strings (or elements that can be coerced to character) to be applied as wrappers, and with names retained.

=== Details ===

If `e2` is a single value it is concanted to both sides of the target strings. If `e2` has two values, the first is added to the left and the second to the right of the target string. If `e2` is longer than the pairs cycled, and if the total number is odd, the the last element is applied to both sides of the target.

If empty string are proved in `e2`, the operator can be used to just add a suffix or a prefix.

If `e1` is named, these names will be preserved and returned. Names associated with `e2` are ignored.

=== Value ===

A character vector (or structure as supplied) with each element wrapped with the string provided

=== Examples ===

{{{#!highlight r

letters %w% "."
0:20 %w% c("(", ")", "<", ">", ".")
# e2 longer, extras ignored
rep("-", 10) %w% letters

}}}

------

== in.seq ==

Test Integers are in Sequence

=== Description ===

Test if items in an integer vector are within a sequence.

=== Usage ===

{{{#!highlight r

in.seq(x)

}}}

=== Arguments ===

 x:: an integer vector, or a vector that can be coerced to integer by `as.integer(x)`.

=== Value ===

If items are within a sequence (a run of 3 or more integers), TRUE is returned, otherwise FALSE is returned. NAs are also returned as FALSE.

=== Examples ===

{{{#!highlight r

in.seq(c(1:3,NA,5:7))
in.seq(as.character(1:5))

}}}

------

== isRomanDate ==

Check Validity of Dates with Roman Numerial Month

=== Description ===

Check string is a valid date with Roman numerial month.

=== Usage ===

{{{#!highlight r

isRomanDate(x, sep = ".", pad = TRUE)

}}}

=== Arguments ===

 x:: A character string

 sep:: Punctuation between day-month-year. Defaults to fullstop.

 pad:: Whether days should be padded with leading 0s. Defaults to TRUE.

=== Value ===

If the supplied string parses to Roman date, returns TRUE with the `"names"` attribute set to the date formatted with numerical month for later pocessing, if needed. If the the day is not correctly zero-padded, then FALSE is returned. If the date is invalid, then NA is returned.

=== Examples ===

{{{#!highlight r

isRomanDate("02.X.2018")
isRomanDate("3-V-2015", sep="-", pad=FALSE)
isRomanDate("21.IIII.2018") # invalid Roman number, FALSE returned
isRomanDate("31.II.2018") # invalid days in month, NA returned

}}}

------

== replaceNameMatches ==

Replace Vector Names from a Lookup Vector

=== Description ===

Replace vector names using a named vector that is used as a look up table.

=== Usage ===

{{{#!highlight r

replaceNameMatches(x, lookup)

}}}

=== Arguments ===

 x:: A frequency vector or another vector with `"names"` attribute set.

 lookup:: A named character vector.

=== Value ===

If a name in `"x"` matches a value in `"lookup"`, it is replaced from the name of the matched item in `"lookup"`.

=== Examples ===

{{{#!highlight r

punctNames <- setNames(c("\t", "\n", "\r", "\u00a0", "\u2028", "\u2029"),
                       c("tab", "lf", "cr", "nbsp", "line", "para"))
hits <- setNames(1:5, c("a", "b", "\t", "c", "\u00a0"))
replaceNameMatches(hits, punctNames)

}}}

------

== romanDates ==

Check Vector of Possible Roman Dates

=== Description ===

Strings to be checked supplied as a character vector, or frequency vector with the `"names"` attribute.

=== Usage ===

{{{#!highlight r

romanDates(x, sorted = TRUE, sep = ".", pad = TRUE)

}}}

=== Arguments ===

 x:: A character vertor, or numerical vector with character strings supplied in the `"names"` attribute.

 sorted:: Whether to sort the returned list. Defaults to TRUE.

 sep:: Punctuation between day-month-year. Defaults to fullstop.

 pad:: Whether days should be padded with leading 0s. Defaults to TRUE.

=== Value ===

The function returns the same vector type as supplied. If a named frequency vector is supplied, the numerical frequencies are not altered. The character vector returned, either directly or as a `"names"` attribute, contains the the original strings appened with either "(?)" or "(??)". The former indicates the date is correct but the zero-padding of the day does not conform. The latter indicates the date is not valid (e.g., 31 days in a month with only 30 days).

If sorted = TRUE, then dates sorted in ascending chronological order included dates that are valid but not zero-padded as requested. Invalid dates are placed at then end of the list.

=== Examples ===

{{{#!highlight r

rD.test <- 1:3
names(rD.test) <- c('03.VX.2018', '05.VII.2018', '9.VIII.2018')
romanDates(rD.test)

}}}

------

= Code =

[[attachment:local.R]]

[[attachment:as.object.R]]

[[attachment:binaryfunctions.R]]

[[attachment:contractSeqs.R]]

[[attachment:helpers.R]]

[[attachment:replaceNameMatches.R]]

[[attachment:romanDates.R]]

= References =

 1. Ian Riley (2018). local: Local Functions [ir]. R package version 2018.09.02. http://rileylink.net/moin.cgi/R_coding/local-package

 1. Hadley Wickham, Peter Danenberg and Manuel Eugster (2017). roxygen2: In-Line Documentation for R. R package version 6.0.1. https://CRAN.R-project.org/package=roxygen2

 1. R Core Team (2018). R: A language and environment for statistical computing. R Foundation for Statistical Computing, Vienna, Austria. URL https://www.R-project.org/.

------

<<ViewLog()>>

------

CategoryRcoding CategoryRpackage