add an 'equals' method to ItemStack and compatibility w/ lua '==' (#12771)

Co-authored-by: rubenwardy <rw@rubenwardy.com>
Co-authored-by: sfan5 <sfan5@live.de>

1 files changed, 17 insertions, 0 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 202f66262..46b4ed642 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -6811,6 +6811,23 @@ an itemstring, a table or `nil`.
 * `peek_item(n)`: returns taken `ItemStack`
     * Copy (don't remove) up to `n` items from this stack
     * `n`: number, default: `1`
+* `equals(other)`:
+    * returns `true` if this stack is identical to `other`.
+    * Note: `stack1:to_string() == stack2:to_string()` is not reliable,
+      as stack metadata can be serialized in arbitrary order.
+    * Note: if `other` is an itemstring or table representation of an
+      ItemStack, this will always return false, even if it is
+      "equivalent".
+
+### Operators
+
+* `stack1 == stack2`:
+    * Returns whether `stack1` and `stack2` are identical.
+    * Note: `stack1:to_string() == stack2:to_string()` is not reliable,
+      as stack metadata can be serialized in arbitrary order.
+    * Note: if `stack2` is an itemstring or table representation of an
+      ItemStack, this will always return false, even if it is
+      "equivalent".
 
 `ItemStackMetaRef`
 ------------------