JavaAdventureRepo/src/main/java/cz/davza/studentadventure/interfaces/ICollection.java

package cz.davza.studentadventure.interfaces;
import cz.davza.studentadventure.objects.ItemStack;
/**
 * Contract for a fixed-size, slot-based item collection.
 *
 * <p>Implementations manage a collection of {@link ItemStack} entries, keyed by item code.
 * Items are stacked automatically up to their {@link IItem#getBulk()} limit,
 * and any items that cannot fit are returned as a leftover count from {@link #Add}.</p>
 *
 * <p>Used by both {@link cz.davza.studentadventure.objects.PlayerInventory} and
 * {@link cz.davza.studentadventure.objects.RoomItems}.</p>
 *
 * @param <T> the type of item this collection holds, must extend {@link IItem}
 *
 * @see cz.davza.studentadventure.base.ItemCollectionBase
 * @see ItemStack
 */
public interface ICollection<T> {
    /**
     * Adds the specified quantity of an item to the collection.
     *
     * <p>The method first attempts to top up any existing stacks of the same item
     * code, then fills empty slots with new stacks. Items that cannot fit due to
     * capacity limits are returned as a remainder.</p>
     *
     * @param item  the item to add
     * @param count the number of items to add
     * @return the number of items that could not be added (0 if all were added)
     */
    int Add(T item, int count);
    /**
     * Removes a specified number of items from the slot at the given index.
     *
     * <p>If {@code count} is greater than or equal to the stack size, the slot
     * is cleared entirely. If the index is out of bounds or the slot is empty,
     * the call is silently ignored.</p>
     *
     * @param code the items code
     * @param count the number of items to remove
     */
    void Remove(String code, int count);


    /**
     * Returns the overall capacity the collection can hold
     *
     * @return Collections bulk capacity
     */
    int GetCapacity();
    /**
     * Empties collection of all items and resets used capacity
     */
    void Empty();
    /**
     * Returns the remaining capacity of the collection
     *
     * @return Collections remaining bulk capacity (how much can still be added)
     */
    int GetRemainingCapacity();
}