Memory-Efficient Collections

/**
 * Memory-efficient map with dynamic internal representation
 */
public interface EconomicMap<K, V> extends UnmodifiableEconomicMap<K, V> {
    /** Create empty map with default equivalence strategy */
    static <K, V> EconomicMap<K, V> create();
    
    /** Create empty map with custom equivalence strategy */
    static <K, V> EconomicMap<K, V> create(Equivalence strategy);
    
    /** Create empty map with expected size hint */
    static <K, V> EconomicMap<K, V> create(int expectedSize);
    
    /** Create map from existing java.util.Map */
    static <K, V> EconomicMap<K, V> wrapMap(Map<K, V> map);
    
    /** Create map with single key-value pair */
    static <K, V> EconomicMap<K, V> of(K key, V value);
    
    /** Create map with multiple key-value pairs */
    static <K, V> EconomicMap<K, V> of(K k1, V v1, K k2, V v2);
    
    /** Put key-value pair, returning previous value */
    V put(K key, V value);
    
    /** Put key-value pair only if key is absent */
    V putIfAbsent(K key, V value);
    
    /** Add all entries from another economic map */
    void putAll(EconomicMap<K, V> other);
    
    /** Add all entries from standard map */
    void putAll(Map<K, V> other);
    
    /** Remove key and return associated value */
    V removeKey(K key);
    
    /** Remove all entries */
    void clear();
    
    /** Replace all values using provided function */
    void replaceAll(BiFunction<? super K, ? super V, ? extends V> function);
}

/**
 * Read-only view of economic map
 */
public interface UnmodifiableEconomicMap<K, V> {
    /** Get value for key, or null if not present */
    V get(K key);
    
    /** Get value for key, or default if not present */
    V get(K key, V defaultValue);
    
    /** Check if key is present in map */
    boolean containsKey(K key);
    
    /** Get number of entries */
    int size();
    
    /** Check if map is empty */
    boolean isEmpty();
    
    /** Get collection of all values */
    Iterable<V> getValues();
    
    /** Get collection of all keys */
    Iterable<K> getKeys();
    
    /** Get collection of all entries */
    Iterable<MapCursor<K, V>> getEntries();
    
    /** Convert to standard java.util.Map */
    Map<K, V> toMap();
}

import org.graalvm.collections.*;

public class MapUsageExample {
    public void demonstrateEconomicMap() {
        // Create with default settings
        EconomicMap<String, Integer> counts = EconomicMap.create();
        
        // Add entries
        counts.put("apple", 5);
        counts.put("banana", 3);
        counts.put("cherry", 8);
        
        // Safe access with default
        int appleCount = counts.get("apple", 0);
        int orangeCount = counts.get("orange", 0); // Returns 0
        
        // Iterate over entries
        for (MapCursor<String, Integer> entry : counts.getEntries()) {
            System.out.println(entry.getKey() + ": " + entry.getValue());
        }
        
        // Use custom equivalence strategy
        EconomicMap<String, String> caseInsensitive = 
            EconomicMap.create(Equivalence.IDENTITY);
        
        // Create with size hint for better performance
        EconomicMap<Integer, String> largeCounts = 
            EconomicMap.create(1000);
    }
}

/**
 * Memory-efficient set with dynamic internal representation
 */
public interface EconomicSet<E> extends UnmodifiableEconomicSet<E> {
    /** Create empty set with default equivalence strategy */
    static <E> EconomicSet<E> create();
    
    /** Create empty set with custom equivalence strategy */
    static <E> EconomicSet<E> create(Equivalence strategy);
    
    /** Create empty set with expected size hint */
    static <E> EconomicSet<E> create(int expectedSize);
    
    /** Add element to set, return true if added */
    boolean add(E element);
    
    /** Remove element from set, return true if removed */
    boolean remove(E element);
    
    /** Add all elements from collection */
    boolean addAll(Collection<? extends E> collection);
    
    /** Add all elements from another economic set */
    boolean addAll(EconomicSet<E> set);
    
