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