NAME
    Data::HashMap - Fast type-specialized hash maps implemented in C

SYNOPSIS
        use Data::HashMap::II;

        # Keyword API (fastest - bypasses method dispatch)
        my $map = Data::HashMap::II->new();
        hm_ii_put $map, 42, 100;
        my $val = hm_ii_get $map, 42;    # 100
        hm_ii_exists $map, 42;           # true
        hm_ii_remove $map, 42;

        # Method API (convenient - same operations)
        $map->put(42, 100);
        my $val = $map->get(42);         # 100
        $map->exists(42);                # true
        $map->remove(42);

        # Counter operations (integer-value variants only)
        my $count = hm_ii_incr $map, 1;  # 1
        $count = hm_ii_incr $map, 1;     # 2
        $count = hm_ii_decr $map, 1;     # 1

        # Iteration
        my @keys   = hm_ii_keys $map;
        my @values = hm_ii_values $map;
        my @pairs  = hm_ii_items $map;   # (k1, v1, k2, v2, ...)
        while (my ($k, $v) = hm_ii_each $map) { ... }

        # Bulk operations
        my $href = hm_ii_to_hash $map;   # Perl hashref snapshot
        hm_ii_clear $map;                # remove all entries

        # LRU cache (max 1000 entries, evicts least-recently-used)
        my $lru = Data::HashMap::II->new(1000);

        # TTL cache (entries expire after 60 seconds)
        my $ttl = Data::HashMap::II->new(0, 60);

        # LRU + TTL combined
        my $both = Data::HashMap::II->new(1000, 60);

        # Per-key TTL
        hm_ii_put_ttl $map, 42, 100, 30;   # expires in 30 seconds

        # Get or set default
        my $v = hm_ii_get_or_set $map, 99, 0;  # insert 0 if key 99 absent

DESCRIPTION
    Data::HashMap provides fourteen type-specialized hash map
    implementations in C, each optimized for its specific key/value type
    combination. All data access uses keyword syntax, which bypasses Perl's
    method dispatch for maximum performance. A method-call API
    ("$map->get($key)") is also available for convenience.

    Keywords are automatically enabled when you "use" a variant module.

VARIANTS
    Data::HashMap::I16 - int16 keys, int16 values (4 bytes/entry)
    Data::HashMap::I16A - int16 keys, any Perl SV* values (refs, objects,
    etc.)
    Data::HashMap::I16S - int16 keys, string values
    Data::HashMap::I32 - int32 keys, int32 values (8 bytes/entry)
    Data::HashMap::I32A - int32 keys, any Perl SV* values (refs, objects,
    etc.)
    Data::HashMap::I32S - int32 keys, string values
    Data::HashMap::II - int64 keys, int64 values (16 bytes/entry)
    Data::HashMap::IA - int64 keys, any Perl SV* values (refs, objects,
    etc.)
    Data::HashMap::IS - int64 keys, string values
    Data::HashMap::SA - string keys, any Perl SV* values (refs, objects,
    etc.)
    Data::HashMap::SI16 - string keys, int16 values
    Data::HashMap::SI32 - string keys, int32 values
    Data::HashMap::SI - string keys, int64 values
    Data::HashMap::SS - string keys, string values

KEYWORDS
    Each variant provides the following keywords (replace "xx" with the
    variant prefix: "i16", "i16a", "i16s", "i32", "i32a", "i32s", "ia",
    "ii", "is", "sa", "si16", "si32", "si", "ss"):

        hm_xx_put $map, $key, $value    # insert/update, returns bool
        hm_xx_get $map, $key            # lookup, returns value or undef
        hm_xx_exists $map, $key         # returns bool
        hm_xx_remove $map, $key         # returns bool
        hm_xx_size $map                 # returns entry count

        # List-returning:
        hm_xx_keys $map                 # returns list of keys
        hm_xx_values $map               # returns list of values
        hm_xx_items $map                # returns (k1,v1, k2,v2, ...)

    Integer-value variants (I16, I32, II, SI16, SI32, SI) also provide:

        hm_xx_incr $map, $key           # +1, returns new value (new keys init to 0)
        hm_xx_decr $map, $key           # -1, returns new value (new keys init to 0)
        hm_xx_incr_by $map, $key, $n    # +N, returns new value (new keys init to 0)

    All variants also provide:

        hm_xx_max_size $map             # returns max_size (0 = no LRU)
        hm_xx_ttl $map                  # returns default TTL in seconds (0 = no TTL)
        hm_xx_clear $map                # remove all entries
        hm_xx_to_hash $map              # returns a Perl hashref snapshot
        hm_xx_each $map                            # returns (key, value) or empty list
        hm_xx_iter_reset $map                      # reset each() iterator to start
        hm_xx_put_ttl $map, $key, $val, $seconds   # insert with per-key TTL
        hm_xx_get_or_set $map, $key, $default      # get existing or insert default

