Package io.jawk.jrt

Interface AssocArray

All Superinterfaces:
Map<Object,Object>
All Known Implementing Classes:
HashAssocArray, ListAssocArray, SortedAssocArray
public interface AssocArray extends Map<Object,Object>
An AWK associative array.

This interface extends Map and provides AWK-specific behaviour: automatic key normalization (null and uninitialized values map to ""), numeric key coercion ("1" and 1L address the same slot), and auto-creation of blank entries on first access.

Concrete implementations directly extend a JDK Map class to avoid delegation overhead:

Use the factory methods to create instances: 

 AssocArray hash = AssocArray.createHash();
 AssocArray sorted = AssocArray.createSorted();
 AssocArray list = AssocArray.createFromList(values, sortedArrayKeys);
 AssocArray aa = AssocArray.create(sortedArrayKeys);
Author:
Danny Daglas

  • Field Details

    • BLANK

      static final UninitializedObject BLANK
      A blank (uninitialized) value shared across all AWK array accesses.

  • Method Details

    • normalizeKey

      static Object normalizeKey(Object key)
      Converts a key to the canonical form expected by AWK: null and UninitializedObject map to the empty string.
      Parameters:
      key - the raw key
      Returns:
      the normalized key, never null

    • toLongKey

      static Long toLongKey(Object key)
      Attempts to parse the key as a Long.
      Parameters:
      key - the key to parse (must not be null)
      Returns:
      the Long value, or null if the key cannot be parsed as a long integer

    • isIn

      default boolean isIn(Object key)
      Returns whether a particular key is contained within the associative array.

      Unlike Map.get(Object), which auto-creates a blank entry when the key is absent, this method does not modify the array. It exists to support the AWK IN keyword.

      Parameters:
      key - Key to be checked
      Returns:
      true if the key (or its numeric equivalent) is present

    • mapString

      default String mapString()
      Provides a string representation of this associative array, recursively rendering nested arrays.
      Returns:
      a human-readable map string of the form {key=value, ...}

    • put

      default Object put(long key, Object value)
      Stores a value using a primitive long key, bypassing string parsing.

      This is a convenience overload for callers that already hold a long key. The default implementation boxes the key and delegates to Map.put(Object, Object).

      Parameters:
      key - the long key
      value - the value to associate with the key
      Returns:
      the previous value associated with the key, or null

    • getMapVersion

      default String getMapVersion()
      Returns the specification version of the underlying JDK Map class that backs this implementation.
      Returns:
      the specification version string, or null if unavailable

    • createHash

      static AssocArray createHash()
      Creates a new hash-based associative array (backed by HashMap).
      Returns:
      a new HashAssocArray

    • createSorted

      static AssocArray createSorted()
      Creates a new sorted associative array (backed by TreeMap with AWK key ordering).
      Returns:
      a new SortedAssocArray

    • create

      static AssocArray create(boolean sortedArrayKeys)
      Creates a new associative array of the appropriate type.
      Parameters:
      sortedArrayKeys - true to create a sorted (tree-backed) array, false for a hash-backed array
      Returns:
      a new AssocArray instance

    • createFromList

      static AssocArray createFromList(List<?> values, boolean sortedArrayKeys)
      Creates a new associative array materialized from a Java List.

      List elements are stored under zero-based Long keys. Nested List values are recursively materialized as associative arrays so JSON-like object trees can be traversed with AWK array syntax.

      Parameters:
      values - list values to expose as an AWK array
      sortedArrayKeys - true to create a sorted array, false for a hash-backed array
      Returns:
      a new AssocArray containing the list values

    • normalizeValue

      static Object normalizeValue(Object value, boolean sortedArrayKeys)
      Normalizes an externally supplied structured value before the AVM stores it.

      List values are converted to AssocArray instances. Map values are kept in place to preserve direct-map performance, but their nested list values are recursively converted.

      Parameters:
      value - value to normalize
      sortedArrayKeys - true when converted lists should use sorted array keys
      Returns:
      the normalized value