Core Utilities

/**
 * Maps keys to values, optimized for high-performance implementations
 * @param <K> the type of keys
 * @param <V> the type of values
 */
public interface Function<K,V> extends java.util.function.Function<K,V> {
    /** Returns the value associated with the given key */
    V get(Object key);
    
    /** Returns the value for key, or defaultValue if not present */
    V getOrDefault(Object key, V defaultValue);
    
    /** Associates the value with the key (optional operation) */  
    V put(K key, V value);
    
    /** Removes the mapping for the key (optional operation) */
    V remove(Object key);
    
    /** Returns true if this function contains a mapping for the key */
    boolean containsKey(Object key);
    
    /** Returns the number of key-value mappings, or -1 if unlimited */
    int size();
    
    /** Removes all mappings (optional operation) */
    void clear();
}

import it.unimi.dsi.fastutil.Function;
import java.util.Map;
import java.util.HashMap;

// Custom function implementation
Function<String, Integer> wordLength = new Function<String, Integer>() {
    private Map<String, Integer> cache = new HashMap<>();
    
    public Integer get(Object key) {
        return cache.computeIfAbsent((String) key, String::length);
    }
    
    public boolean containsKey(Object key) {
        return key instanceof String;
    }
};

int length = wordLength.get("hello"); // Returns 5

/**
 * Utility class providing array operations and generic sorting algorithms
 */
public class Arrays {
    /** Maximum safe array size */
    public static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8;
    
    /**
     * Ensures that the range [from, to) is valid for an array of given length
     * @param arrayLength the length of the array
     * @param from the start index (inclusive)
     * @param to the end index (exclusive)
     * @throws IllegalArgumentException if the range is invalid
     */
    public static void ensureFromTo(int arrayLength, int from, int to);
    
    /**
     * Ensures that offset and length are valid for an array of given length
     * @param arrayLength the length of the array
     * @param offset the starting offset
     * @param length the number of elements
     * @throws IllegalArgumentException if parameters are invalid
     */
    public static void ensureOffsetLength(int arrayLength, int offset, int length);
    
    /**
     * Stable in-place merge sort using a comparator and swapper
     * @param from the start index (inclusive)
     * @param to the end index (exclusive)
     * @param c the comparator
     * @param swapper the swapper for element exchanges
     */
    public static void mergeSort(int from, int to, IntComparator c, Swapper swapper);
    
    /**
     * Generic quicksort using a comparator and swapper
     * @param from the start index (inclusive)
     * @param to the end index (exclusive)
     * @param comp the comparator
     * @param swapper the swapper for element exchanges
     */
    public static void quickSort(int from, int to, IntComparator comp, Swapper swapper);
    
    /**
     * Parallel quicksort using a comparator and swapper
     * @param from the start index (inclusive)
     * @param to the end index (exclusive) 
     * @param comp the comparator
     * @param swapper the swapper for element exchanges
     */
    public static void parallelQuickSort(int from, int to, IntComparator comp, Swapper swapper);
}

import it.unimi.dsi.fastutil.Arrays;
import it.unimi.dsi.fastutil.Swapper;

// Custom data structure sorting
String[] names = {"Charlie", "Alice", "Bob"};
Arrays.quickSort(0, names.length, 
    (i, j) -> names[i].compareTo(names[j]),
    (i, j) -> { String temp = names[i]; names[i] = names[j]; names[j] = temp; });
// Result: names = ["Alice", "Bob", "Charlie"]

/**
 * Interface providing constants and strategy for hash-based data structures
 */
public interface Hash {
    /** Default initial capacity for hash structures */
    int DEFAULT_INITIAL_SIZE = 16;
    
    /** Default load factor balancing space and time */
    float DEFAULT_LOAD_FACTOR = 0.75f;
    
    /** Fast load factor for speed-optimized structures */
    float FAST_LOAD_FACTOR = 0.5f;
    
    /** Very fast load factor for maximum speed */
    float VERY_FAST_LOAD_FACTOR = 0.25f;
    
    /**
     * Custom hash strategy for objects
     * @param <K> the type of keys
     */
    interface Strategy<K> {
        /** Compute hash code for the object */
        int hashCode(K o);
        
        /** Test equality between two objects */
        boolean equals(K a, K b);
    }
}

/**
 * Utility class providing common hash methods
 */
public class HashCommon {
    /**
     * MurmurHash3 finalization step for avalanching bits
     * @param x the value to hash
     * @return the finalized hash value
     */
    public static int murmurHash3(int x);
    
    // Additional hash methods for other primitive types
    public static int murmurHash3(long x);
    public static int murmurHash3(float x);
    public static int murmurHash3(double x);
}

/**
 * Utility class for safe conversions between primitive types
 */
public final class SafeMath {
    /**
     * Safely convert int to char, throwing exception on overflow
     * @param value the int value to convert
     * @return the char value
     * @throws IllegalArgumentException if value is outside char range
     */
    public static char safeIntToChar(int value);
    
