# 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,java.util.List,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` - return type: `java.util.SortedMap` 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` - return type: `java.util.List` 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` - parameter: `addItemsToMap`, type: `boolean` - return type: `java.util.List` 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` - return type: `java.util.List>` 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>` 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` 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>` - return type: `java.util.SortedMap` 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` Description: Add multiple segments to the map.