CONSTRUCTOR
        my $map  = Data::HashMap::II->new();           # plain (no LRU, no TTL)
        my $lru  = Data::HashMap::II->new(1000);       # LRU: max 1000 entries
        my $ttl  = Data::HashMap::II->new(0, 60);      # TTL: 60-second expiry
        my $both = Data::HashMap::II->new(1000, 60);   # LRU + TTL

  LRU eviction
    When "max_size" is set, the map acts as an LRU cache. Inserting beyond
    capacity evicts the least-recently-used entry. "get", "put" (update),
    and counter operations promote the accessed entry to most-recently-used.

  TTL expiry
    When "default_ttl" is set (in seconds), entries expire lazily: expired
    entries are removed on access ("get", "exists", counter ops) and skipped
    during iteration ("keys", "values", "items", "each", "to_hash"). Note
    that "hm_xx_size" returns the count of all inserted entries including
    those past their TTL that have not yet been lazily removed. "exists"
    does not promote entries in LRU mode (read-only check).

    Individual entries can also be given a per-key TTL via "hm_xx_put_ttl"
    or "$map->put_ttl($key, $value, $seconds)", even on maps created without
    a default TTL. The expires array is lazily allocated on first use.

    Both features use parallel arrays indexed by slot, keeping the core node
    struct unchanged. Maps created without LRU/TTL have zero overhead beyond
    a never-taken branch.

PERFORMANCE
    Benchmarks with 100k entries on Linux x86_64 (higher is better):

        INSERT (iterations/sec):
                  Rate perl_ss perl_ii    SA    SS  SI32    SI  I32S    IS   II  I32  I16
        perl_ss 18.0/s      --     -0%  -10%  -24%  -49%  -50%  -50%  -51% -80% -80% -95%
        perl_ii 18.1/s      0%      --  -10%  -23%  -49%  -50%  -50%  -50% -80% -80% -94%
        SA      20.1/s     11%     11%    --  -15%  -43%  -44%  -44%  -45% -77% -77% -94%
        SS      23.6/s     31%     30%   17%    --  -33%  -34%  -34%  -35% -73% -73% -93%
        SI32    35.4/s     96%     96%   76%   50%    --   -1%   -1%   -3% -59% -60% -89%
        SI      35.8/s     99%     98%   79%   52%    1%    --   -0%   -2% -59% -59% -89%
        I32S    35.9/s     99%     99%   79%   52%    2%    0%    --   -1% -59% -59% -89%
        IS      36.5/s    102%    102%   82%   55%    3%    2%    1%    -- -58% -59% -89%
        II      88.2/s    390%    388%  340%  274%  149%  146%  146%  142%   --  -1% -73%
        I32     87.1/s    383%    382%  334%  269%  146%  143%  142%  139%  -1%   -- -73%
        I16      328/s   1722%   1717% 1536% 1293%  828%  817%  814%  801% 272% 277%   --

        LOOKUP (iterations/sec):
                  Rate    SS  SI32    SI perl_ii perl_ss  I32S    IS    II   I32   I16
        SS      27.1/s    --   -6%   -6%    -25%    -29%  -42%  -47%  -69%  -71%  -93%
        SI32    28.9/s    7%    --   -0%    -20%    -25%  -38%  -43%  -66%  -69%  -92%
        SI      28.9/s    7%    0%    --    -20%    -25%  -38%  -43%  -66%  -69%  -92%
        perl_ii 36.0/s   33%   25%   25%      --     -6%  -23%  -29%  -58%  -62%  -90%
        perl_ss 38.3/s   42%   32%   33%      6%      --  -18%  -25%  -55%  -60%  -89%
        I32S    47.0/s   74%   63%   63%     31%     23%    --   -8%  -45%  -50%  -87%
        IS      51.1/s   89%   77%   77%     42%     33%    9%    --  -41%  -46%  -86%
        II      86.0/s  218%  197%  198%    139%    124%   83%   68%    --   -9%  -76%
        I32     94.7/s  250%  227%  228%    163%    147%  101%   85%   10%    --  -74%
        I16      365/s 1249% 1162% 1165%    913%    852%  676%  614%  325%  285%    --

        ITERATE with each() (iterations/sec):
                  Rate perl_ii perl_ss    SS    IS    SI    II   I32   I16
        perl_ii 34.6/s      --     -6%  -16%  -30%  -37%  -52%  -53%  -87%
        perl_ss 36.8/s      6%      --  -11%  -26%  -33%  -48%  -50%  -86%
        SS      41.4/s     20%     13%    --  -17%  -24%  -42%  -43%  -84%
        IS      49.7/s     44%     35%   20%    --   -9%  -30%  -32%  -81%
        SI      54.7/s     58%     48%   32%   10%    --  -24%  -25%  -79%
        II      71.5/s    106%     94%   72%   44%   31%    --   -2%  -72%
        I32     73.1/s    111%     98%   76%   47%   34%    2%    --  -72%
        I16      257/s    643%    598%  520%  417%  370%  260%  252%    --

        ITERATE with keys() (iterations/sec):
                  Rate perl_ii perl_ss    SS    SI    II   I32
        perl_ii 89.0/s      --     -3%  -34%  -41%  -76%  -77%
        perl_ss 92.1/s      3%      --  -32%  -39%  -75%  -77%
        SS       135/s     52%     47%    --  -11%  -63%  -66%
        SI       151/s     70%     64%   12%    --  -59%  -62%
        II       367/s    313%    299%  172%  143%    --   -7%
        I32      395/s    343%    328%  192%  161%    7%    --

        ITERATE with items() vs each-in-loop (iterations/sec):
                    Rate perl_each   perl_kv   SS_each   II_each  SS_items  II_items
        perl_each 35.3/s        --      -13%      -16%      -52%      -53%      -83%
        perl_kv   40.4/s       14%        --       -4%      -45%      -47%      -81%
        SS_each   42.2/s       20%        5%        --      -42%      -44%      -80%
        II_each   73.0/s      107%       81%       73%        --       -3%      -66%
        SS_items  75.5/s      114%       87%       79%        3%        --      -65%
        II_items   214/s      505%      429%      406%      192%      183%        --

  LRU / TTL overhead
    LRU and TTL add parallel arrays for linked-list pointers and expiry
    timestamps. Maps created without these features have zero overhead
    beyond a never-taken branch.

        INSERT, II variant (iterations/sec):
                     Rate II_lru_ttl     II_lru         II
        II_lru_ttl 65.9/s         --        -3%       -26%
        II_lru     68.1/s         3%         --       -24%
        II         89.6/s        36%        32%         --

        LOOKUP, II variant (iterations/sec):
                     Rate II_lru_ttl     II_lru         II
        II_lru_ttl 69.5/s         --        -8%       -22%
        II_lru     75.7/s         9%         --       -15%
        II         89.3/s        29%        18%         --

        LRU EVICTION CHURN: insert 100k into capacity 50k (iterations/sec):
                     Rate II_lru_ttl     II_lru
        II_lru_ttl 75.8/s         --        -5%
        II_lru     79.4/s         5%         --

  Method vs keyword overhead
    Keywords bypass Perl's method dispatch for maximum performance. Method
    calls ("$map->get($key)") are convenient but slower:

        II variant, 100k operations (iterations/sec):
                        keyword    method    overhead
        LOOKUP           87.4/s    75.5/s       -14%
        INSERT           85.2/s    76.0/s       -11%

