**insert** -fgl

Inserts a key/value mapping into the hash table.
Note that insert doesn't remove the old entry from the table - the behaviour is like an association list, the most-recently-inserted mapping for a key in the table. The reason for this is to keep insert as efficient as possible. If you need to update a mapping, then we provide update.
The insert function takes an element and a list and inserts the element into the list at the last position or equal to the next element. In particular, if the list is sorted before the call, the result will also be sorted. It is a special case of insertBy, which allows the programmer to supply their own comparison function.
*O(min(n,W))*. Add a value to the set. There is no left- or right bias for IntSets.

*O(min(n,W))*. Insert a new key/value pair in the map. If the key is already present in the map, the associated value is replaced with the supplied value, i.e. insert is equivalent to insertWith const.
> insert 5 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'x')]
> insert 7 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'a'), (7, 'x')]
> insert 5 'x' empty == singleton 5 'x'
*O(log n)*. Insert an element in a set. If the set already contains an element equal to the given value, it is replaced with the new value.

*O(log n)*. Insert a new key and value in the map. If the key is already present in the map, the associated value is replaced with the supplied value. insert is equivalent to insertWith const.
> insert 5 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'x')]
> insert 7 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'a'), (7, 'x')]
> insert 5 'x' empty == singleton 5 'x'
The non-overloaded version of insert.
insertHeader hdr val x inserts a header with the given header name and value. Does not check for existing headers with same name, allowing duplicates to be introduce (use replaceHeader if you want to avoid this.)
insertHeaderIfMissing hdr val x adds the new header only if no previous header with name hdr exists in x.

insertHeaders hdrs x appends multiple headers to x's existing set.

*O(min(n,W))*. The expression (insertLookupWithKey f k x map) is a pair (lookup k map) and the second element equal to (insertWithKey f k x map).
> let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
> insertLookupWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "5:xxx|a")])
> insertLookupWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == (Nothing, fromList [(3, "b"), (5, "a"), (7, "xxx")])
> insertLookupWithKey f 5 "xxx" empty == (Nothing, singleton 5 "xxx")
This is how to define insertLookup using insertLookupWithKey:
> let insertLookup kx x t = insertLookupWithKey (\_ a _ -> a) kx x t
> insertLookup 5 "x" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "x")])
> insertLookup 7 "x" (fromList [(5,"a"), (3,"b")]) == (Nothing, fromList [(3, "b"), (5, "a"), (7, "x")])
*O(log n)*. Combines insert operation with old value retrieval. The expression (insertLookupWithKey f k x map) is a pair map</tt>) and the second element equal to (insertWithKey f k x map).
> let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
> insertLookupWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "5:xxx|a")])
> insertLookupWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == (Nothing, fromList [(3, "b"), (5, "a"), (7, "xxx")])
> insertLookupWithKey f 5 "xxx" empty == (Nothing, singleton 5 "xxx")
This is how to define insertLookup using insertLookupWithKey:
> let insertLookup kx x t = insertLookupWithKey (\_ a _ -> a) kx x t
> insertLookup 5 "x" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "x")])
> insertLookup 7 "x" (fromList [(5,"a"), (3,"b")]) == (Nothing, fromList [(3, "b"), (5, "a"), (7, "x")])
*O(min(n,W))*. Insert with a combining function. insertWith f key value mp will insert the pair (key, value) into mp if key does not exist in the map. If the key does exist, the function will insert f new_value old_value.
> insertWith (++) 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "xxxa")]
> insertWith (++) 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")]
> insertWith (++) 5 "xxx" empty == singleton 5 "xxx"
*O(log n)*. Insert with a function, combining new value and old value. insertWith f key value mp will insert the pair (key, value) into mp if key does not exist in the map. If the key does exist, the function will insert the pair (key, f new_value old_value).
> insertWith (++) 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "xxxa")]
> insertWith (++) 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")]
> insertWith (++) 5 "xxx" empty == singleton 5 "xxx"
*Deprecated.* As of version 0.5, replaced by insertWith.
*O(log n)*. Same as insertWith, but the result of the combining function is evaluated to WHNF before inserted to the map.
*Deprecated.* As of version 0.5, replaced by insertWith.
*O(log n)*. Same as insertWith, but the value being inserted to the map is evaluated to WHNF beforehand.
For example, to update a counter:
> insertWith' (+) k 1 m
*O(min(n,W))*. Insert with a combining function. insertWithKey f key value mp will insert the pair (key, value) into mp if key does not exist in the map. If the key does exist, the function will insert f key new_value old_value.
> let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
> insertWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:xxx|a")]
> insertWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")]
> insertWithKey f 5 "xxx" empty == singleton 5 "xxx"
*O(min(n,W))*. Insert with a combining function. insertWithKey f key value mp will insert the pair (key, value) into mp if key does not exist in the map. If the key does exist, the function will insert f key new_value old_value.
> let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
> insertWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:xxx|a")]
> insertWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")]
> insertWithKey f 5 "xxx" empty == singleton 5 "xxx"
If the key exists in the map, this function is lazy in x but strict in the result of f.
*O(log n)*. Insert with a function, combining key, new value and old value. insertWithKey f key value mp will insert the pair (key, value) into mp if key does not exist in the map. If the key does exist, the function will insert the pair (key,f key new_value old_value). Note that the key passed to f is the same key passed to insertWithKey.
> let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
> insertWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:xxx|a")]
> insertWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")]
> insertWithKey f 5 "xxx" empty == singleton 5 "xxx"
*Deprecated.* As of version 0.5, replaced by insertWithKey.
*O(log n)*. Same as insertWithKey, but the result of the combining function is evaluated to WHNF before inserted to the map.
*Deprecated.* As of version 0.5, replaced by insertWithKey.
*O(log n)*. Same as insertWithKey, but the value being inserted to the map is evaluated to WHNF beforehand.
Construct a Builder that always inserts the strict ByteString directly as a chunk.
This implies flushing the output buffer, even if it contains just a single byte. You should therefore use byteStringInsert only for large (> 8kb) ByteStrings. Otherwise, the generated chunks are too fragmented to be processed efficiently afterwards.