Add invrefpool (#33)

Author: bkamins

Project.toml

@@ -1,7 +1,7 @@
 name = "DataAPI"
 uuid = "9a962f9c-6df0-11e9-0e5d-c546b8b5ee8a"
 authors = ["quinnj <[email protected]>"]
-version = "1.4.1"
+version = "1.5.0"
 
 [compat]
 julia = "1"

src/DataAPI.jl

@@ -69,6 +69,30 @@ default definition.
 function refpool end
 refpool(A::AbstractArray) = nothing
 
+"""
+    invrefpool(A)
+
+Whenever available, return an indexable object such that given an array `A`
+for which `refpool(A)` is not `nothing`:
+
+* for any valid index `x` into `refpool(A)`, `invrefpool(A)[refpool(A)[x]]` is equal to `x`
+  (according to `isequal`) and of the same type as `x`;
+* for any valid index `ix` into `invrefpool(A)` , `refpool(A)[invrefpool(A)[ix]]` is equal to `ix`
+  (according to `isequal`) and of the same type as `ix`.
+
+Additionally it is required that `haskey` is defined for `invrefpool(A)`,
+allowing to check if `ix` is a valid index into it.
+
+By default, `invrefpool(A)` returns `nothing`.
+
+If `invrefpool(A)` is not `nothing`, then `refpool(A)` also must not be `nothing`.
+
+This generic function is owned by DataAPI.jl itself, which is the sole provider of the
+default definition.
+"""
+function invrefpool end
+invrefpool(A::AbstractArray) = nothing
+
 """
     describe(io::IO, x)