From b48af86b4884602b0419966949d13849ac25e440 Mon Sep 17 00:00:00 2001 From: chengyuli Date: Sat, 7 Jun 2025 10:34:20 +0800 Subject: [PATCH] add OrderedMap/Set Signed-off-by: chengyuli --- api/@ohos.util.OrderedMap.d.ts | 286 +++++++++++++++++++++++++++++++++ api/@ohos.util.OrderedSet.d.ts | 245 ++++++++++++++++++++++++++++ kits/@kit.ArkTS.d.ts | 4 +- 3 files changed, 534 insertions(+), 1 deletion(-) create mode 100644 api/@ohos.util.OrderedMap.d.ts create mode 100644 api/@ohos.util.OrderedSet.d.ts diff --git a/api/@ohos.util.OrderedMap.d.ts b/api/@ohos.util.OrderedMap.d.ts new file mode 100644 index 0000000000..c6515e022b --- /dev/null +++ b/api/@ohos.util.OrderedMap.d.ts @@ -0,0 +1,286 @@ +/* + * Copyright (c) 2025 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @file + * @kit ArkTS + */ + +/** + * This parameter specifies the comparator of ordered set in comparation. + * + * @typedef { function } ComparatorFn + * @param { T } firstValue - firstValue (required) previous element. + * @param { T } secondValue - secondValue (required) next element. + * @returns { number } the number type + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ +type ComparatorFn = (firstValue: T, secondValue: T) => number; +/** + * OrderedMap stores key-value (KV) pairs. Each key must be unique and have only one value. + * OrderedMap 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. + * + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ +declare class OrderedMap { + /** + * A constructor used to create a OrderedMap object. + * + * @param { ComparatorFn } [comparator] - comparator + * comparator (Optional) User-defined comparison functions. + * @throws { BusinessError } 10200012 - The OrderedMap's constructor cannot be directly invoked. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + constructor(comparator?: ComparatorFn); + /** + * Gets the element number of the hashmap. + * + * @type { number } + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + length: number; + /** + * Returns whether the Map object contains elements + * + * @returns { boolean } the boolean type + * @throws { BusinessError } 10200011 - The isEmpty method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + isEmpty(): boolean; + /** + * Returns whether a key is contained in this map + * + * @param { K } key - key key need to determine whether to include the key + * @returns { boolean } the boolean type + * @throws { BusinessError } 10200011 - The hasKey method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + hasKey(key: K): boolean; + /** + * Returns whether a value is contained in this map + * + * @param { V } value - value value value need to determine whether to include the value + * @returns { boolean } the boolean type + * @throws { BusinessError } 10200011 - The hasValue method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + hasValue(value: V): boolean; + /** + * Returns a specified element in a Map object, or undefined if there is no corresponding element + * + * @param { K } key - key key the index in OrderedMap + * @returns { V } value or undefined + * @throws { BusinessError } 10200011 - The get method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + get(key: K): V; + /** + * Obtains the first sorted key in the treemap. + * Or returns undefined if tree map is empty + * + * @returns { K } value or undefined + * @throws { BusinessError } 10200011 - The getFirstKey method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + getFirstKey(): K; + /** + * Obtains the last sorted key in the treemap. + * Or returns undefined if tree map is empty + * + * @returns { K } value or undefined + * @throws { BusinessError } 10200011 - The getLastKey method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + getLastKey(): K; + /** + * Adds all element groups in one map to another map + * + * @param { OrderedMap } map - map map the Map object to add members + * @throws { BusinessError } 10200011 - The setAll method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + setAll(map: OrderedMap): void; + /** + * Adds or updates a(new) key-value pair with a key and value specified for the Map object + * + * @param { K } key - key key Added or updated targets + * @param { V } value - value value Added or updated value + * @returns { Object } the map object after set + * @throws { BusinessError } 10200011 - The set method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + set(key: K, value: V): Object; + /** + * Remove a specified element from a Map object + * + * @param { K } key - key key Target to be deleted + * @returns { V } Target mapped value + * @throws { BusinessError } 10200011 - The remove method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + remove(key: K): V; + /** + * Clear all element groups in the map + * + * @throws { BusinessError } 10200011 - The clear method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + clear(): void; + /** + * Returns the greatest element smaller than or equal to the specified key + * if the key does not exist, undefined is returned + * + * @param { K } key - key key Objective of comparison + * @returns { K } key or undefined + * @throws { BusinessError } 10200011 - The getLowerKey method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + getLowerKey(key: K): K; + /** + * Returns the least element greater than or equal to the specified key + * if the key does not exist, undefined is returned + * + * @param { K } key - key key Objective of comparison + * @returns { K } key or undefined + * @throws { BusinessError } 10200011 - The getHigherKey method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + getHigherKey(key: K): K; + /** + * Returns a new Iterator object that contains the keys contained in this map + * + * @returns { IterableIterator } + * @throws { BusinessError } 10200011 - The keys method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + keys(): IterableIterator; + /** + * Returns a new Iterator object that contains the values contained in this map + * + * @returns { IterableIterator } + * @throws { BusinessError } 10200011 - The values method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + values(): IterableIterator; + /** + * Replace the old value by new value corresponding to the specified key + * + * @param { K } key - key key Updated targets + * @param { V } newValue - newValue newValue Updated the target mapped value + * @returns { boolean } the boolean type(Is there a target pointed to by the key) + * @throws { BusinessError } 10200011 - The replace method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + replace(key: K, newValue: V): boolean; + /** + * Executes the given callback function once for each real key in the map. + * It does not perform functions on deleted keys + * + * @param { function } callbackFn - callbackFn + * callbackFn (required) A function that accepts up to three arguments. + * The function to be called for each element. + * @param { Object } [thisArg] - thisArg + * thisArg (Optional) The value to be used as this value for when callbackFn is called. + * If thisArg is omitted, undefined is used as the this value. + * @throws { BusinessError } 10200011 - The forEach method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + forEach(callbackFn: (value?: V, key?: K, map?: OrderedMap) => void, thisArg?: Object): void; + /** + * Returns a new Iterator object that contains the [key, value] pairs for each element in the Map object in insertion order + * + * @returns { IterableIterator<[K, V]> } + * @throws { BusinessError } 10200011 - The entries method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + entries(): IterableIterator<[K, V]>; + /** + * returns an ES6 iterator.Each item of the iterator is a Javascript Object + * + * @returns { IterableIterator<[K, V]> } + * @throws { BusinessError } 10200011 - The Symbol.iterator method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + [Symbol.iterator](): IterableIterator<[K, V]>; +} + +export default OrderedMap; diff --git a/api/@ohos.util.OrderedSet.d.ts b/api/@ohos.util.OrderedSet.d.ts new file mode 100644 index 0000000000..5ca141e46a --- /dev/null +++ b/api/@ohos.util.OrderedSet.d.ts @@ -0,0 +1,245 @@ +/* + * Copyright (c) 2025 Huawei Device Co., Ltd. + * 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. + */ + +/** + * @file + * @kit ArkTS + */ + +/** + * This parameter specifies the comparator of ordered set in comparation. + * + * @typedef { function } ComparatorFn + * @param { T } firstValue - firstValue (required) previous element. + * @param { T } secondValue - secondValue (required) next element. + * @returns { number } the number type + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ +type ComparatorFn = (firstValue: T, secondValue: T) => number; +/** + * OrderedSet is implemented based on TreeMap. In OrderedSet, only value objects are processed. + * OrderedSet can be used to store values, each of which must be unique. + * + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 +*/ +declare class OrderedSet { + + /** + * A constructor used to create a OrderedSet object. + * + * @param { ComparatorFn } [comparator] - comparator + * comparator (Optional) User-defined comparison functions. + * @throws { BusinessError } 10200012 - The OrderedSet's constructor cannot be directly invoked. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + constructor(comparator?: ComparatorFn); + /** + * Gets the element number of the OrderedSet. + * + * @type { number } + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + length: number; + /** + * Returns whether the Set object contains elements + * + * @returns { boolean } the boolean type + * @throws { BusinessError } 10200011 - The isEmpty method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + isEmpty(): boolean; + /** + * Returns whether the Set object contain s the elements + * + * @param { T } value - value value need to determine whether to include the element + * @returns { boolean } the boolean type + * @throws { BusinessError } 10200011 - The has method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + has(value: T): boolean; + /** + * If the set does not contain the element, the specified element is added + * + * @param { T } value - value value Added element + * @returns { boolean } the boolean type(Is there contain this element) + * @throws { BusinessError } 10200011 - The add method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + add(value: T): boolean; + /** + * Remove a specified element from a Set object + * + * @param { T } value - value value Target to be deleted + * @returns { boolean } the boolean type(Is there contain this element) + * @throws { BusinessError } 10200011 - The remove method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + remove(value: T): boolean; + /** + * Clears all element groups in a set + * + * @throws { BusinessError } 10200011 - The clear method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + clear(): void; + /** + * Gets the first elements in a set + * + * @returns { T } value or undefined + * @throws { BusinessError } 10200011 - The getFirstValue method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + getFirstValue(): T; + /** + * Gets the last elements in a set + * + * @returns { T } value or undefined + * @throws { BusinessError } 10200011 - The getLastValue method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + getLastValue(): T; + /** + * Returns the greatest element smaller than or equal to the specified key + * if the key does not exist, undefined is returned + * + * @param { T } key - key key Objective of comparison + * @returns { T } key or undefined + * @throws { BusinessError } 10200011 - The getLowerValue method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + getLowerValue(key: T): T; + /** + * Returns the least element greater than or equal to the specified key + * if the key does not exist, undefined is returned + * + * @param { T } key - key key Objective of comparison + * @returns { T } key or undefined + * @throws { BusinessError } 10200011 - The getHigherValue method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + getHigherValue(key: T): T; + /** + * Return and delete the first element, returns undefined if tree set is empty + * + * @returns { T } first value or undefined + * @throws { BusinessError } 10200011 - The popFirst method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + popFirst(): T; + /** + * Return and delete the last element, returns undefined if tree set is empty + * + * @returns { T } last value or undefined + * @throws { BusinessError } 10200011 - The popLast method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + popLast(): T; + /** + * Executes a provided function once for each value in the Set object. + * + * @param { function } callbackFn - callbackFn + * callbackFn (required) A function that accepts up to three arguments. + * The function to be called for each element. + * @param { Object } [thisArg] - thisArg + * thisArg (Optional) The value to be used as this value for when callbackFn is called. + * If thisArg is omitted, undefined is used as the this value. + * @throws { BusinessError } 10200011 - The forEach method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + forEach(callbackFn: (value?: T, key?: T, set?: OrderedSet) => void, thisArg?: Object): void; + /** + * Returns a new Iterator object that contains the values contained in this set + * + * @returns { IterableIterator } + * @throws { BusinessError } 10200011 - The values method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + values(): IterableIterator; + /** + * Returns a new Iterator object that contains the [key, value] pairs for each element in the Set object in insertion order + * + * @returns { IterableIterator<[T, T]> } + * @throws { BusinessError } 10200011 - The entries method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + entries(): IterableIterator<[T, T]>; + /** + * returns an ES6 iterator.Each item of the iterator is a Javascript Object + * + * @returns { IterableIterator } + * @throws { BusinessError } 10200011 - The Symbol.iterator method cannot be bound. + * @syscap SystemCapability.Utils.Lang + * @crossplatform + * @atomicservice + * @since 20 + */ + [Symbol.iterator](): IterableIterator; +} + +export default OrderedSet; diff --git a/kits/@kit.ArkTS.d.ts b/kits/@kit.ArkTS.d.ts index d3335d8e22..d1e32d5863 100644 --- a/kits/@kit.ArkTS.d.ts +++ b/kits/@kit.ArkTS.d.ts @@ -40,6 +40,8 @@ import Stack from '@ohos.util.Stack'; import TreeMap from '@ohos.util.TreeMap'; import TreeSet from '@ohos.util.TreeSet'; import Vector from '@ohos.util.Vector'; +import OrderedMap from '@ohos.util.OrderedMap'; +import OrderedSet from '@ohos.util.OrderedSet'; import worker, { DedicatedWorkerGlobalScope, ErrorEvent, Event, EventListener, EventTarget, MessageEvent, MessageEvents, PostMessageOptions, ThreadWorkerGlobalScope, @@ -58,5 +60,5 @@ export { EventTarget, HashMap, HashSet, LightWeightMap, LightWeightSet, LinkedList, List, MessageEvent, MessageEvents, PlainArray, PostMessageOptions, Queue, Stack, ThreadWorkerGlobalScope, TreeMap, TreeSet, Vector, WorkerEventListener, WorkerEventTarget, WorkerOptions, ThreadWorkerPriority, buffer, fastbuffer, process, - taskpool, uri, url, util, worker, xml, JSON, lang, ArkTSUtils, collections, stream, Decimal + taskpool, uri, url, util, worker, xml, JSON, lang, ArkTSUtils, collections, stream, Decimal, OrderedMap, OrderedSet }; -- Gitee