Interface ISegmentMap<K extends Comparable<K>,V extends ISegment<K>>

Type Parameters:
K - key/address type
V - value/segment type
All Superinterfaces:
Map<K,V>, NavigableMap<K,V>, SortedMap<K,V>
All Known Implementing Classes:
AddressSegmentMap, SegmentMap

@Ser public interface ISegmentMap<K extends Comparable<K>,V extends ISegment<K>> extends NavigableMap<K,V>
Definition of a segment-map, a data structure similar to an interval-map. A segment-map is a collection of non-overlapping, ordered segments. Null keys are not allowed.

Terminology:

  • Keys are referred to as addresses
  • Values are referred to segments
  • Method Details

    • add

      V add(V segment)
      Add a segment to the map. Convenience method, similar to put.
      Parameters:
      segment - value to add
      Returns:
      the added value
    • addAndMerge

      V addAndMerge(V v, BiFunction<Couple<K,K>,List<V>,V> merge)
      Adds a segment to the map and merge all the values within the overlap. If no overlap, this method just calls add(ISegment).
      Parameters:
      v - value to add
      merge - Merge function. First parameter is a Couple (begin, end) of the new merged segment. Second parameter is the list of all values to merge (including the value v). For example, a valid function would be:
       (c, l) -> new IntegerSegment(c.getFirst(), c.getSecond() - c.getFirst())
                  
    • put

      V put(K key, V segment)
      Add a segment to the map. This method throws IllegalArgumentException if:
      - the key is null or invalid
      - the key differs from value.getBegin()
      - the segment is invalid (eg, zero-length) - the segment to be inserted overlaps existing segments (alternatively, an implementation may decide to remove the overlapping segments)
      Specified by:
      put in interface Map<K extends Comparable<K>,V extends ISegment<K>>
    • putAll

      void putAll(Map<? extends K,? extends V> m)
      Add multiple segments to the map.
      Specified by:
      putAll in interface Map<K extends Comparable<K>,V extends ISegment<K>>
    • getSegmentContaining

      V getSegmentContaining(K key)
      Get the segment containing the provided address.
      Parameters:
      key - address to probe
      Returns:
      the containing segment, null if none (it is a gap)
    • getSegmentAfter

      V getSegmentAfter(K key)
      Get the closest segment after the provided address, which does not contain it.
      Parameters:
      key - address to probe
      Returns:
      the next segment, null if none (final gap)
    • getSegmentBefore

      V getSegmentBefore(K key)
      Get the closest segment before the provided address, which does not contain it.
      Parameters:
      key - address to probe
      Returns:
      the previous segment, null if none
    • getOverlappingSegmentsMap

      SortedMap<K,V> getOverlappingSegmentsMap(K begin, boolean includeFirstPartialSegment, K end, boolean includeLastPartialSegment)
      Get all segments partially or fully present in the given range. The returned map is not a view of the original map. Modifying it will not modify the original map.
      Parameters:
      begin -
      includeFirstPartialSegment -
      end -
      includeLastPartialSegment -
      Returns:
      a map
    • isEmptyRange

      boolean isEmptyRange(K begin, K end)
      Determine is the provided range is unencumbered.
      Parameters:
      begin - inclusive start address
      end - exclusive end address
      Returns:
    • contiguousSubMap

      SortedMap<K,V> contiguousSubMap(K begin, K end, ISegmentFactory<K,V> factory)
      Get a map containing all the segments in the ranges, without any gap. Unlike subMap, the map returned by this method is not a "view" of the original map; modifying this map, such as inserting or deleting items, does not modify the original map. The original segment-map is not modified; that is, if gap items, are created, they are not added to the original map.
      Parameters:
      begin - start address, inclusive. The first item should start at or after this address; any item simply containing (ie, spanning over) the start address will not be part of the resulting map.
      end - end address end address, exclusive
      factory - a factory used to generate gap items
      Returns:
    • fillGaps

      List<V> fillGaps(K begin, K end, ISegmentFactory<K,V> factory)
      Create segments to fill in the gaps in the provided range of addresses. Trailer and header gaps will be created if need be.
      Parameters:
      begin - begin address
      end - end address
      factory - a factory object used to create segments
      Returns:
      the list of segments that were created
    • generateGapItems

      List<V> generateGapItems(K begin, boolean allowHeader, K end, boolean allowTrailer, ISegmentFactory<K,V> factory, boolean addItemsToMap)
      Create segments to fill in the gaps in the provided range of addresses.
      Parameters:
      begin - begin address
      allowHeader - determine if an unbounded gap header can be filled
      end - end address
      allowTrailer - determine if an unbounded gap trailer can be filled
      factory - a factory object used to create segments
      addItemsToMap - if true, the items created to fill in the gaps in the segment map are also added to the segment map
      Returns:
      the list of segments that were created
    • generateGaps

      List<Couple<K,K>> generateGaps(K begin, boolean allowHeader, K end, boolean allowTrailer, ISegmentGapVerifier<K> verifier)
      Generate a list of segments that correspond to the ordered gaps list of this map.
      Parameters:
      begin -
      allowHeader -
      end -
      allowTrailer -
      verifier - optional verifier to customize the generated list
      Returns:
      a list of [begin, end) keys representing the gap segments
    • generateGaps

      List<Couple<K,K>> generateGaps(K begin, boolean allowHeader, K end, boolean allowTrailer)
      Generate a list of segments that correspond to the ordered gaps list of this map.
      Parameters:
      begin -
      allowHeader -
      end -
      allowTrailer -
      Returns:
      a list of [begin, end) keys representing the gap segments