MEMORY
    Memory usage with 1M entries (fork-isolated measurements):

        Variant       Memory       Bytes/entry   vs Perl hash
        -------       ------       -----------   ------------
        I16*           0.5 MB        19            9x less
        I32            28 MB         30            5.5x less
        II             44 MB         46            3.5x less
        I32S           72 MB         75            2.3x less
        IS             72 MB         75            2.3x less
        SI16           72 MB         75            2.3x less
        SI32           72 MB         75            2.3x less
        SI             72 MB         75            2.3x less
        SS            118 MB        124            1.4x less
        SA            137 MB        144            1.2x less
        IA             90 MB         95            1.8x less
        perl %h (int) 155 MB        163            (baseline)
        perl %h (str) 162 MB        170            (baseline)

        * I16 measured at 30k entries (int16 key range limits max unique keys to ~65k)

  LRU / TTL memory overhead
    Overhead per entry for LRU (prev/next pointers) and TTL (expiry
    timestamp), measured with 1M entries in fork-isolated processes.

        II variant (int64/int64):
        Variant        Bytes/entry   LRU overhead   +TTL overhead
        -------        -----------   ------------   -------------
        II                    46.5       -              -
        II_lru                67.4     +20.9 B          -
        II_lru_ttl            80.0       -            +12.6 B

        SS variant (string/string, various key+value sizes):
        Variant        Bytes/entry   LRU overhead   +TTL overhead
        -------        -----------   ------------   -------------
        SS  8B keys          124.0       -              -
        SS  8B lru           140.8     +16.8 B          -
        SS  8B lru+ttl       152.3       -            +11.5 B
        SS 16B keys          124.0       -              -
        SS 16B lru           140.8     +16.8 B          -
        SS 16B lru+ttl       152.3       -            +11.5 B
        SS 32B keys          156.0       -              -
        SS 32B lru           172.8     +16.8 B          -
        SS 32B lru+ttl       181.2       -             +8.4 B
        SS 64B keys          220.0       -              -
        SS 64B lru           236.8     +16.8 B          -
        SS 64B lru+ttl       245.2       -             +8.4 B

IMPLEMENTATION
    *   Open addressing with linear probing

    *   xxHash-inspired hash functions (64-bit mix for integers, 32-bit mix
        for strings)

    *   Automatic resize at 75% load factor

    *   Tombstone deletion with automatic compaction

    *   Raw C strings (no Perl SV overhead) for string storage

    *   UTF-8 flag packed into high bit of length fields

    *   Sentinel values for integer keys (INT_MIN, INT_MIN+1 are reserved)

DEPENDENCIES
    XS::Parse::Keyword (>= 0.40)

AUTHOR
    vividsnow

LICENSE
    This is free software; you can redistribute it and/or modify it under
    the same terms as Perl itself.