checkVector: Check functions for vector values
In jefferys/DataRepo: Manage a large data file repository
Description
Usage
Arguments
Details
Value
Functions
Examples
Description
A check function test something about its first (required) parameter and
returns either an empty string if the check succeeds or a non-empty string if
the check fails. Even when a test fails due to an error, the error is caught
and a message will be returned. The check functions described here test
various properties of vectors.
Usage
1
2
3
4
5
6
7
8
9
10
checkIsVector(vector, mode = "any")
checkIsSingle(vector, mode = "any")
checkIsIn(vector, checklist = NULL)
checkIsNotIn(vector, checklist = NULL)
checkCharacterCount(vector, minimumCharacterCount = 1,
maximumCharacterCount = Inf, allowNA = FALSE)
Arguments
vector
A vector value to check.
mode
The mode to test, one of "logical", "integer",
"numeric", "double", "complex", "character",
"raw", "expression", or (the default) "any". Other
strings are allowed, but will always result in a failure message, including
"list".
checklist
A vector to compare the contents of vector to.
vector must be a vector with the same mode as this checklist.
minimumCharacterCount
The minimum length value must have. Shorter than
this and the check will fail. The default is 0. Often abbreviated 'min'.
maximumCharacterCount
The maximum length value must have. Longer than this
and the check will fail. The default is Inf. Often abbreviated 'max'.
allowNA
If set, skips testing any missing vector elements. By default
this is FALSE and any NA element will usually cause a test
to fail. Note, if this is set TRUE, an all-NA vector will
probably pass.
Details
Many of the these functions are simple wrappers around existing R functions.
Note, calling any of these functions with an unused parameters will cause an
actual error as that is thrown before the called function begins executing
and hence can not be trapped and converted to a message by the called
function.
Value
All functions return either an empty string if the check succeeds or
a non-empty string if the check fails (including if checking causes an
error.)
Functions
-
checkIsVector: Use to test that a vector is an atomic vector
possibly also testing it's specific type (mode). The default
mode, 'any', will match any vector type, but will not match a
list (unlike is.vector). If vector has any attributes
other than names, it is not a vector. Returns one of:
"" (empty string)
Check succeeded as vector was an atomic vector, and if a mode
other than any was specified, it was that type of vector.
"Not a vector of mode mode."
Check failed as vector was either not an atomic vector (e.g. was
a list or had some attributes), or it was a vector of a different
mode (numeric when integer wanted, etc.)
"Checking for a vector failed with the following error: ..."
Check failed unexpectedly with an error.
-
checkIsSingle: Use as a convenient method to check if a vector is a
single valued vector. Combines calls to checkIsVector and
checkLength with min and max lengths of 1. Returns one of:
"" (empty string)
Check succeeded as vector was an atomic vector of length one,
and if a mode other than any was specified, it was that type.
"Not a vector of mode mode."
Check failed as vector was either not an atomic vector (e.g. was
a list or had some attributes), or it was a vector of a different
mode (numeric when integer wanted, etc.)
"Length is not 1."
Check failed as vector was a vector (of the correct mode), but
was either empty (had length 0), or had more than one element.
"Checking for a single valued vector failed with the following error: ..."
Check failed unexpectedly with an error.
-
checkIsIn: Use to test the content of an atomic vector against
a list of allowed values. If any element of the vector is not in the
checklist, this fails. Returns one of:
"" (empty string)
Check succeeded as vector was an atomic vector of the same
mode as the checklist and it contained only elements that
were also in the checklist.
"Some element is not in the checklist."
Check failed as vector contained one or more elements that are
not in the checklist.
"Bad parameter 'checklist'. ..."
Check failed as checklist was not an atomic vector as tested by
checkIsVector.
"Bad parameter 'vector'. ..."
Check failed as vector was either not an atomic vector or it was
a vector of a different mode than checklist, as tested
by checkIsVector(vector, mode(checklist)).
"Checking for a vector failed with the following error: ..."
Check failed unexpectedly with an error.
-
checkIsNotIn: Use to test the content of an atomic vector against a
list of poison values. If any element of the vector is also found in the
checklist, this fails. Returns one of:
"" (empty string)
Check succeeded as vector was an atomic vector of the same
mode as the checklist and it contained no elements that
were also in the checklist.
"Some element is not in the checklist."
Check failed as vector contained one or more elements that were
in the checklist.
"Bad parameter 'checklist'. ..."
Check failed as checklist was not an atomic vector as tested by
checkIsVector.
"Bad parameter 'vector'. ..."
Check failed as vector was either not an atomic vector or it was
a vector of a different mode than checklist, as tested
by checkIsVector(vector, mode(checklist)).
"Checking for a vector failed with the following error: ..."
Check failed unexpectedly with an error.
-
checkCharacterCount: Use to test that all elements of a character vector
have a number of characters between minimumCharacterCount and
maximumCharacterCount, inclusive. By default checks that length is
between 1 and Inf and contains no NA_character_
values, which is probably the most common string validation case. By
default does not allow NA elements, set allowNA= TRUE to ignore
missing values. Note that NULL and empty character vectors are never
allowed. Returns one of:
"" (empty string)
Check succeeded as vector was a character vector with all string
elements at least min long, but no more than max long,
and only containing missing values if explicitly allowed by
allowNA.
"Not a vector of mode character."
Check failed as vector was either not an atomic vector (e.g. was
a list or had some attributes), or it was not a character vector
"Empty character vector."
Empty character vectors have no content to check, so always fail.
"Character count is not between minimumCharacterCount and maximumCharacterCount."
Check failed as some element in vector had a length > max, or
had a length < min (or both min and max were chosen poorly!).
"Character count is not length."
Check failed as some element in vector did not have the
specified length. This message is only given when max == min.
"Checking for character count failed with the following error: ..."
Check failed unexpectedly with an error.
Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
# Testing for an atomic vector
checkIsVector(NULL)
#=> [1] "Not a vector of mode any."
checkIsVector(c(1,2))
#=> [1] ''
checkIsVector(c(1,2), mode='numeric')
#=> [1] ''
checkIsVector(c(1,2), mode='integer')
#=> [1] "Not a vector of mode integer."
checkIsVector(c(1,2), mode='xyzzy')
#=> [1] "Not a vector of mode xyzzy"
checkIsVector(c(1,2), mode=42)
#=> [1] "Checking for a vector failed with the following error:
#=> invalid 'mode' argument"
checkIsVector( list(A=1) )
#=> [1] "Not a vector of mode any."
checkIsVector( list(A=1), mode='list' )
#=> [1] "Not a vector of mode list."
# Compared to is.vector
is.vector( list(A=1) )
#=> [1] TRUE
is.vector( list(A=1), mode='list' )
#=> [1] TRUE
# Testing for an atomic vector of length 1.
checkIsSingle( 1 )
#=> [1] ""
checkIsSingle( 1, "string" )
#=> [1] "Not a vector of mode string"
checkIsSingle( c('One string to rule them all.'), "string" )
#=> [1] ""
checkIsSingle( c(1, 2) )
#=> [1] "Length is not 1."
checkIsSingle( character(0) )
#=> [1] "Length is not 1."
checkIsSingle( character(0), "integer" )
#=> [1] "Not a vector of mode integer."
checkIsSingle( list(A=1) )
#=> [1] "Not a vector of mode any"
checkIsSingle( NULL )
#=> [1] "Not a vector of mode any"
# Checking a vector's contents for unregistered values
checkIsIn(1, checklist= 1)
#=> [1] ''
checkIsIn(c(1,2), c(1,2,3))
#=> [1] ''
checkIsIn( c( "white", "gray" ), c( "black", "white" ))
#=> 'Some element is not in the checklist.'
checkIsIn( character(0), character(0))
#=> [1] ''
checkIsIn( c(1,2) )
#=> [1] "Bad parameter 'checklist'. Not a vector of mode any."
checkIsIn( NULL, character(0) )
#=> [1] "Bad parameter 'vector'. Not a vector of mode character."
checkIsIn( c("x", NULL), c("x") )
#=> ''
checkIsIn( NA, c("a", "b", NA) )
#=> [1] "Bad parameter 'vector'. Not a vector of mode character."
# Checking a vector's contents for banned values
checkIsNotIn(1, checklist= 2)
#=> [1] ''
checkIsNotIn(c(1,2), c(3,4,5))
#=> [1] ''
checkIsNotIn( 1, c( 1,2,3 ))
#=> 'Some element is in the checklist.'
checkIsNotIn( c( "white", "gray" ), c( "black", "white" ))
#=> 'Some element is in the checklist.'
checkIsNotIn( '', character(0) )
#=> [1] ''
checkIsNotIn( character(0), '' )
#=> [1] ''
checkIsNotIn( c(1,2) )
#=> [1] "Bad parameter 'checklist'. Not a vector of mode any."
checkIsNotIn( NULL, character(0) )
#=> [1] "Bad parameter 'vector'. Not a vector of mode character."
checkIsNotIn( c("x", NULL), c("y", NULL) )
#=> ''
checkIsNotIn( NA, c("a", "b", NA) )
#=> [1] "Bad parameter 'vector'. Not a vector of mode character."
# Testing the character count of vector elements.
checkCharacterCount( 'Alice' )
#=> [1] ""
checkCharacterCount( c('Alice', 'Bob') )
#=> [1] ""
checkCharacterCount( c('Alice', 'Bob'), minimumCharacterCount= 3,
maximumCharacterCount= 5 )
#=> [1] ""
checkCharacterCount( 'Alice', min= 10 )
#=> [1] "Character count is not between 10 and Inf."
checkCharacterCount( 'Alice', max= 3 )
#=> [1] "Character count is not between 1 and 3."
checkCharacterCount( 'Alice', max= 1 )
#=> [1] "Character count is not 1."
checkCharacterCount( c('Alice', 'Bob'), min= 3, max= 4 )
#=> [1] "Character count is not between 3 and 4."
checkCharacterCount( c('Alice', 'Bob'), min= 10, max= 20 )
#=> [1] "Character count is not between 4 and 20."
checkCharacterCount( c('Alice', 'Bob'), min=5, max= 5 )
#=> [1] "Character count is not 5."
checkCharacterCount( c('Alice', '') )
#=> [1] "Character count is not between 1 and Inf"
checkCharacterCount( c('Alice', 'Bob', NA) )
#=> [1] "Contains NA"
checkCharacterCount( c('Alice', 'Bob', NA), allowNA= TRUE )
#=> [1] ""
checkCharacterCount( c('', NA), allowNA= TRUE )
#=> [1] "Character count is not between 1 and Inf"
checkCharacterCount( c('Alice', 'Bob', NA), allowNA= TRUE, min=2, max=2 )
#=> [1] "Character count is not 2."
checkCharacterCount( c(NA_character, NA_character), allowNA= TRUE, min=100, max=100 )
#=> [1] "" # Probably not what you want!
#=> [1] "Not a vector of mode character."
checkCharacterCount( NULL )
#=> [1] "Not a vector of mode character."
checkCharacterCount( list(A=1) )
#=> [1] "Not a vector of mode character."
checkCharacterCount( character(0) )
#=> [1] "Empty character vector."
jefferys/DataRepo documentation built on May 19, 2019, 3:58 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Details Value Functions Examples
Description
A check function test something about its first (required) parameter and returns either an empty string if the check succeeds or a non-empty string if the check fails. Even when a test fails due to an error, the error is caught and a message will be returned. The check functions described here test various properties of vectors.
Usage
1 2 3 4 5 6 7 8 9 10 | checkIsVector(vector, mode = "any")
checkIsSingle(vector, mode = "any")
checkIsIn(vector, checklist = NULL)
checkIsNotIn(vector, checklist = NULL)
checkCharacterCount(vector, minimumCharacterCount = 1,
maximumCharacterCount = Inf, allowNA = FALSE)
|
Arguments
vector |
A vector value to check. |
mode |
The mode to test, one of |
checklist |
A vector to compare the contents of |
minimumCharacterCount |
The minimum length |
maximumCharacterCount |
The maximum length |
allowNA |
If set, skips testing any missing vector elements. By default
this is |
Details
Many of the these functions are simple wrappers around existing R functions. Note, calling any of these functions with an unused parameters will cause an actual error as that is thrown before the called function begins executing and hence can not be trapped and converted to a message by the called function.
Value
All functions return either an empty string if the check succeeds or a non-empty string if the check fails (including if checking causes an error.)
Functions
-
checkIsVector: Use to test that avectoris an atomic vector possibly also testing it's specific type (mode). The defaultmode,'any', will match any vector type, but will not match a list (unlikeis.vector). Ifvectorhas any attributes other than names, it is not a vector. Returns one of:"" (empty string)
vectorwas an atomic vector, and if a mode other thananywas specified, it was that type of vector."Not a vector of mode
mode."vectorwas either not an atomic vector (e.g. was a list or had some attributes), or it was a vector of a differentmode(numeric when integer wanted, etc.)"Checking for a vector failed with the following error: ..."
-
checkIsSingle: Use as a convenient method to check if a vector is a single valued vector. Combines calls tocheckIsVectorandcheckLengthwith min and max lengths of 1. Returns one of:"" (empty string)
vectorwas an atomic vector of length one, and if a mode other thananywas specified, it was that type."Not a vector of mode
mode."vectorwas either not an atomic vector (e.g. was a list or had some attributes), or it was a vector of a differentmode(numeric when integer wanted, etc.)"Length is not 1."
vectorwas a vector (of the correct mode), but was either empty (had length 0), or had more than one element."Checking for a single valued vector failed with the following error: ..."
-
checkIsIn: Use to test the content of an atomic vector against a list of allowed values. If any element of the vector is not in the checklist, this fails. Returns one of:"" (empty string)
vectorwas an atomic vector of the samemodeas thechecklistand it contained only elements that were also in thechecklist."Some element is not in the checklist."
vectorcontained one or more elements that are not in thechecklist."Bad parameter 'checklist'. ..."
checklistwas not an atomic vector as tested bycheckIsVector."Bad parameter 'vector'. ..."
vectorwas either not an atomic vector or it was a vector of a differentmodethanchecklist, as tested bycheckIsVector(vector, mode(checklist))."Checking for a vector failed with the following error: ..."
-
checkIsNotIn: Use to test the content of an atomic vector against a list of poison values. If any element of the vector is also found in the checklist, this fails. Returns one of:"" (empty string)
vectorwas an atomic vector of the samemodeas thechecklistand it contained no elements that were also in thechecklist."Some element is not in the checklist."
vectorcontained one or more elements that were in thechecklist."Bad parameter 'checklist'. ..."
checklistwas not an atomic vector as tested bycheckIsVector."Bad parameter 'vector'. ..."
vectorwas either not an atomic vector or it was a vector of a differentmodethanchecklist, as tested bycheckIsVector(vector, mode(checklist))."Checking for a vector failed with the following error: ..."
-
checkCharacterCount: Use to test that all elements of a character vector have a number of characters betweenminimumCharacterCountandmaximumCharacterCount, inclusive. By default checks that length is between1andInfand contains noNA_character_values, which is probably the most common string validation case. By default does not allow NA elements, setallowNA= TRUEto ignore missing values. Note that NULL and empty character vectors are never allowed. Returns one of:"" (empty string)
vectorwas a character vector with all string elements at leastminlong, but no more thanmaxlong, and only containing missing values if explicitly allowed byallowNA."Not a vector of mode character."
vectorwas either not an atomic vector (e.g. was a list or had some attributes), or it was not a character vector"Empty character vector."
"Character count is not between
minimumCharacterCountandmaximumCharacterCount."vectorhad a length > max, or had a length < min (or both min and max were chosen poorly!)."Character count is not
length."vectordid not have the specified length. This message is only given when max == min."Checking for character count failed with the following error: ..."
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | # Testing for an atomic vector
checkIsVector(NULL)
#=> [1] "Not a vector of mode any."
checkIsVector(c(1,2))
#=> [1] ''
checkIsVector(c(1,2), mode='numeric')
#=> [1] ''
checkIsVector(c(1,2), mode='integer')
#=> [1] "Not a vector of mode integer."
checkIsVector(c(1,2), mode='xyzzy')
#=> [1] "Not a vector of mode xyzzy"
checkIsVector(c(1,2), mode=42)
#=> [1] "Checking for a vector failed with the following error:
#=> invalid 'mode' argument"
checkIsVector( list(A=1) )
#=> [1] "Not a vector of mode any."
checkIsVector( list(A=1), mode='list' )
#=> [1] "Not a vector of mode list."
# Compared to is.vector
is.vector( list(A=1) )
#=> [1] TRUE
is.vector( list(A=1), mode='list' )
#=> [1] TRUE
# Testing for an atomic vector of length 1.
checkIsSingle( 1 )
#=> [1] ""
checkIsSingle( 1, "string" )
#=> [1] "Not a vector of mode string"
checkIsSingle( c('One string to rule them all.'), "string" )
#=> [1] ""
checkIsSingle( c(1, 2) )
#=> [1] "Length is not 1."
checkIsSingle( character(0) )
#=> [1] "Length is not 1."
checkIsSingle( character(0), "integer" )
#=> [1] "Not a vector of mode integer."
checkIsSingle( list(A=1) )
#=> [1] "Not a vector of mode any"
checkIsSingle( NULL )
#=> [1] "Not a vector of mode any"
# Checking a vector's contents for unregistered values
checkIsIn(1, checklist= 1)
#=> [1] ''
checkIsIn(c(1,2), c(1,2,3))
#=> [1] ''
checkIsIn( c( "white", "gray" ), c( "black", "white" ))
#=> 'Some element is not in the checklist.'
checkIsIn( character(0), character(0))
#=> [1] ''
checkIsIn( c(1,2) )
#=> [1] "Bad parameter 'checklist'. Not a vector of mode any."
checkIsIn( NULL, character(0) )
#=> [1] "Bad parameter 'vector'. Not a vector of mode character."
checkIsIn( c("x", NULL), c("x") )
#=> ''
checkIsIn( NA, c("a", "b", NA) )
#=> [1] "Bad parameter 'vector'. Not a vector of mode character."
# Checking a vector's contents for banned values
checkIsNotIn(1, checklist= 2)
#=> [1] ''
checkIsNotIn(c(1,2), c(3,4,5))
#=> [1] ''
checkIsNotIn( 1, c( 1,2,3 ))
#=> 'Some element is in the checklist.'
checkIsNotIn( c( "white", "gray" ), c( "black", "white" ))
#=> 'Some element is in the checklist.'
checkIsNotIn( '', character(0) )
#=> [1] ''
checkIsNotIn( character(0), '' )
#=> [1] ''
checkIsNotIn( c(1,2) )
#=> [1] "Bad parameter 'checklist'. Not a vector of mode any."
checkIsNotIn( NULL, character(0) )
#=> [1] "Bad parameter 'vector'. Not a vector of mode character."
checkIsNotIn( c("x", NULL), c("y", NULL) )
#=> ''
checkIsNotIn( NA, c("a", "b", NA) )
#=> [1] "Bad parameter 'vector'. Not a vector of mode character."
# Testing the character count of vector elements.
checkCharacterCount( 'Alice' )
#=> [1] ""
checkCharacterCount( c('Alice', 'Bob') )
#=> [1] ""
checkCharacterCount( c('Alice', 'Bob'), minimumCharacterCount= 3,
maximumCharacterCount= 5 )
#=> [1] ""
checkCharacterCount( 'Alice', min= 10 )
#=> [1] "Character count is not between 10 and Inf."
checkCharacterCount( 'Alice', max= 3 )
#=> [1] "Character count is not between 1 and 3."
checkCharacterCount( 'Alice', max= 1 )
#=> [1] "Character count is not 1."
checkCharacterCount( c('Alice', 'Bob'), min= 3, max= 4 )
#=> [1] "Character count is not between 3 and 4."
checkCharacterCount( c('Alice', 'Bob'), min= 10, max= 20 )
#=> [1] "Character count is not between 4 and 20."
checkCharacterCount( c('Alice', 'Bob'), min=5, max= 5 )
#=> [1] "Character count is not 5."
checkCharacterCount( c('Alice', '') )
#=> [1] "Character count is not between 1 and Inf"
checkCharacterCount( c('Alice', 'Bob', NA) )
#=> [1] "Contains NA"
checkCharacterCount( c('Alice', 'Bob', NA), allowNA= TRUE )
#=> [1] ""
checkCharacterCount( c('', NA), allowNA= TRUE )
#=> [1] "Character count is not between 1 and Inf"
checkCharacterCount( c('Alice', 'Bob', NA), allowNA= TRUE, min=2, max=2 )
#=> [1] "Character count is not 2."
checkCharacterCount( c(NA_character, NA_character), allowNA= TRUE, min=100, max=100 )
#=> [1] "" # Probably not what you want!
#=> [1] "Not a vector of mode character."
checkCharacterCount( NULL )
#=> [1] "Not a vector of mode character."
checkCharacterCount( list(A=1) )
#=> [1] "Not a vector of mode character."
checkCharacterCount( character(0) )
#=> [1] "Empty character vector."
|
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.