1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2021</year><year>2023</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>Maps</title>
<prepared>Bjorn Gustavsson</prepared>
<docno></docno>
<date>2021-07-01</date>
<rev></rev>
<file>maps.xml</file>
</header>
<p>This guide to using maps efficiently starts with a brief section
on the choice between records or maps, followed by three sections
giving concrete (but brief) advice on using maps as an alternative to
records, as dictionaries, and as sets. The remaining sections dig
deeper, looking at how maps are implemented, the map syntax, and
finally the functions in the <seeerl
marker="stdlib:maps">maps</seeerl> module.</p>
<marker id="terminology"/>
<p>Terminology used in this chapter:</p>
<list type="bulleted">
<item>A map with at most 32 elements will informally be called a
<em>small map</em>.</item>
<item>A map with more than 32 elements will informally be called a
<em>large map</em>.</item>
</list>
<section>
<title>Maps or Records?</title>
<p>If the advice in this chapter is followed, the performance of
records compared to using small maps instead of records is
expected to be similar. Therefore, the choice between records and
maps should be based on the desired properties of the data
structure and not performance.</p>
<p>The advantages of records compared to maps are:</p>
<list type="bulleted">
<item>If the name of a record field is misspelled, there will be
a compilation error. If a map key is misspelled, the compiler
will give no warning and program will fail in some way when it
is run.</item>
<item>Records will use slightly less memory than maps, and
performance is expected to be <em>slightly</em> better than maps
in most circumstances.</item>
</list>
<p>The disadvantage of records compared to maps is that if a new
field is added to a record, all code that uses that record must be
recompiled. Because of that, it is recommended to only use records
within a unit of code that can easily be recompiled all at once, for
example within a single application or single module.</p>
</section>
<section>
<title>Using Maps as an Alternative to Records</title>
<list type="bulleted">
<item><p>Use the map syntax instead of the functions in
the <seeerl marker="stdlib:maps">maps</seeerl> module.</p></item>
<item><p>Avoid having more than 32 elements in the
map. As soon as there are more than 32 elements in the map,
it will require more memory and keys can no longer be shared
with other instances of the map.</p></item>
<item><p>When creating a new map, always create it with all keys
that will ever be used. To maximize sharing of keys (thus
minimizing memory use), create a single function that constructs
the map using the map syntax and always use it.</p></item>
<item><p>Always update the map using the
<c>:=</c> operator (that is, requiring that an element with
that key already exists). The <c>:=</c> operator is slightly
more efficient, and it helps catching mispellings of
keys.</p></item>
<item><p>Whenever possible, match multiple map elements at
once.</p></item>
<item><p>Whenever possible, update multiple map elements at
once.</p></item>
<item><p>Avoid default values and the <seemfa
marker="stdlib:maps#get/3">maps:get/3</seemfa> function. If
there are default values, sharing of keys between different
instances of the map will be less effective, and it is not
possible to match multiple elements having default values in one
go.</p></item>
<item><p>To avoid having to deal with a map that may lack some keys,
<seemfa marker="stdlib:maps#merge/2">maps:merge/2</seemfa>
can efficiently add multiple default values. For example:</p>
<code type="erl"><![CDATA[
DefaultMap = #{shoe_size => 42, editor => emacs},
MapWithDefaultsApplied = maps:merge(DefaultMap, OtherMap)]]></code>
</item>
</list>
</section>
<section>
<title>Using Maps as Dictionaries</title>
<p>Using a map as a dictionary implies the following usage pattern:</p>
<list type="bulleted">
<item><p>Keys are usually variables not known at compile-time.</p></item>
<item><p>There can be any number of elements in the map.</p></item>
<item><p>Usually, no more than one element is looked up or
updated at once.</p></item>
</list>
<p>Given that usage pattern, the difference in performance between
using the map syntax and the maps module is usually
small. Therefore, which one to use is mostly a matter of
taste.</p>
<p>Maps are usually the most efficient dictionary data structure,
with a few exceptions:</p>
<list type="bulleted">
<item><p>If it is necessary to frequently convert a
dictionary to a sorted list, or from a sorted list to a
dictionary, using <seeerl marker="stdlib:gb_trees">gb_trees</seeerl>
can be a better choice.</p></item>
<item><p>If all keys are non-negative integers, the <seeerl
marker="stdlib:array">array</seeerl> module can be a better
choice.</p></item>
</list>
</section>
<section>
<title>Using Maps as Sets</title>
<p>Starting in OTP 24, the <seeerl marker="stdlib:sets">sets</seeerl> module
has an option to represent sets as maps. Examples:</p>
<code type="erl"><![CDATA[
1> sets:new([{version,2}]).
#{}
2> sets:from_list([x,y,z], [{version,2}]).
#{x => [],y => [],z => []}]]></code>
<p><c>sets</c> backed by maps is generally the most efficient set
representation, with a few possible exceptions:</p>
<list type="bulleted">
<item><p><seemfa
marker="stdlib:ordsets#intersection/2">ordsets:intersection/2</seemfa>
can be more efficient than <seemfa
marker="stdlib:sets#intersection/2">sets:intersection/2</seemfa>.
If the intersection operation is frequently used and operations
that operate on a single element in a set (such as
<c>is_element/2</c>) are avoided, <seeerl
marker="stdlib:ordsets">ordsets</seeerl> can be a better
choice than <seeerl marker="stdlib:sets">sets</seeerl>.</p></item>
<item><p>If the intersection operation is frequently used and operations
that operate on a single element in a set (such as
<c>is_element/2</c>) must also be efficient, <seeerl
marker="stdlib:gb_sets">gb_sets</seeerl> can potentially be a
better choice than <seeerl marker="stdlib:sets">sets</seeerl>.</p></item>
<item><p>If the elements of the set are integers in a fairly
compact range, the set can be represented as an integer where
each bit represents an element in the set. The union operation
is performed by <c>bor</c> and the intersection operation by
<c>band</c>.</p></item>
</list>
</section>
<section>
<title>How Maps are Implemented</title>
<p>Internally, maps have two distinct representations depending on
the number of elements in the map. The representation changes
when a map grows beyond 32 elements, or when it shrinks to 32
elements or less.</p>
<list type="bulleted">
<item>A map with at most 32 elements has a compact
representation, making it suitable as an alternative to
records.</item>
<item>A map with more than 32 elements is represented as a tree
that can be efficiently searched and updated regardless of how
many elements there are.</item>
</list>
<section>
<title>How Small Maps are Implemented</title>
<p>A small map looks like this inside the runtime system:</p>
<table align="left">
<row>
<cell align="center"><c>FLATMAP</c></cell>
<cell align="center"><em>N</em></cell>
<cell align="center"><em>Keys</em></cell>
<cell align="center"><em>Value1</em></cell>
<cell align="center"><em>. . .</em></cell>
<cell align="center"><em>ValueN</em></cell>
</row>
<tcaption>The representation of a small map</tcaption>
</table>
<taglist>
<tag><c>FLATMAP</c></tag>
<item>The tag for a small map (called <em>flat map</em> in
the source code for the runtime system).</item>
<tag>N</tag>
<item>The number of elements in the map.</item>
<tag>Keys</tag>
<item>A tuple with keys of the map: <c>{Key1,...,KeyN}</c>. The
keys are sorted.</item>
<tag>Value1</tag>
<item>The value corresponding to the first key in the key tuple.</item>
<tag>ValueN</tag>
<item>The value corresponding to the last key in the key tuple.</item>
</taglist>
<p>As an example, let us look at how the map <c>#{a => foo, z => bar}</c>
is represented:</p>
<table align="left">
<row>
<cell align="center"><c>FLATMAP</c></cell>
<cell align="center"><em>2</em></cell>
<cell align="center"><em>{a,z}</em></cell>
<cell align="center"><em>foo</em></cell>
<cell align="center"><em>bar</em></cell>
</row>
<tcaption>#{a => foo, z => bar}</tcaption>
</table>
<p>Let us update the map: <c>M#{q => baz}</c>. The map now looks
like this:</p>
<table align="left">
<row>
<cell align="center"><c>FLATMAP</c></cell>
<cell align="center"><em>3</em></cell>
<cell align="center"><em>{a,q,z}</em></cell>
<cell align="center"><em>foo</em></cell>
<cell align="center"><em>baz</em></cell>
<cell align="center"><em>bar</em></cell>
</row>
<tcaption>#{a => foo, q => baz, z => bar}</tcaption>
</table>
<p>Finally, change the value of one element: <c>M#{z :=
bird}</c>. The map now looks like this:</p>
<table align="left">
<row>
<cell align="center"><c>FLATMAP</c></cell>
<cell align="center"><em>3</em></cell>
<cell align="center"><em>{a,q,z}</em></cell>
<cell align="center"><em>foo</em></cell>
<cell align="center"><em>baz</em></cell>
<cell align="center"><em>bird</em></cell>
</row>
<tcaption>#{a => foo, q => baz, z => bird}</tcaption>
</table>
<p>When the value for an existing key is updated, the key tuple is not
updated, allowing the key tuple to be shared with other instances of the
map that have the same keys. In fact, the key tuple can be shared between all
maps with the same keys with some care. To arrange that, define a function that
returns a map. For example:</p>
<code type="erl"><![CDATA[
new() ->
#{a => default, b => default, c => default}.]]></code>
<p>Defined like this, the key tuple <c>{a,b,c}</c> will be a
global literal. To ensure that the key tuple is shared
when creating an instance of the map, always call
<c>new()</c> and modify the returned map:</p>
<code type="erl"><![CDATA[
(SOME_MODULE:new())#{a := 42}.]]></code>
<p>Using the map syntax with small maps is particularly
efficient. As long as the keys are known at compile-time, the
map is updated in one go, making the time to update a map
essentially constant regardless of the number of keys
updated. The same goes for matching. (When the keys are
variables, one or more of the keys could be identical, so the
operations need to be performed sequentially from left to
right.)</p>
<p>The memory size for a small map is the size of all keys and values
plus 5 words. See <seeguide marker="advanced#memory">Advanced</seeguide>
for more information about memory sizes.</p>
</section>
<section>
<title>How Large Maps are Implemented</title>
<p>A map with more than 32 elements is implemented as a <url
href="https://en.wikipedia.org/wiki/Hash_array_mapped_trie">Hash
array mapped trie (HAMT)</url>. A large map can be efficiently
searched and updated regardless of the number of elements in the
map.</p>
<p>There is less performance to be gained by matching or
updating multiple elements using the map syntax on a large map
compared to a small map. The execution time is roughly proportional
to the number of elements matched or updated.</p>
<p>The storage overhead for a large map is higher than for a
small map. For a large map, the extra number of words besides
the keys and values is roughly proportional to the number of
elements. For a map with 33 elements the overhead is at
least 53 heap words according to the formula in <seeguide
marker="advanced#memory">Advanced</seeguide> (compared to 5
extra words for a small map regardless of the number of
elements).</p>
<p>When a large map is updated, the updated map and the original
map will share common parts of the HAMT, but sharing will never
be as effective as the best possible sharing of the key tuple
for small maps.</p>
<p>Therefore, if maps are used instead of records and it is
expected that many instances of the map will be created, it is
more efficient from a memory standpoint to avoid using large
maps (for example, by grouping related map elements into sub
maps to reduce the number of elements).</p>
</section>
</section>
<section>
<title>Using the Map Syntax</title>
<p>Using the map syntax is usually slightly more efficient than
using the corresponding function in the <seeerl
marker="stdlib:maps">maps</seeerl> module.</p>
<p>The gain in efficiency for the map syntax is more noticeable
for the following operations that can only be achieved using the
map syntax:</p>
<list type="bulleted">
<item><p>Matching multiple literal keys</p></item>
<item><p>Updating multiple literal keys</p></item>
<item><p>Adding multiple literal keys to a map</p></item>
</list>
<p>For example:</p>
<p><em>DO</em></p>
<code type="erl"><![CDATA[
Map = Map1#{x := X, y := Y, z := Z}]]></code>
<p><em>DO NOT</em></p>
<code type="erl"><![CDATA[
Map2 = maps:update(x, X, Map1),
Map3 = maps:update(y, Y, Map2),
Map = maps:update(z, Z, Map3)]]></code>
<p>If the map is a small map, the first example runs roughly
three times as fast.</p>
<p>Note that for variable keys, the elements are updated
sequentially from left to right. For example, given the following
update with variable keys:</p>
<code type="erl"><![CDATA[
Map = Map1#{Key1 := X, Key2 := Y, Key3 := Z}]]></code>
<p>the compiler rewrites it like this to ensure that the updates
are applied from left to right:</p>
<code type="erl"><![CDATA[
Map2 = Map1#{Key1 := X},
Map3 = Map2#{Key2 := Y},
Map = Map3#{Key3 := Z}]]></code>
<p>If a key is known to exist in a map, using the <c>:=</c>
operator is slightly more efficient than using the <c>=></c>
operator for a small map.</p>
</section>
<section>
<title>Using the Functions in the maps Module</title>
<p>Here follows some notes about most of the functions in the
<c>maps</c> module. For each function, the implementation language
(C or Erlang) is stated. The reason we mention the language is
that it gives an hint about how efficient the function is:</p>
<list type="bulleted">
<item><p>If a function is implemented in C, it is pretty much
impossible to implement the same functionality more efficiently
in Erlang.</p></item>
<item><p>However, it might be possible to beat the <c>maps</c>
modules functions implemented in Erlang, because they are
generally implemented in a way that attempts to make the performance
reasonable for all possible inputs.</p>
<p>For example, <seemfa
marker="stdlib:maps#map/2">maps:map/2</seemfa> iterates over
all elements of the map, calling the mapping fun, collects the
updated map elements in a list, and finally converts the list
back to a map using <seemfa
marker="stdlib:maps#from_list/1">maps:from_list/1</seemfa>. If
it is known that at most one percent of the values in the map
will change, it can be more efficient to update only the
changed values.</p></item>
</list>
<note><p>The implementation details given in this section can
change in the future.</p></note>
<section>
<title>maps:filter/2</title>
<p><seemfa marker="stdlib:maps#filter/2">maps:filter/2</seemfa>
is implemented in Erlang. It creates a new map using <seemfa
marker="stdlib:maps#from_list/1">maps:from_list/1</seemfa>. If
it is known that only a minority of the values will be removed,
it can be more efficient to avoid <c>maps:filter/2</c> and write
a function that will use <seemfa
marker="stdlib:maps#remove/2">maps:remove/3</seemfa> to remove
the unwanted values.</p>
</section>
<section>
<title>maps:filtermap/2</title>
<p><seemfa
marker="stdlib:maps#filtermap/2">maps:filtermap/2</seemfa> is
implemented in Erlang. It creates a new map using <seemfa
marker="stdlib:maps#from_list/1">maps:from_list/1</seemfa>. See
the notes for <c>maps:map/2</c> and <c>maps:filter/2</c> for
hints on how to implement a more efficient version.</p>
</section>
<section>
<title>maps:find/2</title>
<p><seemfa marker="stdlib:maps#find/2">maps:find/2</seemfa> is
implemented in C.</p>
<p>Using the map matching syntax instead of <c>maps:find/2</c>
will be slightly more efficient since building an
<c>{ok,Value}</c> tuple will be avoided.</p>
</section>
<section>
<title>maps:get/2</title>
<p>As an optimization, the compiler will rewrite a call to <seemfa
marker="stdlib:maps#get/2">maps:get/2</seemfa> to a call to the
guard BIF <seemfa
marker="erts:erlang#map_get/2">map_get/2</seemfa>. A call to a
guard BIF is more efficient than calls to other BIFs, making the
performance similar to using the map matching syntax.</p>
<p>If the map is small and the keys are constants known at
compile-time, using the map matching syntax will be more
efficient than multiple calls to <c>maps:get/2</c>.</p>
</section>
<section>
<marker id="maps_get_3"/>
<title>maps:get/3</title>
<p>As an optimization, the compiler will rewrite a call to <seemfa
marker="stdlib:maps#get/3">maps:get/3</seemfa> to Erlang code similar to
the following:</p>
<code type="erl"><![CDATA[
Result = case Map of
#{Key := Value} -> Value;
#{} -> Default
end]]></code>
<p>This is reasonably efficient, but if a small map is used as an
alternative to using a record it is often better not to rely on default
values as it prevents sharing of keys, which may in the end use more
memory than what you save from not storing default values in the
map.</p>
<p>If default values are nevertheless required, instead of calling
<c>maps:get/3</c> multiple times, consider putting the default values
in a map and merging that map with the other map:</p>
<code type="erl"><![CDATA[
DefaultMap = #{Key1 => Value2, Key2 => Value2, ..., KeyN => ValueN},
MapWithDefaultsApplied = maps:merge(DefaultMap, OtherMap)]]></code>
<p>This helps share keys between the default map and the one you applied
defaults to, as long as the default map contains <em>all</em> the keys
that will ever be used and not just the ones with default values.
Whether this is faster than calling <c>maps:get/3</c> multiple times
depends on the size of the map and the number of default values.</p>
<change>
<p>
Before OTP @OTP-18502@ <c>maps:get/3</c> was implemented by calling
the function instead of rewriting it as an Erlang expression. It is
now slightly faster but can no longer be traced.
</p>
</change>
</section>
<section>
<title>maps:intersect/2, maps:intersect_with/3</title>
<p><seemfa marker="stdlib:maps#intersect/2">maps:intersect/2</seemfa> and
<seemfa marker="stdlib:maps#intersect_with/3">maps:intersect_with/3</seemfa>
are implemented in Erlang. They both create new maps using <seemfa
marker="stdlib:maps#from_list/1">maps:from_list/1</seemfa>.</p>
<note><p>A map is usually the most efficient way to implement a
set, but an exception is the intersection operation, where
<seemfa
marker="stdlib:ordsets#intersection/2">ordsets:intersection/2</seemfa>
used on <seeerl marker="stdlib:ordsets">ordsets</seeerl> can be more
efficient than <c>maps:intersect/2</c> on sets implemented as maps.</p></note>
</section>
<section>
<title>maps:from_list/1</title>
<p><seemfa marker="stdlib:maps#from_list/1">maps:from_list/1</seemfa> is
implemented in C.</p>
</section>
<section>
<title>maps:from_keys/2</title>
<p><seemfa marker="stdlib:maps#from_keys/2">maps:from_keys/2</seemfa> is
implemented in C.</p>
</section>
<section>
<title>maps:is_key/2</title>
<p>As an optimization, the compiler rewrites calls to <seemfa
marker="stdlib:maps#is_key/2">maps:is_key/2</seemfa> to calls
to the guard BIF <seemfa
marker="erts:erlang#is_map_key/2">is_map_key/2</seemfa>. A call
to a guard BIF is more efficient than calls to other BIFs,
making the performance similar to using the map matching syntax.</p>
</section>
<section>
<title>maps:iterator/1</title>
<p><seemfa marker="stdlib:maps#iterator/1">maps:iterator/1</seemfa>
is efficiently implemented in C and Erlang.</p>
</section>
<section>
<title>maps:keys/1</title>
<p><seemfa marker="stdlib:maps#keys/1">maps:keys/1</seemfa> is
implemented in C. If the resulting list needs to be ordered, use
<seemfa marker="stdlib:lists#sort/1">lists:sort/1</seemfa> to
sort the result.</p>
</section>
<section>
<title>maps:map/2</title>
<p><seemfa marker="stdlib:maps#map/2">maps:map/2</seemfa> is
implemented in Erlang. It creates a new map using <seemfa
marker="stdlib:maps#from_list/1">maps:from_list/1</seemfa>. If
it is known that only a minority of the values will be updated,
it can be more efficient to avoid <c>maps:map/2</c> and write a
function that will call <seemfa
marker="stdlib:maps#update/3">maps:update/3</seemfa> to update
only the values that have changed.</p>
</section>
<section>
<title>maps:merge/2</title>
<p><seemfa marker="stdlib:maps#merge/2">maps:merge/2</seemfa>
is implemented in C. For <seeguide marker="#terminology">small
maps</seeguide>, the key tuple may be shared with any of the argument
maps if that argument map contains all the keys. Literal key tuples are
prefered if possible.</p>
<change>
<p>
The sharing of key tuples by <c>maps:merge/2</c> was introduced in
OTP @OTP-18523@. Older versions always contructed a new key tuple on
the callers heap.
</p>
</change>
</section>
<section>
<title>maps:merge_with/3</title>
<p><seemfa marker="stdlib:maps#merge_with/3">maps:merge_with/3</seemfa>
is implemented in Erlang. It updates and returns the larger of the
two maps.</p>
</section>
<section>
<title>maps:new/0</title>
<p>The compiler rewrites a call to <seemfa
marker="stdlib:maps#new/0">maps:new/0</seemfa> to using the
syntax <c>#{}</c> for constructing an empty map.</p>
</section>
<section>
<title>maps:next/1</title>
<p><seemfa marker="stdlib:maps#next/1">maps:next/1</seemfa>
is efficiently implemented in C and Erlang.</p>
</section>
<section>
<title>maps:put/3</title>
<p><seemfa marker="stdlib:maps#put/3">maps:put/3</seemfa> is
implemented in C.</p>
<p>If the key is known to already exist in the map, <seemfa
marker="stdlib:maps#update/3">maps:update/3</seemfa> is
slightly more efficient than <c>maps:put/3</c>.</p>
<p>If the keys are constants known at compile-time, using the
map update syntax with the <c>=></c> operator is more
efficient than multiple calls to <c>maps:put/3</c>,
especially for small maps.</p>
</section>
<section>
<title>maps:remove/2</title>
<p><seemfa marker="stdlib:maps#remove/2">maps:remove/2</seemfa>
is implemented in C.</p>
</section>
<section>
<title>maps:size/1</title>
<p>As an optimization, the compiler rewrites calls to
<seemfa marker="stdlib:maps#size/1">maps:size/1</seemfa>
to calls to the guard BIF <seemfa
marker="erts:erlang#map_size/1">map_size/1</seemfa>.
Calls to guard BIFs are more efficient than calls to other BIFs.</p>
</section>
<section>
<title>maps:take/2</title>
<p><seemfa marker="stdlib:maps#take/2">maps:take/2</seemfa>
is implemented in C.</p>
</section>
<section>
<title>maps:to_list/1</title>
<p><seemfa
marker="stdlib:maps#to_list/1">maps:to_list/1</seemfa> is
efficiently implemented in C and Erlang. If the resulting list
needs to be ordered, use <seemfa
marker="stdlib:lists#sort/1">lists:sort/1</seemfa> to sort
the result.</p>
<note><p>Maps are usually more performant than <seeerl
marker="stdlib:gb_trees">gb_trees</seeerl>, but if it is
necessary to frequently convert to and from sorted lists,
<c>gb_trees</c> can be a better choice.</p></note>
</section>
<section>
<title>maps:update/3</title>
<p><seemfa marker="stdlib:maps#update/3">maps:update/3</seemfa>
is implemented in C.</p>
<p>If the keys are constants known at compile-time, using the
map update syntax with the <c>:=</c> operator is more
efficient than multiple calls to <c>maps:update/3</c>,
especially for <seeguide marker="#terminology">small maps</seeguide>.</p>
</section>
<section>
<title>maps:values/1</title>
<p><seemfa marker="stdlib:maps#values/1">maps:values/1</seemfa>
is implemented in C.</p>
</section>
<section>
<title>maps:with/2</title>
<p><seemfa marker="stdlib:maps#with/2">maps:with/2</seemfa>
is implemented in Erlang. It creates a new map using <seemfa
marker="stdlib:maps#from_list/1">maps:from_list/1</seemfa>.</p>
</section>
<section>
<title>maps:without/2</title>
<p><seemfa marker="stdlib:maps#without/2">maps:without/2</seemfa>
is implemented in Erlang. It returns a modified copy of the
input map.</p>
</section>
</section>
</chapter>
|