    /** Remove all elements in collection */
    boolean removeAll(Collection<?> collection);
    
    /** Retain only elements in collection */
    boolean retainAll(Collection<?> collection);
    
    /** Remove all elements */
    void clear();
}

/**
 * Read-only view of economic set
 */
public interface UnmodifiableEconomicSet<E> extends Iterable<E> {
    /** Check if element is present */
    boolean contains(E element);
    
    /** Get number of elements */
    int size();
    
    /** Check if set is empty */
    boolean isEmpty();
    
    /** Convert to array */
    Object[] toArray();
    
    /** Convert to typed array */
    <T> T[] toArray(T[] array);
    
    /** Get iterator over elements */
    Iterator<E> iterator();
    
    /** Convert to standard java.util.Set */
    Set<E> toSet();
    
    /** Get empty economic set */
    static <E> UnmodifiableEconomicSet<E> emptySet();
}

public class SetUsageExample {
    public void demonstrateEconomicSet() {
        // Create set for tracking unique items
        EconomicSet<String> uniqueNames = EconomicSet.create();
        
        // Add elements
        uniqueNames.add("Alice");
        uniqueNames.add("Bob");
        uniqueNames.add("Charlie");
        uniqueNames.add("Alice"); // Duplicate, won't be added
        
        System.out.println("Size: " + uniqueNames.size()); // 3
        
        // Check containment
        if (uniqueNames.contains("Bob")) {
            System.out.println("Bob is present");
        }
        
        // Iterate elements
        for (String name : uniqueNames) {
            System.out.println("Name: " + name);
        }
        
        // Set operations
        EconomicSet<String> otherNames = EconomicSet.create();
        otherNames.add("Bob");
        otherNames.add("Diana");
        
        uniqueNames.addAll(otherNames); // Union
        uniqueNames.retainAll(Arrays.asList("Alice", "Bob")); // Intersection
    }
}

/**
 * Mutable cursor for iterating over map entries
 */
public interface MapCursor<K, V> extends UnmodifiableMapCursor<K, V> {
    /** Set value for current entry */
    void setValue(V value);
}

/**
 * Read-only cursor for map iteration
 */
public interface UnmodifiableMapCursor<K, V> {
    /** Move to next entry, return true if successful */
    boolean advance();
    
    /** Get key of current entry */
    K getKey();
    
    /** Get value of current entry */
    V getValue();
}

public class CursorExample {
    public void demonstrateCursor() {
        EconomicMap<String, Integer> map = EconomicMap.create();
        map.put("a", 1);
        map.put("b", 2);
        map.put("c", 3);
        
        // Read-only iteration
        for (UnmodifiableMapCursor<String, Integer> cursor : map.getEntries()) {
            System.out.println(cursor.getKey() + " = " + cursor.getValue());
        }
        
        // Mutable iteration - double all values
        for (MapCursor<String, Integer> cursor : map.getEntries()) {
            cursor.setValue(cursor.getValue() * 2);
        }
    }
}

/**
 * Abstract base class for custom comparison strategies
 */
public abstract class Equivalence {
    /** Default equivalence using Object.equals() and Object.hashCode() */
    public static final Equivalence DEFAULT;
    
    /** Identity equivalence using == and System.identityHashCode() */
    public static final Equivalence IDENTITY;
    
    /** Identity equivalence with system hash code optimization */
    public static final Equivalence IDENTITY_WITH_SYSTEM_HASHCODE;
    
    /** Test equality of two objects */
    public abstract boolean equals(Object a, Object b);
    
    /** Compute hash code for object */
    public abstract int hashCode(Object o);
}

public class EquivalenceExample {
    // Custom equivalence for case-insensitive strings
    public static final Equivalence CASE_INSENSITIVE = new Equivalence() {
        @Override
        public boolean equals(Object a, Object b) {
            if (a == b) return true;
            if (a == null || b == null) return false;
            return a.toString().equalsIgnoreCase(b.toString());
        }
        
        @Override
        public int hashCode(Object o) {
            return o == null ? 0 : o.toString().toLowerCase().hashCode();
        }
    };
    
