CaseInsensitiveMap<V> class

A map that performs case-insensitive string key lookups while preserving the original casing of keys.

This map implements Map<String, V> and ensures that all key lookups, insertions, updates, and removals are case-insensitive. The original casing of a key is preserved for iteration, keys, and entries.

Rules

• Lookup keys are compared case-insensitively.
  e.g., 'Content-Type', 'content-type', 'CONTENT-TYPE' all match the same entry.
• When inserting a key that differs only in case from an existing key, the old key is replaced, but the value remains the same.
• Null keys are not allowed because the map only supports String keys.
• Values may be null if the type V allows it.

Examples

final map = CaseInsensitiveMap<String>();
map['Content-Type'] = 'application/json';
print(map['content-type']); // 'application/json'
print(map['CONTENT-TYPE']); // 'application/json'

// Updating a key with different casing replaces the original key
map['content-type'] = 'text/html';
print(map['Content-Type']); // 'text/html'

Edge Cases

Operation	Key	Value	Result
Insert	'Token'	'abc'	Stored as 'Token'
Lookup	'token'	-	Returns 'abc'
Update	'TOKEN'	'xyz'	Replaces 'Token', value now 'xyz'
Remove	'tOkEn'	-	Key removed

Design Notes

• Uses a private map _map for storing keys with original casing and values.
• The _findOriginalKey method performs case-insensitive comparison for lookups.
• Fully compatible with standard Dart Map<String, V> APIs (e.g., addAll, update, removeWhere).
• Efficient for typical usage, but very large maps may have performance implications because _findOriginalKey iterates over all keys linearly.

See Also

• Map — base interface implemented
• HashMap — standard Dart hash-based map

Implemented types

• Map<String, V>

Annotations

• @Generic(CaseInsensitiveMap)

Constructors

CaseInsensitiveMap()

A map that performs case-insensitive string key lookups while preserving the original casing of keys.

CaseInsensitiveMap.from(Map<String, V> other)

Creates a CaseInsensitiveMap containing all key-value pairs from other.

factory

CaseInsensitiveMap.fromEntries(Iterable<MapEntry<String, V>> entries)

Creates a CaseInsensitiveMap from the entries of entries.

factory

CaseInsensitiveMap.fromIterable(Iterable iterable, {String key(dynamic element)?, V value(dynamic element)?})

Creates a CaseInsensitiveMap from another map where the keys and values are computed from other's keys and values.

factory

Properties

entries → Iterable<MapEntry<String, V>>

The map entries of this Map.

no setter, override

hashCode → int

The hash code for this object.

no setter, inherited

isEmpty → bool

Whether there is no key/value pair in the map.

no setter, override

isNotEmpty → bool

Whether there is at least one key/value pair in the map.

no setter, override

keys → Iterable<String>

The keys of this Map.

no setter, override

length → int

The number of key/value pairs in the map.

no setter, override

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

values → Iterable<V>

The values of this Map.

no setter, override

Methods

addAll(Map<String, V> other) → void

Adds all key/value pairs of other to this map.

override

addEntries(Iterable<MapEntry<String, V>> newEntries) → void

Adds all key/value pairs of newEntries to this map.

override

cast<RK, RV>() → Map<RK, RV>

Provides a view of this map as having RK keys and RV instances, if necessary.

override

clear() → void

Removes all entries from the map.

override

containsKey(Object? key) → bool

Whether this map contains the given key.

override

containsValue(Object? value) → bool

Whether this map contains the given value.

override

forEach(void action(String key, V value)) → void

Applies action to each key/value pair of the map.

override

map<K2, V2>(MapEntry<K2, V2> convert(String key, V value)) → Map<K2, V2>

Returns a new map where all entries of this map are transformed by the given convert function.

override

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

putIfAbsent(String key, V ifAbsent()) → V

Look up the value of key, or add a new entry if it isn't there.

override

remove(Object? key) → V?

Removes key and its associated value, if present, from the map.

override

removeWhere(bool test(String key, V value)) → void

Removes all entries of this map that satisfy the given test.

override

toString() → String

A string representation of this object.

override

update(String key, V update(V value), {V ifAbsent()?}) → V

Updates the value for the provided key.

override

updateAll(V update(String key, V value)) → void

Updates all values.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited

operator [](Object? key) → V?

The value for the given key, or null if key is not in the map.

override

operator []=(String key, V value) → void

Associates the key with the given value.

override