Package net.fabricmc.fabric.api.transfer.v1.storage

Class StorageUtil

java.lang.Object
net.fabricmc.fabric.api.transfer.v1.storage.StorageUtil
@Experimental public final class StorageUtil extends Object
Helper functions to work with Storages.

Note that the functions that take a predicate iterate over the entire inventory in the worst case. If the resource is known, there will generally be a more performance efficient way.

Experimental feature, we reserve the right to remove or change it without further notice. The transfer API is a complex addition, and we want to be able to correct possible design mistakes.

  • Method Details

    • move

      public static <T> long move(@Nullable @Nullable Storage<T> from, @Nullable @Nullable Storage<T> to, Predicate<T> filter, long maxAmount, @Nullable @Nullable TransactionContext transaction)
      Move resources between two storages, matching the passed filter, and return the amount that was successfully transferred.

      Here is a usage example with fluid variant storages: 

      
 // Source
 Storage<FluidVariant> source;
 // Target
 Storage<FluidVariant> target;

 // Move up to one bucket in total from source to target, outside of a transaction:
 long amountMoved = StorageUtil.move(source, target, variant -> true, FluidConstants.BUCKET, null);
 // Move exactly one bucket in total, only of water:
 try (Transaction transaction = Transaction.openOuter()) {
     Predicate<FluidVariant> filter = variant -> variant.isOf(Fluids.WATER);
     long waterMoved = StorageUtil.move(source, target, filter, FluidConstants.BUCKET, transaction);
     if (waterMoved == FluidConstants.BUCKET) {
         // Only commit if exactly one bucket was moved (no less!).
         transaction.commit();
     }
 }
      Type Parameters:
      T - The type of resources to move.
      Parameters:
      from - The source storage. May be null.
      to - The target storage. May be null.
      filter - The filter for transferred resources. Only resources for which this filter returns true will be transferred. This filter will never be tested with a blank resource, and filters are encouraged to throw an exception if this guarantee is violated.
      maxAmount - The maximum amount that will be transferred.
      transaction - The transaction this transfer is part of, or null if a transaction should be opened just for this transfer.
      Returns:
      The total amount of resources that was successfully transferred.
      Throws:
      IllegalStateException - If no transaction is passed and a transaction is already active on the current thread.

    • simulateInsert

      public static <T> long simulateInsert(Storage<T> storage, T resource, long maxAmount, @Nullable @Nullable TransactionContext transaction)
      Convenient helper to simulate an insertion, i.e. get the result of insert without modifying any state. The passed transaction may be null if a new transaction should be opened for the simulation.
      See Also:

    • simulateExtract

      public static <T> long simulateExtract(Storage<T> storage, T resource, long maxAmount, @Nullable @Nullable TransactionContext transaction)
      Convenient helper to simulate an extraction, i.e. get the result of extract without modifying any state. The passed transaction may be null if a new transaction should be opened for the simulation.
      See Also:

    • simulateExtract

      public static <T> long simulateExtract(StorageView<T> storageView, T resource, long maxAmount, @Nullable @Nullable TransactionContext transaction)
      Convenient helper to simulate an extraction, i.e. get the result of extract without modifying any state. The passed transaction may be null if a new transaction should be opened for the simulation.
      See Also:

    • simulateExtract

      public static <T, S extends Object & Storage<T> & StorageView<T>> long simulateExtract(S storage, T resource, long maxAmount, @Nullable @Nullable TransactionContext transaction)
      Convenient helper to simulate an extraction, i.e. get the result of extract without modifying any state. The passed transaction may be null if a new transaction should be opened for the simulation.
      See Also:
      API Note:
      This function handles the method overload conflict for objects that implement both Storage and StorageView.

    • extractAny

      @Nullable public static <T> @Nullable ResourceAmount<T> extractAny(@Nullable @Nullable Storage<T> storage, long maxAmount, TransactionContext transaction)
      Try to extract any resource from a storage, up to a maximum amount.

      This function will only ever pull from one storage view of the storage, even if multiple storage views contain the same resource.

      Parameters:
      storage - The storage, may be null.
      maxAmount - The maximum to extract.
      transaction - The transaction this operation is part of.
      Returns:
      A non-blank resource and the strictly positive amount of it that was extracted from the storage, or null if none could be found.

    • insertStacking

      public static <T> long insertStacking(List<? extends SingleSlotStorage<T>> slots, T resource, long maxAmount, TransactionContext transaction)
      Try to insert up to some amount of a resource into a list of storage slots, trying to "stack" first, i.e. prioritizing slots that already contain the resource.
      Returns:
      How much was inserted.
      See Also:

    • tryInsertStacking

      public static <T> long tryInsertStacking(@Nullable @Nullable Storage<T> storage, T resource, long maxAmount, TransactionContext transaction)
      Insert resources in a storage, attempting to stack them with existing resources first if possible.
      Parameters:
      storage - The storage, may be null.
      resource - The resource to insert. May not be blank.
      maxAmount - The maximum amount of resource to insert. May not be negative.
      transaction - The transaction this operation is part of.
      Returns:
      A nonnegative integer not greater than maxAmount: the amount that was inserted.

    • findStoredResource

      @Nullable public static <T> T findStoredResource(@Nullable @Nullable Storage<T> storage)
      Attempt to find a resource stored in the passed storage.
      Returns:
      A non-blank resource stored in the storage, or null if none could be found.
      See Also:

    • findStoredResource

      @Nullable public static <T> T findStoredResource(@Nullable @Nullable Storage<T> storage, Predicate<T> filter)
      Attempt to find a resource stored in the passed storage that matches the passed filter.
      Type Parameters:
      T - The type of the stored resources.
      Parameters:
      storage - The storage to inspect, may be null.
      filter - The filter. Only a resource for which this filter returns true will be returned.
      Returns:
      A non-blank resource stored in the storage that matches the filter, or null if none could be found.

    • findExtractableResource

      @Nullable public static <T> T findExtractableResource(@Nullable @Nullable Storage<T> storage, @Nullable @Nullable TransactionContext transaction)
      Attempt to find a resource stored in the passed storage that can be extracted.
      Returns:
      A non-blank resource stored in the storage that can be extracted, or null if none could be found.
      See Also:

    • findExtractableResource

      @Nullable public static <T> T findExtractableResource(@Nullable @Nullable Storage<T> storage, Predicate<T> filter, @Nullable @Nullable TransactionContext transaction)
      Attempt to find a resource stored in the passed storage that matches the passed filter and can be extracted.
      Type Parameters:
      T - The type of the stored resources.
      Parameters:
      storage - The storage to inspect, may be null.
      filter - The filter. Only a resource for which this filter returns true will be returned.
      transaction - The current transaction, or null if a transaction should be opened for this query.
      Returns:
      A non-blank resource stored in the storage that matches the filter and can be extracted, or null if none could be found.

    • findExtractableContent

      @Nullable public static <T> @Nullable ResourceAmount<T> findExtractableContent(@Nullable @Nullable Storage<T> storage, @Nullable @Nullable TransactionContext transaction)
      Attempt to find a resource stored in the passed storage that can be extracted, and how much of it can be extracted.
      Returns:
      A non-blank resource stored in the storage that can be extracted, and the strictly positive amount of it that can be extracted, or null if none could be found.
      See Also:

    • findExtractableContent

      @Nullable public static <T> @Nullable ResourceAmount<T> findExtractableContent(@Nullable @Nullable Storage<T> storage, Predicate<T> filter, @Nullable @Nullable TransactionContext transaction)
      Attempt to find a resource stored in the passed storage that can be extracted and matches the filter, and how much of it can be extracted.
      Type Parameters:
      T - The type of the stored resources.
      Parameters:
      storage - The storage to inspect, may be null.
      filter - The filter. Only a resource for which this filter returns true will be returned.
      transaction - The current transaction, or null if a transaction should be opened for this query.
      Returns:
      A non-blank resource stored in the storage that can be extracted and matches the filter, and the strictly positive amount of it that can be extracted, or null if none could be found.

    • calculateComparatorOutput

      public static <T> int calculateComparatorOutput(@Nullable @Nullable Storage<T> storage)
      Compute the comparator output for a storage, similar to ScreenHandler.calculateComparatorOutput(Inventory).
      Type Parameters:
      T - The type of the stored resources.
      Parameters:
      storage - The storage for which the comparator level should be computed.
      Returns:
      An integer between 0 and 15 (inclusive): the comparator output for the passed storage.