    public void demonstrateCustomEquivalence() {
        EconomicMap<String, String> caseInsensitiveMap = 
            EconomicMap.create(CASE_INSENSITIVE);
        
        caseInsensitiveMap.put("Hello", "World");
        String value = caseInsensitiveMap.get("HELLO"); // Returns "World"
        
        // Identity-based map for object instances
        EconomicMap<String, Integer> identityMap = 
            EconomicMap.create(Equivalence.IDENTITY);
        
        String s1 = new String("key");
        String s2 = new String("key");
        identityMap.put(s1, 1);
        identityMap.put(s2, 2); // Different entry due to identity comparison
    }
}

/**
 * Immutable pair container for two related values
 */
public final class Pair<L, R> {
    /** Create pair with left and right values */
    public static <L, R> Pair<L, R> create(L left, R right);
    
    /** Get left value */
    public L getLeft();
    
    /** Get right value */
    public R getRight();
    
    /** Create pair with null values */
    public static <L, R> Pair<L, R> empty();
}

/**
 * Thread-safe object pool for reusing expensive objects
 */
public final class LockFreePool<T> {
    /** Create pool with factory function */
    public static <T> LockFreePool<T> create(Supplier<T> factory);
    
    /** Get object from pool or create new one */
    public T get();
    
    /** Return object to pool for reuse */
    public void put(T object);
    
    /** Clear all pooled objects */
    public void clear();
}

/**
 * Lock-free radix tree for string keys
 */
public final class LockFreePrefixTree {
    /** Create empty prefix tree */
    public static LockFreePrefixTree create();
    
    /** Put key-value pair */
    public void put(String key, Object value);
    
    /** Get value for key */
    public Object get(String key);
    
    /** Remove key */
    public Object remove(String key);
    
    /** Check if key exists */
    public boolean containsKey(String key);
    
    /** Get all keys with given prefix */
    public Set<String> getKeysWithPrefix(String prefix);
}

/**
 * Sequential lock-based prefix tree with consistent reads
 */
public final class SeqLockPrefixTree {
    /** Create empty sequential lock prefix tree */
    public static SeqLockPrefixTree create();
    
    /** Put key-value pair */
    public void put(String key, Object value);
    
    /** Get value for key with consistent read */
    public Object get(String key);
    
    /** Remove key */
    public Object remove(String key);
    
    /** Get size of tree */
    public int size();
}

public class UtilityExample {
    public void demonstrateUtilities() {
        // Pair usage
        Pair<String, Integer> nameAge = Pair.create("Alice", 30);
        System.out.println(nameAge.getLeft() + " is " + nameAge.getRight());
        
        // Object pool for expensive resources
        LockFreePool<StringBuilder> builderPool = 
            LockFreePool.create(() -> new StringBuilder(256));
        
        StringBuilder sb = builderPool.get();
        try {
            sb.append("Hello").append(" World");
            String result = sb.toString();
        } finally {
            sb.setLength(0); // Reset for reuse
            builderPool.put(sb);
        }
        
        // Prefix tree for fast string lookups
        LockFreePrefixTree tree = LockFreePrefixTree.create();
        tree.put("apple", "fruit");
        tree.put("application", "software");
        tree.put("apply", "action");
        
        // Find all keys starting with "app"
        Set<String> appKeys = tree.getKeysWithPrefix("app");
        // Returns: ["apple", "application", "apply"]
    }
}

// Map wrapper implementation
public final class EconomicMapWrap<K, V> implements EconomicMap<K, V> {
    /** Wrap existing java.util.Map as EconomicMap */
    public static <K, V> EconomicMap<K, V> create(Map<K, V> map);
}

// Iterator types
public interface Iterator<E> {
    boolean hasNext();
    E next();
    void remove();
}

// Collection operation results
public interface Collection<E> extends Iterable<E> {
    int size();
    boolean isEmpty();
    boolean contains(Object o);
    Object[] toArray();
    <T> T[] toArray(T[] a);
    boolean add(E e);
    boolean remove(Object o);
}