Add a memoizing mask utility (#2319)

* Add a memoizing mask utility

* add utils to Masks

* license header

* PR feedback

worldedit-core/src/main/java/com/sk89q/worldedit/function/mask/MaskMemoizer.java

@@ -0,0 +1,63 @@
+/*
+ * WorldEdit, a Minecraft world manipulation toolkit
+ * Copyright (C) sk89q <http://www.sk89q.com>
+ * Copyright (C) WorldEdit team and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.sk89q.worldedit.function.mask;
+
+import com.sk89q.worldedit.math.BlockVector3;
+import com.sk89q.worldedit.util.collection.BlockMap;
+
+import javax.annotation.Nullable;
+
+/**
+ * A utility mask wrapper that memoizes the results of the given mask.
+ *
+ * <p>
+ * This should not be kept around long-term for memory usage reasons. It's intended for usage within a single operation.
+ * The function is auto-closeable to make this simpler.
+ * </p>
+ */
+public class MaskMemoizer extends AbstractMask implements AutoCloseable {
+
+    private final Mask mask;
+    private final BlockMap<Boolean> cache;
+
+    public MaskMemoizer(Mask mask) {
+        this.mask = mask;
+        this.cache = BlockMap.create();
+    }
+
+    @Override
+    public boolean test(BlockVector3 vector) {
+        return this.cache.computeIfAbsent(vector, mask::test);
+    }
+
+    public void clear() {
+        this.cache.clear();
+    }
+
+    @Override
+    public Mask2D toMask2D() {
+        return new MaskMemoizer2D(this.mask.toMask2D());
+    }
+
+    @Override
+    public void close() throws Exception {
+        clear();
+    }
+}

worldedit-core/src/main/java/com/sk89q/worldedit/function/mask/MaskMemoizer2D.java

@@ -0,0 +1,57 @@
+/*
+ * WorldEdit, a Minecraft world manipulation toolkit
+ * Copyright (C) sk89q <http://www.sk89q.com>
+ * Copyright (C) WorldEdit team and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.sk89q.worldedit.function.mask;
+
+import com.sk89q.worldedit.math.BlockVector2;
+import com.sk89q.worldedit.util.collection.BlockMap;
+
+/**
+ * A utility mask wrapper that memoizes the results of the given mask.
+ *
+ * <p>
+ * This should not be kept around long-term for memory usage reasons. It's intended for usage within a single operation.
+ * The function is auto-closeable to make this simpler.
+ * </p>
+ */
+public class MaskMemoizer2D extends AbstractMask2D implements AutoCloseable {
+
+    private final Mask2D mask;
+    private final BlockMap<Boolean> cache;
+
+    public MaskMemoizer2D(Mask2D mask) {
+        this.mask = mask;
+        this.cache = BlockMap.create();
+    }
+
+    @Override
+    public boolean test(BlockVector2 vector) {
+        // Use a Y=0 BlockVector3 to avoid creating a new BlockMap implementation
+        return this.cache.computeIfAbsent(vector.toBlockVector3(), ignored -> mask.test(vector));
+    }
+
+    public void clear() {
+        this.cache.clear();
+    }
+
+    @Override
+    public void close() throws Exception {
+        clear();
+    }
+}

worldedit-core/src/main/java/com/sk89q/worldedit/function/mask/Masks.java

@@ -55,6 +55,38 @@ public static Mask2D alwaysTrue2D() {
         return ALWAYS_TRUE;
     }
 
+    /**
+     * Memoize the given mask.
+     *
+     * <p>
+     * This should not be kept around long-term for memory usage reasons. It's intended for usage within a single operation.
+     * The function is auto-closeable to make this simpler.
+     * </p>
+     *
+     * @param mask the mask
+     * @return a memoized mask
+     */
+    public static Mask memoize(final Mask mask) {
+        checkNotNull(mask);
+        return new MaskMemoizer(mask);
+    }
+
+    /**
+     * Memoize the given mask.
+     *
+     * <p>
+     * This should not be kept around long-term for memory usage reasons. It's intended for usage within a single operation.
+     * The function is auto-closeable to make this simpler.
+     * </p>
+     *
+     * @param mask the mask
+     * @return a memoized mask
+     */
+    public static Mask2D memoize(final Mask2D mask) {
+        checkNotNull(mask);
+        return new MaskMemoizer2D(mask);
+    }
+
     /**
      * Negate the given mask.
      *