====== cItemGrid class ======
This class represents a 2D array of items. It is used as the underlying storage and API for all cases that use a grid of items:
  * Chest contents
  * (TODO) Chest minecart contents
  * Dispenser contents
  * Dropper contents
  * (TODO) Furnace contents (?)
  * (TODO) Hopper contents
  * (TODO) Hopper minecart contents
  * Player Inventory areas
  * (TODO) Trapped chest contents

The items contained in this object are accessed either by a pair of XY coords, or a slot number (x + Width * y). There are functions available for converting between the two formats.

===== Functions =====
^ Function name ^ Parameters ^ Return value ^ Note ^
| AddItem | [[API:cItem|cItem]], [AllowNewStacks] | number | Adds an item to the storage; if AllowNewStacks is true (default), will also create new stacks in empty slots. Returns the number of items added |
| AddItems | [[API:cItems|cItems]], [AllowNewStacks] | number | Same as AddItem, but for several items at once |
| ChangeSlotCount | SlotNum, AddToCount | number | Adds AddToCount to the count of items in the specified slot. If the slot was empty, ignores the call. Returns the new count in the slot, or -1 if invalid SlotNum |
| ChangeSlotCount | X, Y, AddToCount | number | Adds AddToCount to the count of items in the specified slot. If the slot was empty, ignores the call. Returns the new count in the slot, or -1 if invalid slot coords |
| Clear | | | Empties all slots |
| CopyToItems | [[API:cItems|cItems]] | | Copies all non-empty slots into the cItems object provided; original cItems contents are preserved |
| DamageItem | SlotNum, [DamageAmount] | bool | Adds the specified damage (1 by default) to the specified item, returns true if the item reached its max damage and should be destroyed |
| DamageItem | X, Y, [DamageAmount] | bool | Adds the specified damage (1 by default) to the specified item, returns true if the item reached its max damage and should be destroyed |
| EmptySlot | SlotNum | | Destroys the item in the specified slot |
| EmptySlot | X, Y | | Destroys the item in the specified slot |
| GetFirstEmptySlot | | number | Returns the SlotNumber of the first empty slot, -1 if all slots are full |
| GetHeight | | number | Returns the Y dimension of the grid |
| GetLastEmptySlot | | number | Returns the SlotNumber of the last empty slot, -1 if all slots are full |
| GetNextEmptySlot | StartFrom | number | Returns the SlotNumber of the first empty slot following StartFrom, -1 if all the following slots are full |
| GetNumSlots | | number | Returns the total number of slots in the grid (Width * Height) |
| GetSlot | SlotNumber | [[API:cItem|cItem]] | Returns the item in the specified slot. Note that the item is read-only |
| GetSlot | X, Y | [[API:cItem|cItem]] | Returns the item in the specified slot. Note that the item is read-only |
| GetSlotCoords | SlotNum | number, number | Returns the X and Y coords for the specified SlotNumber. Returns "-1, -1" on invalid SlotNumber |
| GetSlotNum | X, Y | number | Returns the SlotNumber for the specified slot coords. Returns -1 on invalid coords |
| GetWidth | | number | Returns the X dimension of the grid |
| HasItems | [[API:cItem|cItem]] | bool | Returns true if there are at least as many items of the specified type as in the parameter |
| HowManyCanFit | [[API:cItem|cItem]] | number | Returns the number of the specified items that can fit in the storage, including empty slots |
| HowManyItems | [[API:cItem|cItem]] | number | Returns the number of the specified items that are currently stored |
| IsSlotEmpty | SlotNum | bool | Returns true if the specified slot is empty, or an invalid slot is specified |
| IsSlotEmpty | X, Y | bool | Returns true if the specified slot is empty, or an invalid slot is specified |
| RemoveOneItem | SlotNum | [[API:cItem|cItem]] | Removes one item from the stack in the specified slot and returns it as a single cItem. Empty slots are skipped and an empty item is returned |
| RemoveOneItem | X, Y | [[API:cItem|cItem]] | Removes one item from the stack in the specified slot and returns it as a single cItem. Empty slots are skipped and an empty item is returned |
| SetSlot | SlotNum, [[API:cItem|cItem]] | | Sets the specified slot to the specified item |
| SetSlot | X, Y, [[API:cItem|cItem]] | | Sets the specified slot to the specified item |
===== Code Examples =====
==== Add items to player inventory =====
The following code tries to add 32 sticks to a player's main inventory:
<code lua>
local Items = cItem(E_ITEM_STICK, 32);
local PlayerMainInventory = Player:GetInventorySlots();  -- PlayerMainInventory is of type cItemGrid
local NumAdded = PlayerMainInventory:AddItem(Items);
if (NumAdded == Items.m_ItemCount) then
  -- All the sticks did fit
  LOG("Added 32 sticks");
else
  -- Some (or all) of the sticks didn't fit
  LOG("Tried to add 32 sticks, but only " .. NumAdded .. " could fit");
end
</code>

==== Damage an item =====
The following code damages the helmet in the player's armor and destroys it if it reaches max damage:
<code lua>
local PlayerArmor = Player:GetArmorSlots();  -- PlayerArmor is of type cItemGrid
if (PlayerArmor:DamageItem(0)) then  -- Helmet is at SlotNum 0
  -- The helmet has reached max damage, destroy it:
  PlayerArmor:EmptySlot(0);
end
</code>