1
#  lazyvec - R package for creating, testing and deploying custom ALTREP vectors
2
#
3
#  Copyright (C) 2019-present, Mark AJ Klik
4
#
5
#  This file is part of the lazyvec R package.
6
#
7
#  The lazyvec R package is free software: you can redistribute it and/or modify it
8
#  under the terms of the GNU Affero General Public License version 3 as
9
#  published by the Free Software Foundation.
10
#
11
#  The lazyvec R package is distributed in the hope that it will be useful, but
12
#  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13
#  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
14
#  for more details.
15
#
16
#  You should have received a copy of the GNU Affero General Public License along
17
#  with the lazyvec R package. If not, see <http://www.gnu.org/licenses/>.
18
#
19
#  You can contact the author at:
20
#  - lazyvec R package source repository : https://github.com/fstpackage/lazyvec
21

22

23
#' Define a custom ALTREP vector
24
#' 
25
#' This method creates a user-defined ALTREP vector with the complete ALTREP API created
26
#' in R instead of C/C++ sources.
27
#'
28
#' @param metadata custom metadata stored alongside the generated ALTREP vector.
29
#' @param vec_type data type required for the ALTREP vector, options are 'integer', 'double',
30
#' 'logical', 'raw' and 'character'. 
31
#' @param altrep_methods user-defined methods used by the resulting ALTREP vector.
32
#' @param package_environment package environment in which to evaluate the user methods. Defaults
33
#' to the lazyvec package.
34
#' @param diagnostics if TRUE, heavy type and boundary checks are performed before returning
35
#' the results of user defined methods to R. This greatly enhances the stability of lazyvec
36
#' implementation and should be set to TRUE during the development phase of new custom vectors
37
#' to avoid crashes and unexpected side-effects.
38
#' @param id identifier for your lazyvec, used for diagnostic output
39
#'
40
#' @return a user-defined ALTREP vector
41
#' @export
42
lazyvec <- function(metadata, vec_type, altrep_methods, package_environment = "lazyvec", diagnostics = TRUE,
43
  id = "lazyvec") {
44

45 3
  if (class(altrep_methods) != "lazyvec_api") {
46 0
    stop("Please use lazyvec_methods() to define the ALTREP methods for this vector")
47
  }
48

49
  # attach package
50 3
  is_attached <- require(package_environment, character.only = TRUE, quietly = TRUE)
51 0
  if (!is_attached) stop("Failed to attach package ", package_environment,
52 0
    ", please make sure it's installed correctly")
53

54 3
  altrep_methods_list <- altrep_methods
55

56
  # if diagnostics are active, user methods are stored in user data
57 3
  if (diagnostics) {
58 3
    altrep_methods_list <- diagnostics()
59 3
    metadata <- list(
60 3
      user_data = metadata,
61 3
      user_methods = altrep_methods,
62 3
      vec_id = id,
63 3
      vec_type = vec_type
64 3
    )
65
  }
66

67 3
  payload <- list(
68

69
    # user defined or diagnostic API
70 3
    altrep_methods_list,
71

72
    # (user) package environment in which to evaluate user defined mehods
73 3
    as.environment(paste0("package:", package_environment)),
74

75
    # user-defined metadata or diagnostic list including metadata
76 3
    metadata,
77

78
    # container for expanded vector
79 3
    NULL,
80

81
    # lazyvec package environment
82 3
    as.environment("package:lazyvec")
83 3
  )
84

85 3
  if (vec_type == "integer") {
86 3
    return(lazyvec_integer_wrapper(payload))
87
  }
88

89 0
  if (vec_type == "double") {
90 0
    return(lazyvec_real_wrapper(payload))
91
  }
92

93 0
  if (vec_type == "logical") {
94 0
    return(lazyvec_logical_wrapper(payload))
95
  }
96

97 0
  if (vec_type == "raw") {
98 0
    return(lazyvec_raw_wrapper(payload))
99
  }
100

101 0
  if (vec_type == "character") {
102 0
    return(lazyvec_string_wrapper(payload))
103
  }
104
}

Read our documentation on viewing source code .

Loading