CanonicalizedMap: new copy, toMap and toMapOfCanonicalKeys methods

[gmpassos]

• copy: copies a CanonicalizedMap instance without recalculating the canonical values of the keys.
• toMap: creates a Map<K,V> (with the original key values).
• toMapOfCanonicalKeys: creates a Map<C,V> (with the canocalized keys).

[natebosch]

These APIs look relatively straightforward and I don't have concerns about adding them.

For clarity, @gmpassos - could you describe the use case you have in mind for these?

cc @lrhn

[lrhn]

I'm always a little worried when adding methods to an implementation of a standard interface like Map.
In this case, the methods are related to the implementation strategy, so it makes sense.

It's also reasonable functions.

So thanks for the contribution! Can you update the changelog and the pubspec version as per https://github.com/dart-lang/.github/blob/main/PULL_REQUEST_TEMPLATE.md ?

It should just be a minor version increment, and a changelog entry for that version saying which methods are added.

[gmpassos]

These APIs look relatively straightforward and I don't have concerns about adding them.

For clarity, @gmpassos - could you describe the use case you have in mind for these?

cc @lrhn

Currently the most common use case is:
https://github.com/dart-lang/http_parser/blob/master/lib/src/case_insensitive_map.dart

It's all about performance. If you use any Map based on CanonicalizedMap and require a copy of it (which is a common operation), you may encounter a bottleneck due to the recalculation of the canonical keys.

It is also important to have methods for transforming it into a regular Map (toMap and toMapOfCanonicalKeys), in case you want to eliminate the overhead associated with the canonical function.

Best regards

[gmpassos]

It should just be a minor version increment, and a changelog entry for that version saying which methods are added.

Done 👍