This module provides common utility functions, such as **TextEncoder** and **TextDecoder** for string encoding and decoding, **RationalNumber** for rational number operations, **LruBuffer** for buffer management, **Scope** for range determination, **Base64** for Base64 encoding and decoding, and **Types** for checks of built-in object types.
> **NOTE**
>
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
This module provides common utility functions, such as **TextEncoder** and **TextDecoder** for string encoding and decoding, **RationalNumber** for rational number operations, **LruBuffer** for buffer management, **Scope** for range determination, **Base64** for Base64 encoding and decoding, and **Types** for checks of built-in object types.
## Modules to Import
```
```js
importutilfrom'@ohos.util';
```
...
...
@@ -45,14 +43,14 @@ console.log(res);
## util.printf<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [util.format9+](#utilformat9) instead.
printf(format: string, ...args: Object[]): string
Formats the specified values and inserts them into the string by replacing the wildcard in the string.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [util.format<sup>9+</sup>](#utilformat9) instead.
@@ -60,7 +58,7 @@ Formats the specified values and inserts them into the string by replacing the w
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| format | string | Yes| String.|
| ...args | Object[] | No| Values to format. The formatted values will be replaced the wildcard in the string.|
| ...args | Object[] | No| Values to format. The formatted values will be replaced the wildcard in the string.|
**Return value**
...
...
@@ -69,6 +67,7 @@ Formats the specified values and inserts them into the string by replacing the w
| string | String containing the formatted values.|
**Example**
```js
letres=util.printf("%s","hello world!");
console.log(res);
...
...
@@ -96,22 +95,22 @@ Obtains detailed information about a system error code.
**Example**
```js
```js
leterrnum=10;// 10 is a system error code.
letresult=util.errnoToString(errnum);
console.log("result = "+result);
```
```
## util.getErrorString<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [util.errnoToString9+](#utilerrnotostring9) instead.
getErrorString(errno: number): string
Obtains detailed information about a system error code.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [util.errnoToString<sup>9+</sup>](#utilerrnotostring9) instead.
@@ -127,6 +126,7 @@ Obtains detailed information about a system error code.
| string | Detailed information about the error code.|
**Example**
```js
leterrnum=10;// 10 is a system error code.
letresult=util.getErrorString(errnum);
...
...
@@ -154,6 +154,7 @@ Calls back an asynchronous function. In the callback, the first parameter indica
| Function | Callback, in which the first parameter indicates the cause of the rejection (the value is **null** if the promise has been resolved) and the second parameter indicates the resolved value.|
**Example**
```js
asyncfunctionpromiseFn(){
returnPromise.reject('value');
...
...
@@ -187,6 +188,7 @@ Processes an asynchronous function and returns a promise.
| Function | Function in the error-first style (that is, **(err, value) =>...** is called as the last parameter) and the promise.|
**Example**
```js
functionaysnFun(str1,str2){
if(typeofstr1==='object'&&typeofstr2==='object'){
...
...
@@ -205,11 +207,11 @@ Processes an asynchronous function and returns a promise.
A constructor used to create a **TextDecoder** object.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [constructor<sup>9+</sup>](#constructor9) instead.
@@ -528,21 +539,21 @@ result = textEncoder.encodeInto("\uD800¥¥");
### encode<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [encodeInto9+](#encodeinto9) instead.
encode(input?: string): Uint8Array
Encodes the input content.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [encodeInto<sup>9+</sup>](#encodeinto9) instead.
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [encodeIntoUint8Array<sup>9+</sup>](#encodeintouint8array9) instead.
A constructor used to create a **RationalNumber** object.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [constructor<sup>9+</sup>](#constructor9) instead.
@@ -765,11 +776,12 @@ Compares this **RationalNumber** object with a given object.
| number | Returns **0** if the two objects are equal; returns **1** if the given object is less than this object; return **-1** if the given object is greater than this object.|
> This API is deprecated since API version 9. You are advised to use [getCommonFactor9+](#getcommonfactor9) instead.
static getCommonDivisor(number1: number,number2: number): number
Obtains the greatest common divisor of two specified integers.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getCommonFactor<sup>9+</sup>](#getcommonfactor9) instead.
@@ -891,10 +907,11 @@ Obtains the numerator of this **RationalNumber** object.
| number | Numerator of this **RationalNumber** object.|
**Example**
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.getNumerator();
```
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.getNumerator();
```
### getDenominator<sup>8+</sup>
...
...
@@ -911,10 +928,11 @@ Obtains the denominator of this **RationalNumber** object.
| number | Denominator of this **RationalNumber** object.|
**Example**
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.getDenominator();
```
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.getDenominator();
```
### isZero<sup>8+</sup>
...
...
@@ -931,10 +949,11 @@ Checks whether this **RationalNumber** object is **0**.
| boolean | Returns **true** if the value of this **RationalNumber** object is **0**; returns **false** otherwise.|
**Example**
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.isZero();
```
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.isZero();
```
### isNaN<sup>8+</sup>
...
...
@@ -951,10 +970,11 @@ Checks whether this **RationalNumber** object is a Not a Number (NaN).
| boolean | Returns **true** if this **RationalNumber** object is a NaN (the denominator and numerator are both **0**); returns **false** otherwise.|
**Example**
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.isNaN();
```
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.isNaN();
```
### isFinite<sup>8+</sup>
...
...
@@ -971,10 +991,11 @@ Checks whether this **RationalNumber** object represents a finite value.
| boolean | Returns **true** if this **RationalNumber** object represents a finite value (the denominator is not **0**); returns **false** otherwise.|
**Example**
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.isFinite();
```
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.isFinite();
```
### toString<sup>8+</sup>
...
...
@@ -991,10 +1012,11 @@ Obtains the string representation of this **RationalNumber** object.
| string | Returns **NaN** if the numerator and denominator of this object are both **0**; returns a string in Numerator/Denominator format otherwise, for example, **3/5**.|
**Example**
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.toString();
```
```js
letrationalNumber=newutil.RationalNumber(1,2);
letresult=rationalNumber.toString();
```
## LRUCache<sup>9+</sup>
...
...
@@ -1005,22 +1027,22 @@ Obtains the string representation of this **RationalNumber** object.
| V \| undefined | Returns an **Optional** object containing the removed key-value pair if the key exists in the buffer; returns an empty **Optional** object otherwise. If the key is null, an exception will be thrown.|
| V \| undefined | Returns an **Optional** object containing the removed key-value pair if the key exists in the cache; returns an empty **Optional** object otherwise. If the key is null, an exception will be thrown.|
**Example**
...
...
@@ -1412,10 +1434,10 @@ Performs subsequent operations after a value is removed.
| isEvict | boolean | No | Whether the buffer capacity is insufficient. If the value is **true**, this method is called due to insufficient capacity. |
| isEvict | boolean | Yes | Whether the cache capacity is insufficient. If the value is **true**, this method is called due to insufficient capacity. |
| key | K | Yes | Key removed. |
| value | V | Yes | Value removed. |
| newValue | V | No | New value for the key if the **put()** method is called and the key to be added already exists. In other cases, this parameter is left blank.|
| newValue | V | Yes | New value for the key if the **put()** method is called and the key to be added already exists. In other cases, this parameter is left blank.|
| boolean | Returns **true** if the buffer contains the specified key; returns **false** otherwise.|
| boolean | Returns **true** if the cache contains the specified key; returns **false** otherwise.|
**Example**
```js
letpro=newutil.LRUCache();
pro.put(2,10);
letresult=pro.contains(20);
letobj={1:"key"};
letresult=pro.contains(obj);
```
...
...
@@ -1545,7 +1568,7 @@ let result = pro[Symbol.iterator]();
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [LRUCache9+](#lrucache9) instead.
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [LRUCache<sup>9+</sup>](#lrucache9) instead.
### Attributes
...
...
@@ -1556,6 +1579,7 @@ let result = pro[Symbol.iterator]();
| length | number | Yes| No| Total number of values in this buffer.|
**Example**
```js
letpro=newutil.LruBuffer();
pro.put(2,10);
...
...
@@ -1565,14 +1589,14 @@ let result = pro[Symbol.iterator]();
### constructor<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [constructor9+](#constructor9) instead.
constructor(capacity?: number)
A constructor used to create a **LruBuffer** instance. The default capacity of the buffer is 64.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [constructor<sup>9+</sup>](#constructor9) instead.
@@ -1582,20 +1606,21 @@ A constructor used to create a **LruBuffer** instance. The default capacity of t
| capacity | number | No| Capacity of the **LruBuffer** to create.|
**Example**
```js
letlrubuffer=newutil.LruBuffer();
```
### updateCapacity<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [updateCapacity9+](#updatecapacity9) instead.
updateCapacity(newCapacity: number): void
Changes the **LruBuffer** capacity. If the new capacity is less than or equal to **0**, an exception will be thrown.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [updateCapacity<sup>9+</sup>](#updatecapacity9) instead.
@@ -1629,6 +1655,7 @@ Obtains the string representation of this **LruBuffer** object.
| string | String representation of this **LruBuffer** object.|
**Example**
```js
letpro=newutil.LruBuffer();
pro.put(2,10);
...
...
@@ -1639,14 +1666,14 @@ Obtains the string representation of this **LruBuffer** object.
### getCapacity<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [getCapacity9+](#getcapacity9) instead.
getCapacity(): number
Obtains the capacity of this buffer.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getCapacity<sup>9+</sup>](#getcapacity9) instead.
@@ -1683,14 +1711,14 @@ Clears key-value pairs from this buffer. The **afterRemoval()** method will be c
### getCreateCount<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [getCreateCount9+](#getcreatecount9) instead.
getCreateCount(): number
Obtains the number of return values for **createDefault()**.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getCreateCount<sup>9+</sup>](#getcreatecount9) instead.
@@ -1700,6 +1728,7 @@ Obtains the number of return values for **createDefault()**.
| number | Number of return values for **createDefault()**.|
**Example**
```js
letpro=newutil.LruBuffer();
pro.put(1,8);
...
...
@@ -1708,14 +1737,14 @@ Obtains the number of return values for **createDefault()**.
### getMissCount<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [getMissCount9+](#getmisscount9) instead.
getMissCount(): number
Obtains the number of times that the queried values are mismatched.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getMissCount<sup>9+</sup>](#getmisscount9) instead.
@@ -1725,6 +1754,7 @@ Obtains the number of times that the queried values are mismatched.
| number | Number of times that the queried values are mismatched.|
**Example**
```js
letpro=newutil.LruBuffer();
pro.put(2,10);
...
...
@@ -1734,14 +1764,14 @@ Obtains the number of times that the queried values are mismatched.
### getRemovalCount<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [getRemovalCount9+](#getremovalcount9) instead.
getRemovalCount(): number
Obtains the number of removals from this buffer.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getRemovalCount<sup>9+</sup>](#getremovalcount9) instead.
@@ -1751,6 +1781,7 @@ Obtains the number of removals from this buffer.
| number | Number of removals from the buffer.|
**Example**
```js
letpro=newutil.LruBuffer();
pro.put(2,10);
...
...
@@ -1761,14 +1792,14 @@ Obtains the number of removals from this buffer.
### getMatchCount<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [getMatchCount9+](#getmatchcount9) instead.
getMatchCount(): number
Obtains the number of times that the queried values are matched.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getMatchCount<sup>9+</sup>](#getmatchcount9) instead.
@@ -1778,6 +1809,7 @@ Obtains the number of times that the queried values are matched.
| number | Number of times that the queried values are matched.|
**Example**
```js
letpro=newutil.LruBuffer();
pro.put(2,10);
...
...
@@ -1787,14 +1819,14 @@ Obtains the number of times that the queried values are matched.
### getPutCount<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [getPutCount9+](#getputcount9) instead.
getPutCount(): number
Obtains the number of additions to this buffer.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getPutCount<sup>9+</sup>](#getputcount9) instead.
@@ -1892,6 +1927,7 @@ Adds a key-value pair to this buffer.
| V | Returns the existing value if the key already exists; returns the value added otherwise. If the key or value is null, an exception will be thrown. |
**Example**
```js
letpro=newutil.LruBuffer();
letresult=pro.put(2,10);
...
...
@@ -1899,14 +1935,14 @@ Adds a key-value pair to this buffer.
### values<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [values9+](#values9) instead.
values(): V[]
Obtains all values in this buffer, listed from the most to the least recently accessed.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [values<sup>9+</sup>](#values9) instead.
Performs subsequent operations after a value is removed.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [afterRemoval<sup>9+</sup>](#afterremoval9) instead.
| isEvict | boolean | No| Whether the buffer capacity is insufficient. If the value is **true**, this method is called due to insufficient capacity.|
| isEvict | boolean | Yes| Whether the buffer capacity is insufficient. If the value is **true**, this method is called due to insufficient capacity.|
| key | K | Yes| Key removed.|
| value | V | Yes| Value removed.|
| newValue | V | No| New value for the key if the **put()** method is called and the key to be added already exists. In other cases, this parameter is left blank.|
| newValue | V | Yes| New value for the key if the **put()** method is called and the key to be added already exists. In other cases, this parameter is left blank.|
@@ -2047,6 +2086,7 @@ Checks whether this buffer contains the specified key.
| boolean | Returns **true** if the buffer contains the specified key; returns **false** otherwise.|
**Example**
```js
letpro=newutil.LruBuffer();
pro.put(2,10);
...
...
@@ -2055,14 +2095,14 @@ Checks whether this buffer contains the specified key.
### createDefault<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [createDefault9+](#createdefault9) instead.
createDefault(key: K): V
Creates a value if the value of the specified key is not available.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [createDefault<sup>9+</sup>](#createdefault9) instead.
Obtains a two-dimensional array in key-value pairs.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [Symbol.iterator<sup>9+</sup>](#symboliterator9) instead.
| range | [ScopeHelper](#scopehelper9) | Yes | **Scope** specified.|
**Return value**
...
...
@@ -2528,18 +2572,19 @@ let result = range.clamp(tempMiDF);
> **NOTE**
>
> This class is deprecated since API version 9. You are advised to use [ScopeHelper9+](#scopehelper9) instead.
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [ScopeHelper<sup>9+</sup>](#scopehelper9) instead.
### constructor<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [constructor9+](#constructor9) instead.
A constructor used to create a **Scope** object with the specified upper and lower limits.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [constructor<sup>9+</sup>](#constructor9) instead.
@@ -2903,6 +2956,7 @@ Limits a value to this **Scope**.
| [ScopeType](#scopetype8) | Returns **lowerObj** if the specified value is less than the lower limit; returns **upperObj** if the specified value is greater than the upper limit; returns the specified value if it is within this **Scope**.|
> This class is deprecated since API version 9. You are advised to use [Base64Helper9+](#base64helper9) instead.
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [Base64Helper<sup>9+</sup>](#base64helper9) instead.
### constructor<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [constructor9+](#constructor9) instead.
constructor()
A constructor used to create a **Base64** object.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [constructor<sup>9+</sup>](#constructor9) instead.
> This API is deprecated since API version 9. You are advised to use [encodeSync9+](#encodesync9) instead.
encodeSync(src: Uint8Array): Uint8Array
Encodes the input content.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [encodeSync<sup>9+</sup>](#encodesync9) instead.
@@ -3170,14 +3225,14 @@ Encodes the input content.
### encodeToStringSync<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [encodeToStringSync9+](#encodetostringsync9) instead.
encodeToStringSync(src: Uint8Array): string
Encodes the input content.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [encodeToStringSync<sup>9+</sup>](#encodetostringsync9) instead.
@@ -3201,14 +3257,14 @@ Encodes the input content.
### decodeSync<sup>(deprecated)</sup>
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [decodeSync9+](#decodesync9) instead.
decodeSync(src: Uint8Array | string): Uint8Array
Decodes the input content.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [decodeSync<sup>9+</sup>](#decodesync9) instead.
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [encodeToString<sup>9+</sup>](#encodetostring9) instead.