# Class: com.pnfsoftware.jeb.util.collect.SegmentMap

Standard implementation of a segment\-map using a [TreeMap](TreeMap) as the underlying data structure. Supports auto\-removal of values when inserting a new segment overlaps existing segments. 

 Thread safety: support for partial concurrency: multiple reader threads with a single writer thread is okay. However, if multiple threads are attempting to modify this object, external synchronization is required. \(This is the reason why this class name is not prefixed by 'Concurrent'\).

## Constructor: SegmentMap

Description: Create a segment\-map that uses natural comparison for the keys.

## Constructor: SegmentMap
- parameter: `o`, type: `com.pnfsoftware.jeb.util.collect.SegmentMap<K,V>`

Description: Copy\-constructor.
parameter: o: source map

## Protected Constructor: SegmentMap
- parameter: `comparator`, type: `java.util.Comparator<? super K>`

Description: Create a segment\-map using the provided key comparator.
parameter: comparator: a custom comparator for the keys

## Method: add
- parameter: `v`, type: `V`
- return type: `V`


## 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`


## Method: compareKeys
- parameter: `a`, type: `K`
- parameter: `b`, type: `K`
- return type: `int`

Description: Compare two keys using the map's **actual** comparator.
parameter: a: first key
parameter: b: second key
return: comparison result

## 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>`


## Method: equals
- parameter: `obj`, type: `java.lang.Object`
- return type: `boolean`


## 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>`


## 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>`


## 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>>`


## 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>>`


## 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>`


## 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>`


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


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


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


## Method: hashCode
- return type: `int`


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


## Method: isRemoveSegmentsOnOverlap
- return type: `boolean`

Description: Get the map behavior when the insertion of a segment would overlap existing segments.
return: true if overlapping segments are removed before insertion

## Method: isValidKey
- parameter: `k`, type: `K`
- return type: `boolean`

Description: Validate whether or not the provided key is valid. The default implementation simply returns true: all objects of type K are valid keys, as would be expected by an implementation of [Map](Map). 

 This method is called when attempting to insert an entry into a map \(using [add](#add(ISegment)), [put](#put(Comparable, ISegment)), or [putall](#putAll(Map))\).
parameter: k: a key
return: true or false

## Method: isValidSegment
- parameter: `v`, type: `V`
- return type: `boolean`

Description: Validate whether or not the provided key is valid. The default implementation verifies that the segment's begin value is strictly less than the segment's end value. 

 This method is called when attempting to insert an entry into a map \(using [add](#add(ISegment)), [put](#put(Comparable, ISegment)), or [putall](#putAll(Map))\).
parameter: v: a segment
return: true if the segment is valid

## Method: put
- parameter: `k`, type: `K`
- parameter: `v`, type: `V`
- return type: `V`


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


## Method: setRemoveSegmentsOnOverlap
- parameter: `removeSegmentsOnOverlap`, type: `boolean`

Description: Set the map behavior when the insertion of a segment would overlap existing segments.
parameter: removeSegmentsOnOverlap: true to remove overlapping segments before insertion

## Method: subMap
- parameter: `fromKey`, type: `K`
- parameter: `fromInclusive`, type: `boolean`
- parameter: `toKey`, type: `K`
- parameter: `toInclusive`, type: `boolean`
- return type: `java.util.concurrent.ConcurrentNavigableMap<K,V>`


## Method: toString
- return type: `java.lang.String`