public interface

ISegmentMap

implements NavigableMap<K, V>
com.pnfsoftware.jeb.util.collect.ISegmentMap<K extends java.lang.Comparable<K>, V extends com.pnfsoftware.jeb.util.collect.ISegment<K>>
Known Indirect Subclasses

Class Overview

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

Summary

Public Methods
abstract V add(V segment)
Add a segment to the map.
abstract 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.
abstract 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.
abstract List<V> fillGaps(K begin, K end, ISegmentFactory<K, V> factory)
Create segments to fill in the gaps in the provided range of addresses.
abstract 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.
abstract 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.
abstract 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.
abstract SortedMap<K, V> getOverlappingSegmentsMap(K begin, boolean includeFirstPartialSegment, K end, boolean includeLastPartialSegment)
Get all segments partially or fully present in the given range.
abstract V getSegmentAfter(K key)
Get the closest segment after the provided address, which does not contain it.
abstract V getSegmentBefore(K key)
Get the closest segment before the provided address, which does not contain it.
abstract V getSegmentContaining(K key)
Get the segment containing the provided address.
abstract boolean isEmptyRange(K begin, K end)
Determine is the provided range is unencumbered.
abstract V put(K key, V segment)
Add a segment to the map.
abstract void putAll(Map<? extends K, ? extends V> m)
Add multiple segments to the map.
[Expand]
Inherited Methods
From interface java.util.Map
From interface java.util.NavigableMap
From interface java.util.SortedMap

Public Methods

public abstract V add (V segment)

Add a segment to the map. Convenience method, similar to put.

Parameters
segment value to add
Returns
  • the added value

public abstract 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())
            

public abstract 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

public abstract 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

public abstract 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

public abstract 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
verifier optional verifier to customize the generated list
Returns
  • a list of [begin, end) keys representing the gap segments

public abstract 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.

Returns
  • a list of [begin, end) keys representing the gap segments

public abstract 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.

Returns
  • a map

public abstract 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)

public abstract 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

public abstract 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)

public abstract boolean isEmptyRange (K begin, K end)

Determine is the provided range is unencumbered.

Parameters
begin inclusive start address
end exclusive end address

public abstract 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)

public abstract void putAll (Map<? extends K, ? extends V> m)

Add multiple segments to the map.