de.caff.generics

## Interface Lazy<T>

- Type Parameters:
    `T` - result type of the evaluation
  All Superinterfaces:
    java.util.function.Supplier<T>

      public interface Lazy<T>
      extends java.util.function.Supplier<T>

  Support for lazy evaluation.

  The underlying value is only created if the `Supplier.get()` method is called the first time. Later calls will return the value created on the first call.

  Since:
    April 05, 2025
  Author:
    Rammi

- - ### Method Summary

    All Methods Static Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <V> Lazy<V>` | `from(ReferenceType referenceType, java.util.function.Supplier<? extends V> supplier)` Helper method allowing to define the type of the reference which holds the value after it is provided by the supplier.
    `static <V> Lazy<V>` | `from(java.util.function.Supplier<? extends V> supplier)` Create a lazy evaluation from a supplier.
    `static <V> Lazy<V>` | `fromFragile(FragileFunction0<? extends V,?> fragileSupplier)` Create a lazy evaluation from a fragile supplier.
    `static <V> Lazy<V>` | `softFrom(java.util.function.Supplier<? extends V> supplier)` Create a lazy evaluation from a fragile supplier, but reference the value internally only via a soft reference.
    `static <V> Lazy<V>` | `softFromFragile(FragileFunction0<? extends V,?> fragileSupplier)` Create a lazy evaluation from a fragile supplier, but reference the value internally only via a soft reference.
    `static <V> Lazy<V>` | `weakFrom(java.util.function.Supplier<? extends V> supplier)` Create a lazy evaluation from a fragile supplier, but reference the value internally only via a weak reference.
    `static <V> Lazy<V>` | `weakFromFragile(FragileFunction0<? extends V,?> fragileSupplier)` Create a lazy evaluation from a fragile supplier, but reference the value internally only via a weak reference.
    `static <V> java.util.function.Supplier<V>` | `wrapFragile(FragileFunction0<? extends V,?> fragileSupplier)` Wrap a fragile supplier to be fragile no longer.

    - ### Methods inherited from interface java.util.function.Supplier

      `get`

- - ### Method Detail

    - #### from

          @NotNull
          static <V> Lazy<V> from(@NotNull
                                           java.util.function.Supplier<? extends V> supplier)

      Create a lazy evaluation from a supplier. Using this method, the value is stored after its first creation, and just returned on further calls of `Supplier.get()`.
      Type Parameters:
        `V` - value type the lazy evaluation will provide
      Parameters:
        `supplier` - The supplier which creates the value. Will only be called at most once.
      Returns:
        lazy evaluation object

    - #### fromFragile

          @NotNull
          static <V> Lazy<V> fromFragile(@NotNull
                                                  FragileFunction0<? extends V,?> fragileSupplier)

      Create a lazy evaluation from a fragile supplier. Note that in case the supplier throws the `Supplier.get()` method of the returned `Lazy` will throw a `LazyEvalutionFailure`.
      Type Parameters:
        `V` - value type of the returned lazy evaluator
      Parameters:
        `fragileSupplier` - supplier which might throw a checked exception
      Returns:
        lazy evaluator

    - #### from

          @NotNull
          static <V> Lazy<V> from(@NotNull
                                           ReferenceType referenceType,
                                           @NotNull
                                           java.util.function.Supplier<? extends V> supplier)

      Helper method allowing to define the type of the reference which holds the value after it is provided by the supplier.
      Type Parameters:
        `V` - value type of the returned lazy evaluator
      Parameters:
        `referenceType` - reference type used for keeping the value
        `supplier` - the value supplier, which might be called more than once depending on `referenceType`
      Returns:
        lazy evaluator

    - #### softFrom

          @NotNull
          static <V> Lazy<V> softFrom(@NotNull
                                               java.util.function.Supplier<? extends V> supplier)

      Create a lazy evaluation from a fragile supplier, but reference the value internally only via a soft reference.

      This allows the value to be garbage-collected when it is no longer used elsewhere, with the cost of creating it again if it is requested afterward.

      Type Parameters:
        `V` - value type of the returned lazy evaluator
      Parameters:
        `supplier` - supplier which is possibly called more than once, so it should be idempotent
      Returns:
        a lazy evaluator which keeps its value via a soft reference
      See Also:
        `SoftReference`

    - #### softFromFragile

          @NotNull
          static <V> Lazy<V> softFromFragile(@NotNull
                                                      FragileFunction0<? extends V,?> fragileSupplier)

      Create a lazy evaluation from a fragile supplier, but reference the value internally only via a soft reference.

      This allows the value to be garbage-collected when it is no longer used elsewhere, with the cost of creating it again if it is requested afterward.

      Type Parameters:
        `V` - value type of the returned lazy evaluator
      Parameters:
        `fragileSupplier` - supplier which is possibly called more than once, so it should be idempotent
      Returns:
        a lazy evaluator which keeps its value via a soft reference
      See Also:
        `SoftReference`

    - #### weakFrom

          @NotNull
          static <V> Lazy<V> weakFrom(@NotNull
                                               java.util.function.Supplier<? extends V> supplier)

      Create a lazy evaluation from a fragile supplier, but reference the value internally only via a weak reference.

      This allows the value to be garbage-collected when it is no longer used elsewhere, with the cost of creating it again if it is requested afterward.

      Type Parameters:
        `V` - value type of the returned lazy evaluator
      Parameters:
        `supplier` - supplier which is possibly called more than once, so it should be idempotent
      Returns:
        a lazy evaluator which keeps its value via a weak reference
      See Also:
        `WeakReference`

    - #### weakFromFragile

          @NotNull
          static <V> Lazy<V> weakFromFragile(@NotNull
                                                      FragileFunction0<? extends V,?> fragileSupplier)

      Create a lazy evaluation from a fragile supplier, but reference the value internally only via a weak reference.

      This allows the value to be garbage-collected when it is no longer used elsewhere, with the cost of creating it again if it is requested afterward.

      Type Parameters:
        `V` - value type of the returned lazy evaluator
      Parameters:
        `fragileSupplier` - supplier which is possibly called more than once, so it should be idempotent
      Returns:
        a lazy evaluator which keeps its value via a weak reference
      See Also:
        `WeakReference`

    - #### wrapFragile

          @NotNull
          static <V> java.util.function.Supplier<V> wrapFragile(@NotNull
                                                                         FragileFunction0<? extends V,?> fragileSupplier)

      Wrap a fragile supplier to be fragile no longer. This wraps a supplier which might throw a checked exception with one which will throw an unchecked exception instead.
      Type Parameters:
        `V` - type of supplied value
      Parameters:
        `fragileSupplier` - fragile supplier
      Returns:
        supplier which will throw a `LazyEvalutionFailure` if the original `fragileSupplier` throws an exception