1# 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 11> **NOTE** 12> 13> 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. 14 15## Modules to Import 16 17```ts 18import TreeMap from '@ohos.util.TreeMap'; 19``` 20 21## TreeMap 22 23### Attributes 24 25**System capability**: SystemCapability.Utils.Lang 26 27| Name| Type| Readable| Writable| Description| 28| -------- | -------- | -------- | -------- | -------- | 29| length | number | Yes| No| Number of elements in a tree map (called container later).| 30 31 32### constructor 33 34constructor(comparator?:(firstValue: K, secondValue: K) => boolean) 35 36A constructor used to create a **TreeMap** instance. 37 38**System capability**: SystemCapability.Utils.Lang 39 40**Parameters** 41 42| Name| Type| Mandatory| Description| 43| -------- | -------- | -------- | -------- | 44| comparator | function | No| Custom comparator.| 45 46**Example** 47 48```ts 49let treeMap = new TreeMap(); 50``` 51 52 53### isEmpty 54 55isEmpty(): boolean 56 57Checks whether this container is empty (contains no element). 58 59**System capability**: SystemCapability.Utils.Lang 60 61**Return value** 62 63| Type| Description| 64| -------- | -------- | 65| boolean | Returns **true** if the container is empty; returns **false** otherwise.| 66 67**Example** 68 69```ts 70const treeMap = new TreeMap(); 71let result = treeMap.isEmpty(); 72``` 73 74 75### hasKey 76 77hasKey(key: K): boolean 78 79Checks whether this container has the specified key. 80 81**System capability**: SystemCapability.Utils.Lang 82 83**Parameters** 84 85| Name| Type| Mandatory| Description| 86| -------- | -------- | -------- | -------- | 87| key | K | Yes| Target key.| 88 89**Return value** 90 91| Type| Description| 92| -------- | -------- | 93| boolean | Returns **true** if the specified key is contained; returns **false** otherwise.| 94 95**Example** 96 97```ts 98let treeMap = new TreeMap(); 99let result = treeMap.hasKey("Ahfbrgrbgnutfodgorrogorgrogofdfdf"); 100treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 101let result1 = treeMap.hasKey("Ahfbrgrbgnutfodgorrogorgrogofdfdf"); 102``` 103 104 105### hasValue 106 107hasValue(value: V): boolean 108 109Checks whether this container has the specified value. 110 111**System capability**: SystemCapability.Utils.Lang 112 113**Parameters** 114 115| Name| Type| Mandatory| Description| 116| -------- | -------- | -------- | -------- | 117| value | V | Yes| Target value.| 118 119**Return value** 120 121| Type| Description| 122| -------- | -------- | 123| boolean | Returns **true** if the specified value is contained; returns **false** otherwise.| 124 125**Example** 126 127```ts 128let treeMap = new TreeMap(); 129let result = treeMap.hasValue(123); 130treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 131let result1 = treeMap.hasValue(123); 132``` 133 134 135### get 136 137get(key: K): V 138 139Obtains the value of the specified key in this container. 140 141**System capability**: SystemCapability.Utils.Lang 142 143**Parameters** 144 145| Name| Type| Mandatory| Description| 146| -------- | -------- | -------- | -------- | 147| key | K | Yes| Target key.| 148 149**Return value** 150 151| Type| Description| 152| -------- | -------- | 153| V | Value of the key.| 154 155**Example** 156 157```ts 158let treeMap = new TreeMap(); 159treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 160treeMap.set("sdfs", 356); 161let result = treeMap.get("sdfs"); 162``` 163 164 165### getFirstKey 166 167getFirstKey(): K 168 169Obtains the first key in this container. 170 171**System capability**: SystemCapability.Utils.Lang 172 173**Return value** 174 175| Type| Description| 176| -------- | -------- | 177| K | Key obtained.| 178 179**Example** 180 181```ts 182let treeMap = new TreeMap(); 183treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 184treeMap.set("sdfs", 356); 185let result = treeMap.getFirstKey(); 186``` 187 188 189### getLastKey 190 191getLastKey(): K 192 193Obtains the last key in this container. 194 195**System capability**: SystemCapability.Utils.Lang 196 197**Return value** 198 199| Type| Description| 200| -------- | -------- | 201| K | Key obtained.| 202 203**Example** 204 205```ts 206let treeMap = new TreeMap(); 207treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 208treeMap.set("sdfs", 356); 209let result = treeMap.getLastKey(); 210``` 211 212 213### setAll 214 215setAll(map: TreeMap<K, V>): void 216 217Adds all elements in a **TreeMap** instance to this container. 218 219**System capability**: SystemCapability.Utils.Lang 220 221**Parameters** 222 223| Name| Type| Mandatory| Description| 224| -------- | -------- | -------- | -------- | 225| map | TreeMap<K, V> | Yes| **TreeMap** instance whose elements are to be added to the current container.| 226 227**Example** 228 229```ts 230let treeMap = new TreeMap(); 231treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 232treeMap.set("sdfs", 356); 233let map = new TreeMap(); 234treeMap.setAll(map); 235``` 236 237 238### set 239 240set(key: K, value: V): Object 241 242Adds an element to this container. 243 244**System capability**: SystemCapability.Utils.Lang 245 246**Parameters** 247 248| Name| Type| Mandatory| Description| 249| -------- | -------- | -------- | -------- | 250| key | K | Yes| Key of the target element.| 251| value | V | Yes| Value of the target element.| 252 253**Return value** 254 255| Type| Description| 256| -------- | -------- | 257| Object | Container that contains the new element.| 258 259**Example** 260 261```ts 262let treeMap = new TreeMap(); 263treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 264``` 265 266 267### remove 268 269remove(key: K): V 270 271Removes the element with the specified key from this container. 272 273**System capability**: SystemCapability.Utils.Lang 274 275**Parameters** 276 277| Name| Type| Mandatory| Description| 278| -------- | -------- | -------- | -------- | 279| key | K | Yes| Target key.| 280 281**Return value** 282 283| Type| Description| 284| -------- | -------- | 285| V | Value of the element removed.| 286 287**Example** 288 289```ts 290let treeMap = new TreeMap(); 291treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 292treeMap.set("sdfs", 356); 293treeMap.remove("sdfs"); 294``` 295 296 297### getLowerKey 298 299getLowerKey(key: K): K 300 301Obtains the key that is placed in front of the input key in this container. 302 303**System capability**: SystemCapability.Utils.Lang 304 305**Parameters** 306 307| Name| Type| Mandatory| Description| 308| -------- | -------- | -------- | -------- | 309| key | K | Yes| Input key.| 310 311**Return value** 312 313| Type| Description| 314| -------- | -------- | 315| K | Key obtained.| 316 317**Example** 318 319```ts 320let treeMap = new TreeMap(); 321treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 322treeMap.set("sdfs", 356); 323treeMap.set("zdfgsd", 356); 324let result = treeMap.getLowerKey("sdfs"); 325``` 326 327 328### getHigherKey 329 330getHigherKey(key: K): K 331 332Obtains the key that is placed next to the input key in this container. 333 334**System capability**: SystemCapability.Utils.Lang 335 336**Parameters** 337 338| Name| Type| Mandatory| Description| 339| -------- | -------- | -------- | -------- | 340| key | K | Yes| Input key.| 341 342**Return value** 343 344| Type| Description| 345| -------- | -------- | 346| K | Key obtained.| 347 348**Example** 349 350```ts 351let treeMap = new TreeMap(); 352treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 353treeMap.set("sdfs", 356); 354treeMap.set("zdfgsd", 356); 355let result = treeMap.getHigherKey("sdfs"); 356``` 357 358### replace 359 360replace(key: K, newValue: V): boolean 361 362Replaces an element in this container. 363 364**System capability**: SystemCapability.Utils.Lang 365 366**Parameters** 367 368| Name| Type| Mandatory| Description| 369| -------- | -------- | -------- | -------- | 370| key | K | Yes| Key of the target element.| 371| newValue | V | Yes| New value of the element.| 372 373**Return value** 374 375| Type| Description| 376| -------- | -------- | 377| boolean | Returns **true** if the element is replaced successfully; returns **false** otherwise.| 378 379**Example** 380 381```ts 382let treeMap = new TreeMap(); 383treeMap.set("sdfs", 123); 384let result = treeMap.replace("sdfs", 357); 385``` 386 387 388### clear 389 390clear(): void 391 392Clears this container and sets its length to **0**. 393 394**System capability**: SystemCapability.Utils.Lang 395 396**Example** 397 398```ts 399let treeMap = new TreeMap(); 400treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 401treeMap.set("sdfs", 356); 402treeMap.clear(); 403``` 404 405 406### keys 407 408keys(): IterableIterator<K> 409 410Obtains an iterator that contains all the keys in this container. 411 412**System capability**: SystemCapability.Utils.Lang 413 414**Return value** 415 416| Type| Description| 417| -------- | -------- | 418| IterableIterator<K> | Iterator obtained.| 419 420**Example** 421 422```ts 423let treeMap = new TreeMap(); 424treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 425treeMap.set("sdfs", 356); 426let iter = treeMap.keys(); 427let temp = iter.next().value; 428while(temp != undefined) { 429 console.log("value:" + temp); 430 temp = iter.next().value; 431} 432``` 433 434 435### values 436 437values(): IterableIterator<V> 438 439Obtains an iterator that contains all the values in this container. 440 441**System capability**: SystemCapability.Utils.Lang 442 443**Return value** 444 445| Type| Description| 446| -------- | -------- | 447| IterableIterator<V> | Iterator obtained.| 448 449**Example** 450 451```ts 452let treeMap = new TreeMap(); 453treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 454treeMap.set("sdfs", 356); 455let iter = treeMap.values(); 456let temp = iter.next().value; 457while(temp != undefined) { 458 console.log("value:" + temp); 459 temp = iter.next().value; 460} 461``` 462 463 464### forEach 465 466forEach(callbackfn: (value?: V, key?: K, map?: TreeMap<K, V>) => void, thisArg?: Object): void 467 468Uses a callback to traverse the elements in this container and obtain their position indexes. 469 470**System capability**: SystemCapability.Utils.Lang 471 472**Parameters** 473 474| Name| Type| Mandatory| Description| 475| -------- | -------- | -------- | -------- | 476| callbackfn | function | Yes| Callback invoked to traverse the elements in the container.| 477| thisArg | Object | No| Value to use when the callback is invoked.| 478 479callbackfn 480| Name| Type| Mandatory| Description| 481| -------- | -------- | -------- | -------- | 482| value | V | No| Value of the element that is currently traversed.| 483| key | K | No| Key of the element that is currently traversed.| 484| map | TreeMap<K, V> | No| Instance that invokes the **forEach** method.| 485 486**Example** 487 488```ts 489let treeMap = new TreeMap(); 490treeMap.set("sdfs", 123); 491treeMap.set("dfsghsf", 357); 492treeMap.forEach((value, key) => { 493 console.log("value:" + value, "key:" + key); 494}); 495``` 496 497 498### entries 499 500entries(): IterableIterator<[K, V]> 501 502Obtains an iterator that contains all the elements in this container. 503 504**System capability**: SystemCapability.Utils.Lang 505 506**Return value** 507 508| Type| Description| 509| -------- | -------- | 510| IterableIterator<[K, V]> | Iterator obtained.| 511 512**Example** 513 514```ts 515let treeMap = new TreeMap(); 516treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 517treeMap.set("sdfs", 356); 518let iter = treeMap.entries(); 519let temp = iter.next().value; 520while(temp != undefined) { 521 console.log("key:" + temp[0]); 522 console.log("value:" + temp[1]); 523 temp = iter.next().value; 524} 525``` 526 527 528### [Symbol.iterator] 529 530[Symbol.iterator]\(): IterableIterator<[K, V]> 531 532Obtains an iterator, each item of which is a JavaScript object. 533 534**System capability**: SystemCapability.Utils.Lang 535 536**Return value** 537| Type| Description| 538| -------- | -------- | 539| IterableIterator<[K, V]> | Iterator obtained.| 540 541**Example** 542 543```ts 544let treeMap = new TreeMap(); 545treeMap.set("Ahfbrgrbgnutfodgorrogorgrogofdfdf", 123); 546treeMap.set("sdfs", 356); 547 548// Method 1: 549for (let item of treeMap) { 550 console.log("key:" + item[0]); 551 console.log("value:" + item[1]); 552} 553 554// Method 2: 555let iter = treeMap[Symbol.iterator](); 556let temp = iter.next().value; 557while(temp != undefined) { 558 console.log("key:" + temp[0]); 559 console.log("value:" + temp[1]); 560 temp = iter.next().value; 561} 562``` 563