Array types that can use sentinel values of the element type for special values
The package is registered in the General registry and so can be installed at the REPL with ] add SentinelArrays.
SentinelArray(A::AbstractArray, sentinel, value)
SentinelVector{T}(undef, len, sentinel, value)
SentinelArray{T, N}(undef, dims, sentinel, value)
Construct a SentinelArray by either wrapping an existing AbstractArray or using the standard undef pattern, which first constructs an Array to be wrapped by SentinelArray.
A SentinelArray{T} wraps an AbstractArray of type T, and accepts a sentinel and value argument. If the wrapped array has an element equal to sentinel, value is returned instead.
This allows, for example, simulating a Vector{Union{Float64, Missing}} by doing something like SentinelVector{Float64}(undef, len, NaN, missing). The resulting SentinelArray will have
eltype equal to Union{T, typeof(value)}.
If no sentinel is given, isbits element types use the value with all bits set (-1 for signed integers, typemax for unsigned integers, a NaN for floats) and other element types use #undef. The default value is missing.
A SentinelArray allows setting an element to value, which will result in the sentinel being stored in the wrapped array.
For isbits element types, if a setindex! operation is attempted with the SentinelArray's current sentinel value, another sentinel will be attempted to be chosen that doesn't already exist in the wrapped array.
If another sentinel can't be found (i.e. the values already exist in the wrapped array), an error will be thrown.
- Wrapped elements equal to the sentinel read as
value, soSentinelArray([-1, 2])is[missing, 2]. The default float sentinel is a NaN payload that real data rarely contains; for other types, pass asentinelthat can't occur in your data - For
Integertypes, every bit pattern is a valid value, so replacement sentinels are chosen at random; if usage will involve extremely high cardinality relative to the type range, consider usingVector{Union{T, Missing}}instead SentinelArrays are not allowed to have plainBoolelements since there isn't a possible sentinel- A
SentinelArrayIS NOT thread-safe when usage relies onsetindex!and potential sentinel collision (due to the check to automatically cycle the sentinel to another value); this will normally only affect smallIntegerelement types where the potential for sentinel collision is highest - Access to a
SentinelArray's raw data is possible viaparent(A)orpointer(A), but note that the raw data will NOT respect the sentinel=>value semantics; i.e. the raw data may have entries of the sentinel value.
- It is generally recommended to use
Vector{Union{T, typeof(value)}}instead ofSentinelArrayif possible - Currently, a non-copying operation like
convert(Vector{T}, A::Vector{Union{T, Missing}})isn't possible, even though you may know there aren'tmissingvalues; aSentinelArrayallows this operation by just "unwrapping" the storage array, likeparent(A) - It's also currently not possible to use
Vector{Union{T, Missing}}withMmap.mmap; withSentinelArray, you can write the parent array to disk and then doSentinelArray(Mmap.mmap(array_type, file))(assuming usage of default sentinel/value)
# initialize a new SentinelArray with default sentinel/value
A = SentinelVector{Float64}(undef, 10)
# wrap an existing array, manually providing sentinel/value
parent = zeros(UInt8, 10)
B = SentinelArray(parent, typemax(UInt8), nothing)CI tests Julia 1.3 (the minimum supported version), the latest release, and nightly on Linux, and the latest release on 32-bit Windows.
Contributions are very welcome, as are feature requests and suggestions. Please open an issue if you encounter any problems or would just like to ask a question.