# Interface: com.pnfsoftware.jeb.util.collect.ISegmentMap

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: add
- parameter: `segment`, type: `V`
- return type: `V`

Description: Add a segment to the map. Convenience method, similar to [put](#put(Comparable, ISegment)).
parameter: segment: value to add
return: the added value

## Method: addAndMerge
- parameter: `v`, type: `V`
- parameter: `mf`, type: `java.util.function.BiFunction<com.pnfsoftware.jeb.util.base.Couple<K,K>,java.util.List<V>,V>`
- return type: `V`

Description: Adds a segment to the map and merge all the values within the overlap. If no overlap, this method just calls [#add(ISegment)](#add(ISegment)).
parameter: v: value to add
parameter: mf: the merge function: the first parameter is a [Couple](Couple) \(begin, end\) of the new            merged segment; the 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](IntegerSegment)(c.getFirst(), c.getSecond() - c.getFirst())
 
```
return: merged segment

## Method: contiguousSubMap
- parameter: `begin`, type: `K`
- parameter: `end`, type: `K`
- parameter: `factory`, type: `com.pnfsoftware.jeb.util.collect.ISegmentFactory<K,V>`
- return type: `java.util.SortedMap<K,V>`

Description: Get a map containing all the segments in the ranges, without any gap. Unlike [subMap](#subMap(Object, Object)), 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.
parameter: 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.
parameter: end: end address end address, exclusive
parameter: factory: a factory used to generate gap items
return: map containing real and generated gap segments

## Method: fillGaps
- parameter: `begin`, type: `K`
- parameter: `end`, type: `K`
- parameter: `factory`, type: `com.pnfsoftware.jeb.util.collect.ISegmentFactory<K,V>`
- return type: `java.util.List<V>`

Description: Create segments to fill in the gaps in the provided range of addresses. Trailer and header gaps will be created if need be.
parameter: begin: begin address
parameter: end: end address
parameter: factory: a factory object used to create segments
return: the list of segments that were created

## Method: generateGapItems
- parameter: `begin`, type: `K`
- parameter: `allowHeader`, type: `boolean`
- parameter: `end`, type: `K`
- parameter: `allowTrailer`, type: `boolean`
- parameter: `factory`, type: `com.pnfsoftware.jeb.util.collect.ISegmentFactory<K,V>`
- parameter: `addItemsToMap`, type: `boolean`
- return type: `java.util.List<V>`

Description: Create segments to fill in the gaps in the provided range of addresses.
parameter: begin: begin address
parameter: allowHeader: determine if an unbounded gap header can be filled
parameter: end: end address
parameter: allowTrailer: determine if an unbounded gap trailer can be filled
parameter: factory: a factory object used to create segments
parameter: addItemsToMap: if true, the items created to fill in the gaps in the segment map are            also added to the segment map
return: the list of segments that were created

## Method: generateGaps
- parameter: `begin`, type: `K`
- parameter: `allowHeader`, type: `boolean`
- parameter: `end`, type: `K`
- parameter: `allowTrailer`, type: `boolean`
- parameter: `verifier`, type: `com.pnfsoftware.jeb.util.collect.ISegmentGapVerifier<K>`
- return type: `java.util.List<com.pnfsoftware.jeb.util.base.Couple<K,K>>`

Description: Generate a list of segments that correspond to the ordered gaps list of this map.
parameter: begin: range start
parameter: allowHeader: true to include a gap before the first segment
parameter: end: range end
parameter: allowTrailer: true to include a gap after the last segment
parameter: verifier: optional verifier to customize the generated list
return: a list of \[begin, end\) keys representing the gap segments

## Method: generateGaps
- parameter: `begin`, type: `K`
- parameter: `allowHeader`, type: `boolean`
- parameter: `end`, type: `K`
- parameter: `allowTrailer`, type: `boolean`
- return type: `java.util.List<com.pnfsoftware.jeb.util.base.Couple<K,K>>`

Description: Generate a list of segments that correspond to the ordered gaps list of this map.
parameter: begin: range start
parameter: allowHeader: true to include a gap before the first segment
parameter: end: range end
parameter: allowTrailer: true to include a gap after the last segment
return: a list of \[begin, end\) keys representing the gap segments

## Method: getOverlappingSegmentsMap
- parameter: `begin`, type: `K`
- parameter: `includeFirstPartialSegment`, type: `boolean`
- parameter: `end`, type: `K`
- parameter: `includeLastPartialSegment`, type: `boolean`
- return type: `java.util.SortedMap<K,V>`

Description: 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.
parameter: begin: inclusive range start
parameter: includeFirstPartialSegment: true to include a segment containing `begin`
parameter: end: exclusive range end
parameter: includeLastPartialSegment: true to include a segment extending past `end`
return: map of overlapping segments

## Method: getOverlappingSegmentsMap
- parameter: `begin`, type: `K`
- parameter: `includeFirstPartialSegment`, type: `boolean`
- parameter: `end`, type: `K`
- parameter: `includeLastPartialSegment`, type: `boolean`
- parameter: `predicate`, type: `java.util.function.Predicate<? super java.util.Map.Entry<K,V>>`
- return type: `java.util.SortedMap<K,V>`

Description: 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.
parameter: begin: inclusive range start
parameter: includeFirstPartialSegment: true to include a segment containing `begin`
parameter: end: exclusive range end
parameter: includeLastPartialSegment: true to include a segment extending past `end`
parameter: predicate: [Predicate](Predicate) to filter the returned values.
return: a map

## Method: getSegmentAfter
- parameter: `key`, type: `K`
- return type: `V`

Description: Get the closest segment after the provided address, which does not contain it.
parameter: key: address to probe
return: the next segment, null if none \(final gap\)

## Method: getSegmentBefore
- parameter: `key`, type: `K`
- return type: `V`

Description: Get the closest segment before the provided address, which does not contain it.
parameter: key: address to probe
return: the previous segment, null if none

## Method: getSegmentContaining
- parameter: `key`, type: `K`
- return type: `V`

Description: Get the segment containing the provided address.
parameter: key: address to probe
return: the containing segment, null if none \(it is a gap\)

## Method: isEmptyRange
- parameter: `begin`, type: `K`
- parameter: `end`, type: `K`
- return type: `boolean`

Description: Determine if the provided range is unencumbered.
parameter: begin: inclusive start address
parameter: end: exclusive end address
return: true if no segment overlaps the range

## Method: put
- parameter: `key`, type: `K`
- parameter: `segment`, type: `V`
- return type: `V`

Description: Add a segment to the map. This method throws [IllegalArgumentException](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\)

## Method: putAll
- parameter: `m`, type: `java.util.Map<? extends K,? extends V>`

Description: Add multiple segments to the map.

