Package eu.bandm.tools.lexic

Class CodePointMap<V>

java.lang.Object
eu.bandm.tools.lexic.CodePointMap<V>
Type Parameters:
V - the value type
All Implemented Interfaces:
FormatClient, Serializable
public class CodePointMap<V> extends Object implements FormatClient, Serializable
Immutable map of Unicode code point keys encoded as int values to arbitrary values.

Since the number of code points is finite but large, this class provides efficient support for total maps where nearly all points are mapped to the same value. In fact, since null is generally allowed as a value, every map is trivially total in this sense.

The implementation builds on the assumption that maps are constructed in a first phase, and used for lookups in a second. The efficiency of the latter is strongly prioritized.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    anyMatch(Predicate<? super V> pred)
    Checks whether any value of this map satisfies a given predicate.
    static <V> CodePointMap<V>
    anyOf(int[] keys, V value)
    Returns a map containing several entries with the same value.
    static <V> CodePointMap<V>
    constant(V value)
    Returns a total map containing one entry for every code point, all with the same value.
    static <V> CodePointMap<V>
    empty()
    Returns a map containing no entries.
    void
    forEach(Consumer<? super V> action)
    Performs an action for each value of this map.
    (package private) void
    forEachKey(IntConsumer action)
    Performs an action for all specifically mapped or unmapped code points.
    (package private) void
    forEachNonNullKey(IntConsumer action)
    Performs an action for all explicitly recognized code points.
    <F> F
    format(FormatServer<F> server)
    Returns a human-readable representation of this map.
    <F> F
    format(FormatServer<F> server, Function<? super V,? extends F> onValue)
    Returns a human-readable representation of this map.
    V
    get(int key)
    Returns the value associated with the given key.
    (package private) int
    getCollisions()
    Returns the number of hashtable collision in this map.
    (package private) void
    hardPatch(Map<?,?> subst)
    Changes the content of this map according to a given substitution.
    static <V, W, X> CodePointMap<X>
    intersect(CodePointMap<V> a, CodePointMap<W> b, BiFunction<? super V,? super W,? extends X> intersector)
    Returns a map containing the intersected entries of two maps, with conflicting values combined.
    <W> CodePointMap<W>
    map(Function<? super V,? extends W> fun)
    Returns a map containing the entries of this map, with all values transformed.
    static <V> CodePointMap<V>
    merge(CodePointMap<V> a, CodePointMap<V> b, BinaryOperator<V> merger)
    Returns a map containing the merged entries of two maps, with conflicting values combined.
    static <V> CodePointMap<V>
    of(Map<? extends Number,? extends V> map)
    Returns a map containing the given entries.
    static String
    quote(int c)
    Returns a representation of the given code point that works in Java literals.
    CodePointMap<V>
    simplify()
    Returns a map that differs from this map at most by discarding explicit entries that are already implicit.
    static <V> CodePointMap<V>
    singleton(int key, V value)
    Returns a map containing one entry.
    int
    size()
    Returns the number of entries in this map.
    String
    toString()
    Returns a human-readable representation of this map.
    CodePointMap<V>
    totalize(V otherwise)
    Returns a map that differs from this map by having default entries for all keys previously mapped to null.
    CodePointMap<V>
    with(int key, V value)
    Returns a map containing the entries of this map with one value added or overwritten.
    CodePointMap<V>
    with(int key, V value, @Opt BinaryOperator<V> merge)
    Returns a map containing the entries of this map with one value added or merged.
    CodePointMap<V>
    without(int key)
    Returns a map containing the entries of this map with one value removed.
    CodePointMap<V>
    without(int... keys)
    Returns a map containing the entries of this map with some values removed.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • empty

      public static <V> CodePointMap<V> empty()
      Returns a map containing no entries.
      Type Parameters:
      V - the value type
      Returns:
      a map containing no entries

    • singleton

      public static <V> CodePointMap<V> singleton(int key, V value)
      Returns a map containing one entry.
      Type Parameters:
      V - the value type
      Parameters:
      key - the code point key
      value - the associated value, possibly null
      Returns:
      a map containing the given entry
      Throws:
      IllegalArgumentException - if the given key is not a valid code point
      See Also:

    • getCollisions

      int getCollisions()
      Returns the number of hashtable collision in this map. This method is for efficiency profiling. The lower the number, the more efficient the table layout.
      Returns:
      the number of hashtable collision in this map

    • anyOf

      public static <V> CodePointMap<V> anyOf(int[] keys, V value)
      Returns a map containing several entries with the same value.

      Repeating the same code point in the array of keys has no further effect.

      Type Parameters:
      V - the value type
      Parameters:
      keys - an array of code point keys
      value - the value to associate with each of the keys
      Returns:
      a map containing entries for all given keys with the given value

    • constant

      public static <V> CodePointMap<V> constant(@Opt V value)
      Returns a total map containing one entry for every code point, all with the same value.
      Type Parameters:
      V - the value type
      Parameters:
      value - the value to associate with all code point keys
      Returns:
      a total map of all code point keys to the given value

    • of

      public static <V> CodePointMap<V> of(Map<? extends Number,? extends V> map)
      Returns a map containing the given entries.

      All map entries are iterated over when this method is called. The method Number.intValue() is used to convert keys to code points. Changes to the given map that occur after this method has returned will have no side-effect on the result.

      Type Parameters:
      V - the value type
      Parameters:
      map - the entries
      Returns:
      a map containing the given entries
      Throws:
      IllegalArgumentException - if any converted key is not a valid code point
      See Also:

    • get

      @Opt public V get(int key)
      Returns the value associated with the given key.
      Parameters:
      key - the code point key
      Returns:
      the value associated with the given key, or null if there is none

    • with

      public CodePointMap<V> with(int key, V value)
      Returns a map containing the entries of this map with one value added or overwritten.
      Parameters:
      key - the code point key to add or overwrite
      value - the value to associate with the given key
      Returns:
      a map containing the entries of this map with the given entry added or overwritten
      Throws:
      IllegalArgumentException - if the given key is not a valid code point
      See Also:

    • with

      public CodePointMap<V> with(int key, V value, @Opt @Opt BinaryOperator<V> merge)
      Returns a map containing the entries of this map with one value added or merged.

      If there is no previous entry with the same key, then the value is just added. If there is one, then the old and new value are merged using the given operator. If the merge operator is null, then the new value overwrites the old one.

      Parameters:
      key - the code point key to add or overwrite
      value - the value to associate with the given key
      merge - an operator for merging the old and the new value, or null
      Returns:
      a map containing the entries of this map with the given entry added or merged
      Throws:
      IllegalArgumentException - if the given key is not a valid code point
      See Also:

    • without

      public CodePointMap<V> without(int key)
      Returns a map containing the entries of this map with one value removed.

      Note that this operation is intended for use with constant(V) to define maps that contain most, but not all keys. No attempt is made to shrink or simplify the internal data; hence it is not guaranteed to strictly undo a preceding with(int,Object).

      Parameters:
      key - the code point key to remove
      Returns:
      a map containing the entries of this map with the given entry removed

    • without

      public CodePointMap<V> without(int... keys)
      Returns a map containing the entries of this map with some values removed.

      Note that this operation is intended for use with constant(V) to define maps that contain most, but not all keys. No attempt is made to shrink or simplify the internal data; hence it is not guaranteed to strictly undo a preceding with(int,Object).

      Parameters:
      keys - the code point keys to remove
      Returns:
      a map containing the entries of this map with the given entries removed

    • map

      public <W> CodePointMap<W> map(Function<? super V,? extends W> fun)
      Returns a map containing the entries of this map, with all values transformed.
      Type Parameters:
      W - the target value type
      Parameters:
      fun - the function for transforming all values
      Returns:
      a map containing the entries of this map, with all values transformed with the given function

    • merge

      public static <V> CodePointMap<V> merge(CodePointMap<V> a, CodePointMap<V> b, BinaryOperator<V> merger)
      Returns a map containing the merged entries of two maps, with conflicting values combined.
      Type Parameters:
      V - the value type of the maps
      Parameters:
      a - the first map
      b - the second map
      merger - the operation for combining conflicting values
      Returns:
      a map containing the merged entries of two maps, with conflicting values combined

    • intersect

      public static <V, W, X> CodePointMap<X> intersect(CodePointMap<V> a, CodePointMap<W> b, BiFunction<? super V,? super W,? extends X> intersector)
      Returns a map containing the intersected entries of two maps, with conflicting values combined.
      Type Parameters:
      V - the value type of the first map
      W - the value type of the second map
      X - the value type of the intersection map
      Parameters:
      a - the first map
      b - the second map
      intersector - the operation for combining conflicting values
      Returns:
      a map containing the intersected entries of two maps, with conflicting values combined

    • forEach

      public void forEach(Consumer<? super V> action)
      Performs an action for each value of this map.

      If a value occurs multiple times for different keys, multiple actions may be performed. It is this strongly recommended that the given action be idempotent, such as adding the value to a set.

      Parameters:
      action - the action to perform

    • toString

      public String toString()
      Returns a human-readable representation of this map.
      Overrides:
      toString in class Object

    • quote

      public static String quote(int c)
      Returns a representation of the given code point that works in Java literals.

      In particular, standard backslash escapes apply.

      Parameters:
      c - the code point to represent
      Returns:
      a representation of the given code point that works in Java literals

    • format

      public <F> F format(FormatServer<F> server)
      Returns a human-readable representation of this map.
      Specified by:
      format in interface FormatClient
      Type Parameters:
      F - the type of format objects to produce
      Parameters:
      server - a factory object that can produce format objects
      Returns:
      a format object produced by the server

    • format

      public <F> F format(FormatServer<F> server, Function<? super V,? extends F> onValue)
      Returns a human-readable representation of this map.
      Type Parameters:
      F - the type of format objects to produce
      Parameters:
      server - a factory object that can produce format objects
      onValue - the operation for computing representations of values
      Returns:
      a human-readable representation of this map

    • hardPatch

      void hardPatch(Map<?,?> subst)
      Changes the content of this map according to a given substitution.

      The type of the substituted values is not checked either at compile time or at execution time. Latent causes for ClassCastException may arise if this method is used carelessly.

      Parameters:
      subst - the substitution to apply; values not present as keys are left unchanged

    • totalize

      public CodePointMap<V> totalize(V otherwise)
      Returns a map that differs from this map by having default entries for all keys previously mapped to null.

      Note that otherwise(null) makes an equivalent copy.

      Parameters:
      otherwise - the default value to replace null
      Returns:
      a map that differs from this map by having entries for all keys previously mapped to null

    • anyMatch

      public boolean anyMatch(Predicate<? super V> pred)
      Checks whether any value of this map satisfies a given predicate.
      Parameters:
      pred - the predicate to satisfy
      Returns:
      true if this map contains a value that satisfies the given predicate; false otherwise

    • simplify

      public CodePointMap<V> simplify()
      Returns a map that differs from this map at most by discarding explicit entries that are already implicit. The resulting map may require less, but not more, space.

      This method can also be used to clean up redundant null-valued entries.

      The resulting map will be undistinguishable from this map in terms of the observable map-like behavior, i.e., results of the method get(int). It may, however, react differently to the method forEachNonNullKey(java.util.function.IntConsumer).

      Returns:
      a map that differs from this map at most by discarding explicit entries that are already implicit; can be this if no clean-up is required

    • forEachNonNullKey

      void forEachNonNullKey(IntConsumer action)
      Performs an action for all explicitly recognized code points.

      This includes all code points that have been assigned a non-null value explicitly using of(java.util.Map<? extends java.lang.Number, ? extends V>), anyOf(int[], V) or with(int, V), but not code points that have been assigned a value implicitly using constant(V) or totalize(V).

      Parameters:
      action - the action to perform

    • forEachKey

      void forEachKey(IntConsumer action)
      Performs an action for all specifically mapped or unmapped code points.

      This includes all code points that have been assigned a non-null value explicitly using of(java.util.Map<? extends java.lang.Number, ? extends V>), anyOf(int[], V) or with(int, V), as well as code points that have been exceptionally assigned a null value, but not code points that have been assigned a value implicitly using constant(V) or totalize(V).

      Parameters:
      action - the action to perform

    • size

      public int size()
      Returns the number of entries in this map.

      Both positive (non-null) and negative (null) particular entries are counted, as well as the default entry. Thus, the returned value is never less than one.

      Returns:
      the number of entries