    /**
     * Safely convert int to byte, throwing exception on overflow
     * @param value the int value to convert
     * @return the byte value
     * @throws IllegalArgumentException if value is outside byte range
     */
    public static byte safeIntToByte(int value);
    
    /**
     * Safely convert int to short, throwing exception on overflow
     * @param value the int value to convert
     * @return the short value
     * @throws IllegalArgumentException if value is outside short range
     */
    public static short safeIntToShort(int value);
    
    /**
     * Safely convert long to int, throwing exception on overflow
     * @param value the long value to convert
     * @return the int value
     * @throws IllegalArgumentException if value is outside int range
     */
    public static int safeLongToInt(long value);
    
    /**
     * Safely convert long to char, throwing exception on overflow
     * @param value the long value to convert
     * @return the char value
     * @throws IllegalArgumentException if value is outside char range
     */
    public static char safeLongToChar(long value);
    
    /**
     * Safely convert long to byte, throwing exception on overflow
     * @param value the long value to convert
     * @return the byte value
     * @throws IllegalArgumentException if value is outside byte range
     */
    public static byte safeLongToByte(long value);
    
    /**
     * Safely convert long to short, throwing exception on overflow
     * @param value the long value to convert
     * @return the short value
     * @throws IllegalArgumentException if value is outside short range
     */
    public static short safeLongToShort(long value);
    
    /**
     * Safely convert double to float, throwing exception on overflow
     * @param value the double value to convert
     * @return the float value
     * @throws IllegalArgumentException if value is outside float range
     */
    public static float safeDoubleToFloat(double value);
}

/**
 * Functional interface for swapping elements at integer positions
 */
@FunctionalInterface
public interface Swapper {
    /**
     * Swap elements at positions a and b
     * @param a first position
     * @param b second position
     */
    void swap(int a, int b);
}

/**
 * Functional interface for swapping elements at 64-bit positions
 */  
@FunctionalInterface
public interface BigSwapper {
    /**
     * Swap elements at 64-bit positions a and b
     * @param a first position
     * @param b second position
     */
    void swap(long a, long b);
}

/**
 * Iterator supporting both forward and backward traversal
 * @param <K> the type of elements
 */
public interface BidirectionalIterator<K> extends Iterator<K> {
    /**
     * Get the previous element in the iteration
     * @return the previous element
     * @throws NoSuchElementException if no previous element
     */
    K previous();
    
    /**
     * Check if there is a previous element
     * @return true if there is a previous element
     */
    boolean hasPrevious();
}

/**
 * Bidirectional iterator for BigList with 64-bit indices
 * @param <K> the type of elements  
 */
public interface BigListIterator<K> extends BidirectionalIterator<K> {
    /**
     * Get the next index as a long value
     * @return the next index
     */
    long nextIndex();
    
    /**
     * Get the previous index as a long value
     * @return the previous index
     */
    long previousIndex();
    
    /**
     * Add an element at the current position
     * @param k the element to add
     */
    void add(K k);
    
    /**
     * Set the element at the current position
     * @param k the element to set
     */
    void set(K k);
}

/**
 * Generic pair of elements with multiple access patterns
 * @param <L> type of left element
 * @param <R> type of right element
 */
public interface Pair<L,R> {
    /** Get the left element */
    L left();
    
    /** Get the right element */
    R right();
    
    /** Set the left element (optional operation) */
    Pair<L,R> left(L l);
    
    /** Set the right element (optional operation) */
    Pair<L,R> right(R r);
    
    // Alternative accessors
    /** Alias for left() */
    default L first() { return left(); }
    
    /** Alias for right() */
    default R second() { return right(); }
    
    /** Alias for left() when used as key-value pair */
    default L key() { return left(); }
    
    /** Alias for right() when used as key-value pair */
    default R value() { return right(); }
}

/**
 * Pair where left element is always ≤ right element
 * @param <K> type of elements (must be Comparable)
 */
public interface SortedPair<K> extends Pair<K,K>, Comparable<SortedPair<? extends K>> {
    /**
     * Create a sorted pair ensuring left ≤ right
     * @param l first element
     * @param r second element  
     * @return sorted pair with smaller element as left
     */
    static <K extends Comparable<K>> SortedPair<K> of(K l, K r);
}

import it.unimi.dsi.fastutil.Pair;
import it.unimi.dsi.fastutil.SortedPair;

// Using pairs for coordinate representation
Pair<Integer, Integer> coordinate = Pair.of(10, 20);
int x = coordinate.first(); // or coordinate.left()
int y = coordinate.second(); // or coordinate.right()

// Using sorted pairs
SortedPair<Integer> range = SortedPair.of(100, 50);
int min = range.left(); // 50 (smaller value)
int max = range.right(); // 100 (larger value)