1# @ohos.util.TreeMap (Nonlinear Container TreeMap) 2 3**TreeMap** stores key-value (KV) pairs. Each key must be unique and have only one value. 4 5**TreeMap** is implemented using a red-black tree, which is a binary search tree where keys are stored in sorted order for efficient insertion and removal. 6 7**[HashMap](js-apis-treemap.md)** is faster in accessing data than **TreeMap**, because the former accesses data based on the hash code of the key, whereas the latter stores and accesses the keys in sorted order. 8 9Recommended use case: Use **TreeMap** when you need to store KV pairs in sorted order. 10 11This topic uses the following to identify the use of generics: 12 13- K: Key 14 15- V: Value 16 17> **NOTE** 18> 19> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 20 21## Modules to Import 22 23```ts 24import TreeMap from '@ohos.util.TreeMap'; 25``` 26 27## TreeMap 28 29### Attributes 30 31**System capability**: SystemCapability.Utils.Lang 32 33| Name| Type| Readable| Writable| Description| 34| -------- | -------- | -------- | -------- | -------- | 35| length | number | Yes| No| Number of elements in a tree map (called container later).| 36 37 38### constructor 39 40constructor(comparator?:(firstValue: K, secondValue: K) => boolean) 41 42A constructor used to create a **TreeMap** instance. 43 44**System capability**: SystemCapability.Utils.Lang 45 46**Parameters** 47 48| Name| Type| Mandatory| Description| 49| -------- | -------- | -------- | -------- | 50| comparator | function | No| Custom comparator.| 51 52**Error codes** 53 54For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 55 56| ID| Error Message| 57| -------- | -------- | 58| 10200012 | The TreeMap's constructor cannot be directly invoked. | 59 60**Example** 61 62```ts 63let treeMap = new TreeMap(); 64``` 65 66 67### isEmpty 68 69isEmpty(): boolean 70 71Checks whether this container is empty (contains no element). 72 73**System capability**: SystemCapability.Utils.Lang 74 75**Return value** 76 77| Type| Description| 78| -------- | -------- | 79| boolean | Returns **true** if the container is empty; returns **false** otherwise.| 80 81**Error codes** 82 83For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 84 85| ID| Error Message| 86| -------- | -------- | 87| 10200011 | The isEmpty method cannot be bound. | 88 89**Example** 90 91```ts 92const treeMap = new TreeMap(); 93let result = treeMap.isEmpty(); 94``` 95 96 97### hasKey 98 99hasKey(key: K): boolean 100 101Checks whether this container has the specified key. 102 103**System capability**: SystemCapability.Utils.Lang 104 105**Parameters** 106 107| Name| Type| Mandatory| Description| 108| -------- | -------- | -------- | -------- | 109| key | K | Yes| Target key.| 110 111**Return value** 112 113| Type| Description| 114| -------- | -------- | 115| boolean | Returns **true** if the specified key is contained; returns **false** otherwise.| 116 117**Error codes** 118 119For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 120 121| ID| Error Message| 122| -------- | -------- | 123| 10200011 | The hasKey method cannot be bound. | 124 125**Example** 126 127```ts 128let treeMap = new TreeMap(); 129let result = treeMap.hasKey("squirrel"); 130treeMap.set("squirrel", 123); 131let result1 = treeMap.hasKey("squirrel"); 132``` 133 134 135### hasValue 136 137hasValue(value: V): boolean 138 139Checks whether this container has the specified value. 140 141**System capability**: SystemCapability.Utils.Lang 142 143**Parameters** 144 145| Name| Type| Mandatory| Description| 146| -------- | -------- | -------- | -------- | 147| value | V | Yes| Target value.| 148 149**Return value** 150 151| Type| Description| 152| -------- | -------- | 153| boolean | Returns **true** if the specified value is contained; returns **false** otherwise.| 154 155**Error codes** 156 157For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 158 159| ID| Error Message| 160| -------- | -------- | 161| 10200011 | The hasValue method cannot be bound. | 162 163**Example** 164 165```ts 166let treeMap = new TreeMap(); 167let result = treeMap.hasValue(123); 168treeMap.set("squirrel", 123); 169let result1 = treeMap.hasValue(123); 170``` 171 172 173### get 174 175get(key: K): V 176 177Obtains the value of the specified key in this container. 178 179**System capability**: SystemCapability.Utils.Lang 180 181**Parameters** 182 183| Name| Type| Mandatory| Description| 184| -------- | -------- | -------- | -------- | 185| key | K | Yes| Target key.| 186 187**Return value** 188 189| Type| Description| 190| -------- | -------- | 191| V | Value of the key.| 192 193**Error codes** 194 195For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 196 197| ID| Error Message| 198| -------- | -------- | 199| 10200011 | The get method cannot be bound. | 200 201**Example** 202 203```ts 204let treeMap = new TreeMap(); 205treeMap.set("squirrel", 123); 206treeMap.set("sparrow", 356); 207let result = treeMap.get("sparrow"); 208``` 209 210 211### getFirstKey 212 213getFirstKey(): K 214 215Obtains the first key in this container. 216 217**System capability**: SystemCapability.Utils.Lang 218 219**Return value** 220 221| Type| Description| 222| -------- | -------- | 223| K | Key obtained.| 224 225**Error codes** 226 227For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 228 229| ID| Error Message| 230| -------- | -------- | 231| 10200011 | The getFirstKey method cannot be bound. | 232 233**Example** 234 235```ts 236let treeMap = new TreeMap(); 237treeMap.set("squirrel", 123); 238treeMap.set("sparrow", 356); 239let result = treeMap.getFirstKey(); 240``` 241 242 243### getLastKey 244 245getLastKey(): K 246 247Obtains the last key in this container. 248 249**System capability**: SystemCapability.Utils.Lang 250 251**Return value** 252 253| Type| Description| 254| -------- | -------- | 255| K | Key obtained.| 256 257**Error codes** 258 259For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 260 261| ID| Error Message| 262| -------- | -------- | 263| 10200011 | The getLastKey method cannot be bound. | 264 265**Example** 266 267```ts 268let treeMap = new TreeMap(); 269treeMap.set("squirrel", 123); 270treeMap.set("sparrow", 356); 271let result = treeMap.getLastKey(); 272``` 273 274 275### setAll 276 277setAll(map: TreeMap<K, V>): void 278 279Adds all elements in a **TreeMap** instance to this container. 280 281**System capability**: SystemCapability.Utils.Lang 282 283**Parameters** 284 285| Name| Type| Mandatory| Description| 286| -------- | -------- | -------- | -------- | 287| map | TreeMap<K, V> | Yes| **TreeMap** object to be added to the container.| 288 289**Error codes** 290 291For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 292 293| ID| Error Message| 294| -------- | -------- | 295| 10200011 | The setAll method cannot be bound. | 296 297**Example** 298 299```ts 300let treeMap = new TreeMap(); 301treeMap.set("squirrel", 123); 302treeMap.set("sparrow", 356); 303let map = new TreeMap(); 304map.set("demo", 12); 305map.setAll(treeMap); // Add all elements in the treeMap to the map. 306map.forEach((value, key) => { 307 console.log("test" + value, key); // Print result: 12 demo, 356 sparrow, and 123 squirrel 308}) 309``` 310 311 312### set 313 314set(key: K, value: V): Object 315 316Adds an element to this container. 317 318**System capability**: SystemCapability.Utils.Lang 319 320**Parameters** 321 322| Name| Type| Mandatory| Description| 323| -------- | -------- | -------- | -------- | 324| key | K | Yes| Key of the target element.| 325| value | V | Yes| Value of the target element.| 326 327**Return value** 328 329| Type| Description| 330| -------- | -------- | 331| Object | Container that contains the new element.| 332 333**Error codes** 334 335For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 336 337| ID| Error Message| 338| -------- | -------- | 339| 10200011 | The set method cannot be bound. | 340 341**Example** 342 343```ts 344let treeMap = new TreeMap(); 345treeMap.set("squirrel", 123); 346``` 347 348 349### remove 350 351remove(key: K): V 352 353Removes the element with the specified key from this container. 354 355**System capability**: SystemCapability.Utils.Lang 356 357**Parameters** 358 359| Name| Type| Mandatory| Description| 360| -------- | -------- | -------- | -------- | 361| key | K | Yes| Target key.| 362 363**Return value** 364 365| Type| Description| 366| -------- | -------- | 367| V | Value of the element removed.| 368 369**Error codes** 370 371For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 372 373| ID| Error Message| 374| -------- | -------- | 375| 10200011 | The remove method cannot be bound. | 376 377**Example** 378 379```ts 380let treeMap = new TreeMap(); 381treeMap.set("squirrel", 123); 382treeMap.set("sparrow", 356); 383treeMap.remove("sparrow"); 384``` 385 386 387### getLowerKey 388 389getLowerKey(key: K): K 390 391Obtains the key that is placed in front of the input key in this container. 392 393**System capability**: SystemCapability.Utils.Lang 394 395**Parameters** 396 397| Name| Type| Mandatory| Description| 398| -------- | -------- | -------- | -------- | 399| key | K | Yes| Input key.| 400 401**Return value** 402 403| Type| Description| 404| -------- | -------- | 405| K | Key obtained.| 406 407**Error codes** 408 409For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 410 411| ID| Error Message| 412| -------- | -------- | 413| 10200011 | The getLowerKey method cannot be bound. | 414 415**Example** 416 417```ts 418let treeMap = new TreeMap(); 419treeMap.set("squirrel", 123); 420treeMap.set("sparrow", 356); 421treeMap.set("gander", 356); 422let result = treeMap.getLowerKey("sparrow"); 423``` 424 425 426### getHigherKey 427 428getHigherKey(key: K): K 429 430Obtains the key that is placed next to the input key in this container. 431 432**System capability**: SystemCapability.Utils.Lang 433 434**Parameters** 435 436| Name| Type| Mandatory| Description| 437| -------- | -------- | -------- | -------- | 438| key | K | Yes| Input key.| 439 440**Return value** 441 442| Type| Description| 443| -------- | -------- | 444| K | Key obtained.| 445 446**Error codes** 447 448For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 449 450| ID| Error Message| 451| -------- | -------- | 452| 10200011 | The getHigherKey method cannot be bound. | 453 454**Example** 455 456```ts 457let treeMap = new TreeMap(); 458treeMap.set("squirrel", 123); 459treeMap.set("sparrow", 356); 460treeMap.set("gander", 356); 461let result = treeMap.getHigherKey("sparrow"); 462``` 463 464### replace 465 466replace(key: K, newValue: V): boolean 467 468Replaces an element in this container. 469 470**System capability**: SystemCapability.Utils.Lang 471 472**Parameters** 473 474| Name| Type| Mandatory| Description| 475| -------- | -------- | -------- | -------- | 476| key | K | Yes| Key of the target element.| 477| newValue | V | Yes| New value of the element.| 478 479**Return value** 480 481| Type| Description| 482| -------- | -------- | 483| boolean | Returns **true** if the element is replaced successfully; returns **false** otherwise.| 484 485**Error codes** 486 487For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 488 489| ID| Error Message| 490| -------- | -------- | 491| 10200011 | The replace method cannot be bound. | 492 493**Example** 494 495```ts 496let treeMap = new TreeMap(); 497treeMap.set("sparrow", 123); 498let result = treeMap.replace("sparrow", 357); 499``` 500 501 502### clear 503 504clear(): void 505 506Clears this container and sets its length to **0**. 507 508**System capability**: SystemCapability.Utils.Lang 509 510**Error codes** 511 512For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 513 514| ID| Error Message| 515| -------- | -------- | 516| 10200011 | The clear method cannot be bound. | 517 518**Example** 519 520```ts 521let treeMap = new TreeMap(); 522treeMap.set("squirrel", 123); 523treeMap.set("sparrow", 356); 524treeMap.clear(); 525``` 526 527 528### keys 529 530keys(): IterableIterator<K> 531 532Obtains an iterator that contains all the keys in this container. 533 534**System capability**: SystemCapability.Utils.Lang 535 536**Return value** 537 538| Type| Description| 539| -------- | -------- | 540| IterableIterator<K> | Iterator obtained.| 541 542**Error codes** 543 544For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 545 546| ID| Error Message| 547| -------- | -------- | 548| 10200011 | The keys method cannot be bound. | 549 550**Example** 551 552```ts 553let treeMap = new TreeMap(); 554treeMap.set("squirrel", 123); 555treeMap.set("sparrow", 356); 556let iter = treeMap.keys(); 557let temp = iter.next().value; 558while(temp != undefined) { 559 console.log("value:" + temp); 560 temp = iter.next().value; 561} 562``` 563 564 565### values 566 567values(): IterableIterator<V> 568 569Obtains an iterator that contains all the values in this container. 570 571**System capability**: SystemCapability.Utils.Lang 572 573**Return value** 574 575| Type| Description| 576| -------- | -------- | 577| IterableIterator<V> | Iterator obtained.| 578 579**Error codes** 580 581For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 582 583| ID| Error Message| 584| -------- | -------- | 585| 10200011 | The values method cannot be bound. | 586 587**Example** 588 589```ts 590let treeMap = new TreeMap(); 591treeMap.set("squirrel", 123); 592treeMap.set("sparrow", 356); 593let iter = treeMap.values(); 594let temp = iter.next().value; 595while(temp != undefined) { 596 console.log("value:" + temp); 597 temp = iter.next().value; 598} 599``` 600 601 602### forEach 603 604forEach(callbackFn: (value?: V, key?: K, map?: TreeMap<K, V>) => void, thisArg?: Object): void 605 606Uses a callback to traverse the elements in this container and obtain their position indexes. 607 608**System capability**: SystemCapability.Utils.Lang 609 610**Parameters** 611 612| Name| Type| Mandatory| Description| 613| -------- | -------- | -------- | -------- | 614| callbackFn | function | Yes| Callback invoked to traverse the elements in the container.| 615| thisArg | Object | No| Value of **this** to use when **callbackFn** is invoked.| 616 617callbackfn 618| Name| Type| Mandatory| Description| 619| -------- | -------- | -------- | -------- | 620| value | V | No| Value of the element that is currently traversed.| 621| key | K | No| Key of the element that is currently traversed.| 622| map | TreeMap<K, V> | No| Instance that invokes the **forEach** method.| 623 624**Error codes** 625 626For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 627 628| ID| Error Message| 629| -------- | -------- | 630| 10200011 | The forEach method cannot be bound. | 631 632**Example** 633 634```ts 635let treeMap = new TreeMap(); 636treeMap.set("sparrow", 123); 637treeMap.set("gull", 357); 638treeMap.forEach((value, key) => { 639 console.log("value:" + value, "key:" + key); 640}); 641``` 642 643 644### entries 645 646entries(): IterableIterator<[K, V]> 647 648Obtains an iterator that contains all the elements in this container. 649 650**System capability**: SystemCapability.Utils.Lang 651 652**Return value** 653 654| Type| Description| 655| -------- | -------- | 656| IterableIterator<[K, V]> | Iterator obtained.| 657 658**Error codes** 659 660For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 661 662| ID| Error Message| 663| -------- | -------- | 664| 10200011 | The entries method cannot be bound. | 665 666**Example** 667 668```ts 669let treeMap = new TreeMap(); 670treeMap.set("squirrel", 123); 671treeMap.set("sparrow", 356); 672let iter = treeMap.entries(); 673let temp = iter.next().value; 674while(temp != undefined) { 675 console.log("key:" + temp[0]); 676 console.log("value:" + temp[1]); 677 temp = iter.next().value; 678} 679``` 680 681 682### [Symbol.iterator] 683 684[Symbol.iterator]\(): IterableIterator<[K, V]> 685 686Obtains an iterator, each item of which is a JavaScript object. 687 688**System capability**: SystemCapability.Utils.Lang 689 690**Return value** 691| Type| Description| 692| -------- | -------- | 693| IterableIterator<[K, V]> | Iterator obtained.| 694 695**Error codes** 696 697For details about the error codes, see [Utils Error Codes](../errorcodes/errorcode-utils.md). 698 699| ID| Error Message| 700| -------- | -------- | 701| 10200011 | The Symbol.iterator method cannot be bound. | 702 703**Example** 704 705```ts 706let treeMap = new TreeMap(); 707treeMap.set("squirrel", 123); 708treeMap.set("sparrow", 356); 709 710// Method 1: 711for (let item of treeMap) { 712 console.log("key:" + item[0]); 713 console.log("value:" + item[1]); 714} 715 716// Method 2: 717let iter = treeMap[Symbol.iterator](); 718let temp = iter.next().value; 719while(temp != undefined) { 720 console.log("key:" + temp[0]); 721 console.log("value:" + temp[1]); 722 temp = iter.next().value; 723} 724``` 725