Paper/patches/api/0139-Inventory-removeItemAnySlot.patch

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Zach Brown <zach.brown@destroystokyo.com>
Date: Tue, 28 Aug 2018 23:04:06 -0400
Subject: [PATCH] Inventory#removeItemAnySlot


diff --git a/src/main/java/org/bukkit/inventory/Inventory.java b/src/main/java/org/bukkit/inventory/Inventory.java
index 5576a6a8df8c95164bf2dde45d756ce8b7ec957a..f1a48eab1a357ae64545e1f1dc941c383cff8707 100644
--- a/src/main/java/org/bukkit/inventory/Inventory.java
+++ b/src/main/java/org/bukkit/inventory/Inventory.java
@@ -104,7 +104,9 @@ public interface Inventory extends Iterable<ItemStack> {
     public HashMap<Integer, ItemStack> addItem(@NotNull ItemStack... items) throws IllegalArgumentException;
 
     /**
-     * Removes the given ItemStacks from the inventory.
+     * Removes the given ItemStacks from the storage contents of the inventory.
+     * For removing ItemStacks from the inventories that have other content groups,
+     * like Player inventories, see {@link #removeItemAnySlot(ItemStack...)}.
      * <p>
      * It will try to remove 'as much as possible' from the types and amounts
      * you give as arguments.
@@ -121,10 +123,39 @@ public interface Inventory extends Iterable<ItemStack> {
      * @param items The ItemStacks to remove
      * @return A HashMap containing items that couldn't be removed.
      * @throws IllegalArgumentException if items is null
+     * @see #removeItemAnySlot(ItemStack...)
      */
     @NotNull
     public HashMap<Integer, ItemStack> removeItem(@NotNull ItemStack... items) throws IllegalArgumentException;
 
+    // Paper start
+    /**
+     * Searches all possible inventory slots in order to remove the given ItemStacks.
+     * <p>
+     * Similar to {@link Inventory#removeItem(ItemStack...)} in behavior, except this
+     * method will check all possible slots in the inventory, rather than just the main
+     * storage contents.
+     * <p>
+     * It will try to remove 'as much as possible' from the types and amounts
+     * you give as arguments.
+     * <p>
+     * The returned HashMap contains what it couldn't remove, where the key is
+     * the index of the parameter, and the value is the ItemStack at that
+     * index of the varargs parameter. If all the given ItemStacks are
+     * removed, it will return an empty HashMap.
+     * <p>
+     * It is known that in some implementations this method will also set the
+     * inputted argument amount to the number of that item not removed from
+     * slots.
+     *
+     * @param items The ItemStacks to remove
+     * @return A HashMap containing items that couldn't be removed.
+     * @throws IllegalArgumentException if items is null
+     */
+    @NotNull
+    public HashMap<Integer, ItemStack> removeItemAnySlot(@NotNull ItemStack... items) throws IllegalArgumentException;
+    // Paper end
+
     /**
      * Returns all ItemStacks from the inventory
      *