ff (version 4.5.0)

as.hi: Hybrid Index, coercion to

Description

The generic as.hi and its methods are the main (internal) means for preprocessing index information into the hybrid index class hi. Usually as.hi is called transparently from [.ff. However, you can explicitely do the index-preprocessing, store the Hybrid Index hi, and use the hi for subscripting.

Usage

as.hi(x, ...)
# S3 method for NULL
as.hi(x, ...)
# S3 method for hi
as.hi(x, ...)
# S3 method for ri
as.hi(x, maxindex = length(x), ...)
# S3 method for bit
as.hi(x, range = NULL, maxindex = length(x), vw = NULL
, dim = NULL, dimorder = NULL, pack = TRUE, ...)
# S3 method for bitwhich
as.hi(x, maxindex = length(x), pack = FALSE, ...)
# S3 method for call
as.hi(x, maxindex = NA, dim = NULL, dimorder = NULL, vw = NULL
, vw.convert = TRUE, pack = TRUE, envir = parent.frame(), ...)
# S3 method for name
as.hi(x, envir = parent.frame(), ...)

# S3 method for integer
as.hi(x, maxindex = NA, dim = NULL, dimorder = NULL
, symmetric = FALSE, fixdiag = NULL, vw = NULL, vw.convert = TRUE
, dimorder.convert  = TRUE, pack = TRUE, NAs = NULL, ...)
# S3 method for which
as.hi(x, ...)
# S3 method for double
as.hi(x, ...)
# S3 method for logical
as.hi(x, maxindex = NA, dim = NULL, vw = NULL, pack = TRUE, ...)
# S3 method for character
as.hi(x, names, vw = NULL, vw.convert = TRUE, ...)
# S3 method for matrix
as.hi(x, dim, dimorder = NULL, symmetric = FALSE, fixdiag = NULL
, vw = NULL, pack = TRUE, ...)

Value

an object of class hi

Arguments

x

an appropriate object of the class for which we dispatched

envir

the environment in which to evaluate components of the index expression

maxindex

maximum positive indexposition maxindex, is needed with negative indices, if vw or dim is given, maxindex is calculated automatically

names

the names of the indexed vector for character indexing

dim

the dim of the indexed matrix to be stored within the hi object

dimorder

the dimorder of the indexed matrix to be stored within the hi object, may convert interpretation of x

symmetric

the symmetric of the indexed matrix to be stored within the hi object

fixdiag

the fixdiag of the indexed matrix to be stored within the hi object

vw

the virtual window vw of the indexed vector or matrix to be stored within the hi object, see details

vw.convert

FALSE to prevent doubly virtual window conversion, this is needed for some internal calls that have done the virtual window conversion already, see details

dimorder.convert

FALSE to prevent doubly dimorder conversion, this is needed for some internal calls that have done the dimorder conversion already, see details

NAs

a vector of NA positions to be stored rlepacked, not fully supported yet

pack

FALSE to prevent rlepacking, note that this is a hint rather than a guarantee, as.hi.bit might ignore this

range

NULL or a vector with two elements indicating first and last position to be converted from 'bit' to 'hi'

...

further argument passed from generic to method or from wrapper method to as.hi.integer

Author

Jens Oehlschlägel

Details

The generic dispatches appropriately, as.hi.hi returns an hi object unchanged, as.hi.call tries to hiparse instead of evaluate its input in order to save RAM. If parsing is successfull as.hi.call will ignore its argument pack and always pack unless the subscript is too small to do so. If parsing fails it evaluates the index expression and dispatches again to one of the other methods. as.hi.name and as.hi.( are wrappers to as.hi.call. as.hi.integer is the workhorse for coercing evaluated expressions and as.hi.which is a wrapper removing the which class attribute. as.hi.double, as.hi.logical and as.hi.character are also wrappers to as.hi.integer, but note that as.hi.logical is not memory efficient because it expands all positions and then applies logical subscripting.
as.hi.matrix calls arrayIndex2vectorIndex and then as.hi.integer to interpret and preprocess matrix indices.
If the dim and dimorder parameter indicate a non-standard dimorder (dimorderStandard), the index information in x is converted from a standard dimorder interpretation to the requested dimorder.
If the vw parameter is used, the index information in x is interpreted relative to the virtual window but stored relative to the abolute origin. Back-coercion via as.integer.hi and friends will again return the index information relative to the virtual window, thus retaining symmetry and transparency of the viurtual window to the user.
You can use length to query the index length (possibly length of negative subscripts), poslength to query the number of selected elements (even with negative subscripts), and maxindex to query the largest possible index position (within virtual window, if present)
Duplicated negative indices are removed and will not be recovered by as.integer.hi.

See Also

hi for the Hybrid Index class, hiparse for parsing details, as.integer.hi for back-coercion, [.ff for ff subscripting

Examples

  message("integer indexing with and without rel-packing")
  as.hi(1:12)
  as.hi(1:12, pack=FALSE)
  message("if index is double, the wrapper method just converts to integer")
  as.hi(as.double(1:12))
  message("if index is character, the wrapper method just converts to integer")
  as.hi(c("a","b","c"), names=letters)
  message("negative index must use maxindex (or vw)")
  as.hi(-(1:3), maxindex=12)
  message("logical index can use maxindex")
  as.hi(c(FALSE, FALSE, TRUE, TRUE))
  as.hi(c(FALSE, FALSE, TRUE, TRUE), maxindex=12)

  message("matrix index")
  x <- matrix(1:12, 6)
  as.hi(rbind(c(1,1), c(1,2), c(2,1)), dim=dim(x))

  message("first ten positions within virtual window")
  i <- as.hi(1:10, vw=c(10, 80, 10))
  i
  message("back-coerce relativ to virtual window")
  as.integer(i)
  message("back-coerce relativ to absolute origin")
  as.integer(i, vw.convert=FALSE)

  message("parsed index expressions save index RAM")
    as.hi(quote(1:1000000000))
if (FALSE) {
  message("compare to RAM requirement when the index experssion is evaluated")
    as.hi(1:1000000000)
}

message("example of parsable index expression")
  a <- seq(100, 200, 20)
  as.hi(substitute(c(1:5, 4:9, a)))
  hi(c(1,4, 100),c(5,9, 200), by=c(1,1,20))

message("two examples of index expression temporarily expanded to full length due to 
non-supported use of brackets '(' and mathematical operators '+' accepting token")
message("example1: accepted token but aborted parsing because length>16")
  as.hi(quote(1+(1:16)))
message("example1: rejected token and aborted parsing because length>16")
  as.hi(quote(1+(1:17)))