From b1d7ee6ee1d682da52c24022433043fe47a0cdef Mon Sep 17 00:00:00 2001
From: Jacob Quinn <quinn.jacobd@gmail.com>
Date: Sat, 21 Nov 2020 23:05:38 -0700
Subject: [PATCH] Add droplevels! function for removing unused pool values

---
 src/DataAPI.jl   | 14 ++++++++++++++
 test/runtests.jl |  6 ++++++
 2 files changed, 20 insertions(+)

diff --git a/src/DataAPI.jl b/src/DataAPI.jl
index f4c943f..ec1ae1e 100644
--- a/src/DataAPI.jl
+++ b/src/DataAPI.jl
@@ -69,6 +69,20 @@ default definition.
 function refpool end
 refpool(A::AbstractArray) = nothing
 
+"""
+    droplevels!(A)
+
+For an array `A` that implements [`levels`](@ref DataAPI.levels)), certain levels may
+become "unused" via array modification, meaning the values still exist in the array
+"pool", but are no longer present in the actual array values. `droplevels!` remove
+such values to ensure `levels` only returns values that currently exist in the array.
+
+This generic function is owned by DataAPI.jl itself, which is the sole provider of the
+default definition.
+"""
+function droplevels! end
+droplevels!(A) = nothing
+
 """
     describe(io::IO, x)
 
diff --git a/test/runtests.jl b/test/runtests.jl
index 0496c7f..cfbf124 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -57,6 +57,12 @@ end
 
 end
 
+@testset "droplevels!" begin
+
+    @test DataAPI.droplevels!([1, 2, 3]) === nothing
+
+end
+
 @testset "Between" begin
 
     for x in (1, :a, "a"), y in (1, :a, "a")