OpenHarmony语言基础类库【@ohos.util (util工具函数)】

@ohos.util (util工具函数)

该模块主要提供常用的工具函数，实现字符串编解码（[TextEncoder])，[TextDecoder]）、有理数运算（[RationalNumber8+]）、缓冲区管理（[LRUCache9+]）、范围判断（[ScopeHelper9+]）、Base64编解码（[Base64Helper9+]）、内置对象类型检查（[types8+]）等功能。

说明：

本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

复制代码

import util from '@ohos.util';

鸿蒙开发指导文档：gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md点击或者复制转到。

util.format9+

format(format: string, ...args: Object[]): string

通过式样化字符串对输入的内容按特定格式输出。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
format	string	是	格式化字符串，可以包含零个或多个占位符，用于指定要插入的参数的位置和格式。
...args	Object[]	否	替换format参数中占位符的数据，此参数缺失时，默认返回第一个参数。

返回值：

类型	说明
string	格式化后的字符串。

格式说明符：

格式说明符	说明
%s	将参数转换为字符串，用于除Object，BigInt和-0之外的所有值。
%d	将参数作为十进制整数进行格式化输出，用于除Symbol和BigInt之外的所有值。
%i	将字符串转换为十进制整数，用于除BigInt和Symbol之外的所有值。
%f	将字符串转换为浮点数，用于除Bigint和Symbol之外的所有值。
%j	将JavaScript对象转换为JSON字符串进行格式化输出。
%o	用于将JavaScript对象进行格式化输出，将对象转换为字符串表示，但不包含对象的原型链信息。
%O	用于将JavaScript对象进行格式化输出，将对象转换为字符串表示。
%c	只在浏览器环境中有效。其余环境不会产生样式效果。
%%	转义百分号的特殊格式化占位符。

示例：

复制代码

let name = 'John';
let age = 20;
let formattedString = util.format('My name is %s and I am %s years old', name, age);
console.log(formattedString);
// 输出结果：My name is John and I am 20 years old
let num = 10.5;
formattedString = util.format('The number is %d', num);
console.log(formattedString);
// 输出结果：The number is 10.5
num = 100.5;
formattedString = util.format('The number is %i', num);
console.log(formattedString);
// 输出结果：The number is 100
const pi = 3.141592653;
formattedString = util.format('The value of pi is %f', pi);
console.log(formattedString);
// 输出结果：The value of pi is 3.141592653
const obj = { name: 'John', age: 20 };
formattedString = util.format('The object is %j', obj);
console.log(formattedString);
// 输出结果：The object is {"name":"John","age":20}
const person = {
  name: 'John',
  age: 20,
  address: {
    city: 'New York',
    country: 'USA'
  }
};
console.log(util.format('Formatted object using %%O: %O', person));
console.log(util.format('Formatted object using %%o: %o', person));
/*
输出结果：
Formatted object using %O: { name: 'John',
  age: 20,
  address:
  { city: 'New York',
    country: 'USA' } }
Formatted object using %o: { name: 'John',
  age: 20,
  address:
  { city: 'New York',
    country: 'USA' } }
*/
const percentage = 80;
let arg = 'homework';
formattedString = util.format('John finished %d%% of the %s', percentage, arg);
console.log(formattedString);
// 输出结果：John finished 80% of the homework

util.errnoToString9+

errnoToString(errno: number): string

获取系统错误码对应的详细信息。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
errno	number	是	系统发生错误产生的错误码。

返回值：

类型	说明
string	错误码对应的详细信息。

示例：

复制代码

let errnum = -1; // -1 : a system error number
let result = util.errnoToString(errnum);
console.log("result = " + result);

部分错误码及信息示例：

错误码	信息
-1	operation not permitted
-2	no such file or directory
-3	no such process
-4	interrupted system call
-5	i/o error
-11	resource temporarily unavailable
-12	not enough memory
-13	permission denied
-100	network is down

util.callbackWrapper

callbackWrapper(original: Function): (err: Object, value: Object )=>void

对异步函数进行回调化处理，回调中第一个参数将是拒绝原因（如果 Promise 已解决，则为 null），第二个参数将是已解决的值。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
original	Function	是	异步函数。

返回值：

类型	说明
Function	返回一个回调函数，该函数第一个参数err是拒绝原因（如果 Promise 已解决，则为 null），第二个参数value是已解决的值。

示例：

复制代码

async function fn() {
 return 'hello world';
}
let cb = util.callbackWrapper(fn);
cb(1, (err, ret) => {
 if (err) throw err;
 console.log(ret);
});

util.promisify9+

promisify(original: (err: Object, value: Object) => void): Function

对异步函数处理并返回一个promise的函数。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
original	Function	是	回调函数中第一个参数err是拒绝原因（如果 Promise 已解决，则为 null），第二个参数value是已解决的值。

返回值：

类型	说明
Function	返回一个 Promise 的函数。

示例：

复制代码

async function fn() {
  return 'hello world';
}
const addCall = util.promisify(util.callbackWrapper(fn));
(async () => {
  try {
    let res: string = await addCall();
    console.log(res);
  } catch (err) {
    console.log(err);
  }
})();

util.generateRandomUUID9+

generateRandomUUID(entropyCache?: boolean): string

使用加密安全随机数生成器生成随机的RFC 4122版本4的string类型UUID。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
entropyCache	boolean	否	是否使用已缓存的UUID，默认true。

返回值：

类型	说明
string	表示此UUID的字符串。

示例：

复制代码

let uuid = util.generateRandomUUID(true);
console.log("RFC 4122 Version 4 UUID:" + uuid);
// 输出：
// RFC 4122 Version 4 UUID:88368f2a-d5db-47d8-a05f-534fab0a0045

util.generateRandomBinaryUUID9+

generateRandomBinaryUUID(entropyCache?: boolean): Uint8Array

使用加密安全随机数生成器生成随机的RFC 4122版本4的Uint8Array类型UUID。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
entropyCache	boolean	否	是否使用已缓存的UUID，默认true。

返回值：

类型	说明
Uint8Array	表示此UUID的Uint8Array值。

示例：

复制代码

let uuid = util.generateRandomBinaryUUID(true);
console.log(JSON.stringify(uuid));
// 输出：
// 138,188,43,243,62,254,70,119,130,20,235,222,199,164,140,150

util.parseUUID9+

parseUUID(uuid: string): Uint8Array

将generateRandomUUID生成的string类型UUID转换为generateRandomBinaryUUID生成的Uint8Array类型UUID，如RFC 4122版本4中所述。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
uuid	string	是	UUID字符串。

返回值：

类型	说明
Uint8Array	返回表示此UUID的Uint8Array，如果解析失败，则抛出SyntaxError。

示例：

复制代码

let uuid = util.parseUUID("84bdf796-66cc-4655-9b89-d6218d100f9c");
console.log(JSON.stringify(uuid));
// 输出：
// 132,189,247,150,102,204,70,85,155,137,214,33,141,16,15,156

util.printf(deprecated)

printf(format: string, ...args: Object[]): string

通过式样化字符串对输入的内容按特定格式输出。

说明：

从API version 7开始支持，从API version 9开始废弃，建议使用[util.format9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
format	string	是	式样化字符串。
...args	Object[]	否	替换式样化字符串通配符的数据，此参数缺失时，默认返回第一个参数。

返回值：

类型	说明
string	按特定格式式样化后的字符串。

示例：

复制代码

let res = util.printf("%s", "hello world!");
console.log(res);

util.getErrorString(deprecated)

getErrorString(errno: number): string

获取系统错误码对应的详细信息。

说明：

从API version 7开始支持，从API version 9开始废弃，建议使用[util.errnoToString9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
errno	number	是	系统发生错误产生的错误码。

返回值：

类型	说明
string	错误码对应的详细信息。

示例：

复制代码

let errnum = -1; // -1 : a system error number
let result = util.getErrorString(errnum);
console.log("result = " + result);

util.promiseWrapper(deprecated)

promiseWrapper(original: (err: Object, value: Object) => void): Object

对异步函数处理并返回一个promise的版本。

说明：

此接口不可用，建议使用[util.promisify9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
original	Function	是	异步函数。

返回值：

类型	说明
Function	采用遵循常见的错误优先的回调风格的函数（也就是将 (err, value) => ... 回调作为最后一个参数），并返回一个返回 promise 的版本。

TextDecoder

TextDecoder用于将字节数组解码为字符串，可以处理多种编码格式，包括utf-8、utf-16le/be、iso-8859和windows-1251等不同的编码格式。

属性

系统能力： 以下各项对应的系统能力均为SystemCapability.Utils.Lang。

名称	类型	可读	可写	说明
encoding	string	是	否	编码格式。 - 支持格式：utf-8、ibm866、iso-8859-2、iso-8859-3、iso-8859-4、iso-8859-5、iso-8859-6、iso-8859-7、iso-8859-8、iso-8859-8-i、iso-8859-10、iso-8859-13、iso-8859-14、iso-8859-15、koi8-r、koi8-u、macintosh、windows-874、windows-1250、windows-1251、windows-1252、windows-1253、windows-1254、windows-1255、windows-1256、windows-1257、windows-1258、x-mac-cyrilli、gbk、gb18030、big5、euc-jp、iso-2022-jp、shift_jis、euc-kr、utf-16be、utf-16le。
fatal	boolean	是	否	是否显示致命错误。
ignoreBOM	boolean	是	否	是否忽略BOM（byte order marker）标记，默认值为false ，表示解码结果包含BOM标记。

constructor9+

constructor()

TextDecoder的构造函数。

系统能力： SystemCapability.Utils.Lang

示例：

复制代码

let result = new util.TextDecoder();
let retStr = result.encoding;

create9+

static create(encoding?: string,options?: { fatal?: boolean; ignoreBOM?: boolean }): TextDecoder

替代有参构造功能。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
encoding	string	否	编码格式，默认值是'utf-8'。
options	Object	否	解码相关选项参数，存在两个属性fatal和ignoreBOM。

表1.1options

名称	参数类型	必填	说明
fatal	boolean	否	是否显示致命错误，默认值是false。
ignoreBOM	boolean	否	是否忽略BOM标记，默认值是false。

示例：

复制代码

let result = util.TextDecoder.create('utf-8', { ignoreBOM : true })
let retStr = result.encoding

decodeWithStream9+

decodeWithStream(input: Uint8Array, options?: { stream?: boolean }): string

通过输入参数解码后输出对应文本。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
input	Uint8Array	是	符合格式需要解码的数组。
options	Object	否	解码相关选项参数。

表2 options

名称	参数类型	必填	说明
stream	boolean	否	在随后的decodeWithStream()调用中是否跟随附加数据块。如果以块的形式处理数据，则设置为true；如果处理最后的数据块或数据未分块，则设置为false。默认为false。

返回值：

类型	说明
string	解码后的数据。

示例：

复制代码

let textDecoder = new util.TextDecoder("utf-8",{ignoreBOM: true});
let result = new Uint8Array(6);
result[0] = 0xEF;
result[1] = 0xBB;
result[2] = 0xBF;
result[3] = 0x61;
result[4] = 0x62;
result[5] = 0x63;
console.log("input num:");
let retStr = textDecoder.decodeWithStream( result , {stream: false});
console.log("retStr = " + retStr);

constructor(deprecated)

constructor(encoding?: string, options?: { fatal?: boolean; ignoreBOM?: boolean })

TextDecoder的构造函数。

说明：

从API version 7开始支持，从API version 9开始废弃，建议使用[create9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
encoding	string	否	编码格式，默认值是'utf-8'。
options	Object	否	解码相关选项参数，存在两个属性fatal和ignoreBOM。

表1 options

名称	参数类型	必填	说明
fatal	boolean	否	是否显示致命错误，默认值是false。
ignoreBOM	boolean	否	是否忽略BOM标记，默认值是false。

示例：

复制代码

let textDecoder = new util.TextDecoder("utf-8",{ignoreBOM: true});

decode(deprecated)

decode(input: Uint8Array, options?: { stream?: false }): string

通过输入参数解码后输出对应文本。

说明：

从API version 7开始支持，从API version 9开始废弃，建议使用[decodeWithStream9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
input	Uint8Array	是	符合格式需要解码的数组。
options	Object	否	解码相关选项参数。

表2 options

名称	参数类型	必填	说明
stream	boolean	否	在随后的decode()调用中是否跟随附加数据块。如果以块的形式处理数据，则设置为true；如果处理最后的数据块或数据未分块，则设置为false。默认为false。

返回值：

类型	说明
string	解码后的数据。

示例：

复制代码

let textDecoder = new util.TextDecoder("utf-8",{ignoreBOM: true});
let result = new Uint8Array(6);
result[0] = 0xEF;
result[1] = 0xBB;
result[2] = 0xBF;
result[3] = 0x61;
result[4] = 0x62;
result[5] = 0x63;
console.log("input num:");
let retStr = textDecoder.decode( result , {stream: false});
console.log("retStr = " + retStr);

TextEncoder

TextEncoder用于将字符串编码为字节数组，支持多种编码格式，包括utf-8、utf-16le/be等。需要注意的是，在使用TextEncoder进行编码时，不同编码格式下字符所占的字节数是不同的。例如，utf-8编码下中文字符通常占3个字节，而utf-16le/be编码下中文字符通常占2个字节。因此，在使用TextEncoder时需要明确指定要使用的编码格式，以确保编码结果正确。

属性

系统能力： 以下各项对应的系统能力均为SystemCapability.Utils.Lang。

名称	类型	可读	可写	说明
encoding	string	是	否	编码格式，默认值是'utf-8'。

constructor

constructor()

TextEncoder的构造函数。

系统能力： SystemCapability.Utils.Lang

示例：

复制代码

let textEncoder = new util.TextEncoder();

constructor9+

constructor(encoding?: string)

TextEncoder的构造函数。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
encoding	string	否	编码格式，默认值为'utf-8'。

示例：

复制代码

let textEncoder = new util.TextEncoder("utf-8");

encodeInto9+

encodeInto(input?: string): Uint8Array

通过输入参数编码后输出对应文本。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
input	string	否	需要编码的字符串，默认值是空字符串。

返回值：

类型	说明
Uint8Array	返回编码后的文本。

示例：

复制代码

let textEncoder = new util.TextEncoder();
let buffer = new ArrayBuffer(20);
let result = new Uint8Array(buffer);
result = textEncoder.encodeInto("\uD800¥¥");

encodeIntoUint8Array9+

encodeIntoUint8Array(input: string, dest: Uint8Array, ): { read: number; written: number }

放置生成的UTF-8编码文本。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
input	string	是	需要编码的字符串。
dest	Uint8Array	是	Uint8Array对象实例，用于将生成的UTF-8编码文本放入其中。

返回值：

类型	说明
Uint8Array	返回编码后的文本。

示例：

复制代码

let that = new util.TextEncoder()
let buffer = new ArrayBuffer(4)
let dest = new Uint8Array(buffer)
let result = new Object()
result = that.encodeIntoUint8Array('abcd', dest)

encodeInto(deprecated)

encodeInto(input: string, dest: Uint8Array, ): { read: number; written: number }

放置生成的UTF-8编码文本。

说明：

从API version 7开始支持，从API version 9开始废弃，建议使用[encodeIntoUint8Array9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
input	string	是	需要编码的字符串。
dest	Uint8Array	是	Uint8Array对象实例，用于将生成的UTF-8编码文本放入其中。

返回值：

类型	说明
Uint8Array	返回编码后的文本。

示例：

复制代码

let that = new util.TextEncoder()
let buffer = new ArrayBuffer(4)
let dest = new Uint8Array(buffer)
let result = new Object()
result = that.encodeInto('abcd', dest)

encode(deprecated)

encode(input?: string): Uint8Array

通过输入参数编码后输出对应文本。

说明：

从API version 7开始支持，从API version 9开始废弃，建议使用[encodeInto9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
input	string	否	需要编码的字符串，默认值是空字符串。

返回值：

类型	说明
Uint8Array	返回编码后的文本。

示例：

复制代码

let textEncoder = new util.TextEncoder();
let buffer = new ArrayBuffer(20);
let result = new Uint8Array(buffer);
result = textEncoder.encode("\uD800¥¥");

RationalNumber8+

RationalNumber主要是对有理数进行比较，获取分子分母等方法。例如使用toString()方法可以将有理数转换为字符串形式，使用该类可以方便地进行有理数的各种操作。

constructor9+

constructor()

RationalNumber的构造函数。

系统能力： SystemCapability.Utils.Lang

示例：

复制代码

let rationalNumber = new util.RationalNumber();

parseRationalNumber9+

parseRationalNumber(numerator: number,denominator: number): RationalNumber

替代原有参构造的参数处理。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
numerator	number	是	分子，整数类型。
denominator	number	是	分母，整数类型。

示例：

复制代码

let rationalNumber = util.RationalNumber.parseRationalNumber(1,2)

createRationalFromString8+

static createRationalFromString(rationalString: string): RationalNumber

基于给定的字符串创建一个RationalNumber对象。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
rationalString	string	是	字符串格式。

返回值：

类型	说明
object	返回有理数类的对象。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let rational = util.RationalNumber.createRationalFromString("3/4");

compare9+

compare(another: RationalNumber): number

将当前的RationalNumber对象与给定的对象进行比较。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
another	RationalNumber	是	其他的有理数对象。

返回值：

类型	说明
number	如果两个对象相等，则返回0；如果给定对象小于当前对象，则返回1；如果给定对象大于当前对象，则返回-1。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let rational = util.RationalNumber.createRationalFromString("3/4");
let result = rationalNumber.compare(rational);

valueOf8+

valueOf(): number

以整数形式或者浮点数的形式获取当前RationalNumber对象的值。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
number	返回整数或者浮点数的值。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let result = rationalNumber.valueOf();

equals8+

equals(obj: Object): boolean

将当前的RationalNumber对象与给定的对象进行比较是否相等。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
obj	Object	是	其他类型对象。

返回值：

类型	说明
boolean	如果给定对象与当前对象相同，则返回true；否则返回false。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let rational = util.RationalNumber.createRationalFromString("3/4");
let result = rationalNumber.equals(rational);

getCommonFactor9+

getCommonFactor(number1: number,number2: number): number

获取两个指定整数的最大公约数。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
number1	number	是	整数类型。
number2	number	是	整数类型。

返回值：

类型	说明
number	返回两个给定数字的最大公约数。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let result = util.RationalNumber.getCommonFactor(4,6);

getNumerator8+

getNumerator(): number

获取当前RationalNumber对象的分子。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
number	返回RationalNumber对象的分子的值。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let result = rationalNumber.getNumerator();

getDenominator8+

getDenominator(): number

获取当前RationalNumber对象的分母。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
number	返回RationalNumber对象的分母的值。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let result = rationalNumber.getDenominator();

isZero8+

isZero():boolean

检查当前RationalNumber对象是否为0。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
boolean	如果当前对象表示的值为0，则返回true；否则返回false。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let result = rationalNumber.isZero();

isNaN8+

isNaN(): boolean

检查当前RationalNumber对象是否表示非数字(NaN)值。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
boolean	如果分母和分子都为0，则返回true；否则返回false。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let result = rationalNumber.isNaN();

isFinite8+

isFinite():boolean

检查当前RationalNumber对象是否表示一个有限值。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
boolean	如果分母不为0，则返回true；否则返回false。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let result = rationalNumber.isFinite();

toString8+

toString(): string

获取当前RationalNumber对象的字符串表示形式。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
string	返回Numerator/Denominator格式的字符串，例如3/5，如果当前对象的分子和分母都为0，则返回NaN。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let result = rationalNumber.toString();

constructor(deprecated)

constructor(numerator: number,denominator: number)

RationalNumber的构造函数。

说明：

从API version 8开始支持，从API version 9开始废弃，建议使用[constructor9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
numerator	number	是	分子，整数类型。
denominator	number	是	分母，整数类型。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);

compareTo(deprecated)

compareTo(another: RationalNumber): number

将当前的RationalNumber对象与给定的对象进行比较。

说明：

从API version 8开始支持，从API version 9开始废弃，建议使用[compare9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
another	RationalNumber	是	其他的有理数对象。

返回值：

类型	说明
number	如果两个对象相等，则返回0；如果给定对象小于当前对象，则返回1；如果给定对象大于当前对象，则返回-1。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let rational = util.RationalNumber.createRationalFromString("3/4");
let result = rationalNumber.compareTo(rational);

getCommonDivisor(deprecated)

static getCommonDivisor(number1: number,number2: number): number

获取两个指定整数的最大公约数。

说明：

从API version 8开始支持，从API version 9开始废弃，建议使用[getCommonFactor9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
number1	number	是	整数类型。
number2	number	是	整数类型。

返回值：

类型	说明
number	返回两个给定数字的最大公约数。

示例：

复制代码

let rationalNumber = new util.RationalNumber(1,2);
let result = util.RationalNumber.getCommonDivisor(4,6);

LRUCache9+

LRUCache用于在缓存空间不够的时候，将近期最少使用的数据替换为新数据。此设计基于资源访问的考虑：近期访问的数据，可能在不久的将来会再次访问。于是最少访问的数据就是价值最小的数据，是最应该踢出缓存空间的数据。

属性

系统能力： 以下各项对应的系统能力均为SystemCapability.Utils.Lang。

名称	类型	可读	可写	说明
length	number	是	否	当前缓冲区中值的总数。

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
pro.put(1,8);
let result = pro.length;

constructor9+

constructor(capacity?: number)

默认构造函数用于创建一个新的LruBuffer实例，默认容量为64。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
capacity	number	否	指示要为缓冲区自定义的容量。

示例：

复制代码

let lrubuffer= new util.LRUCache();

updateCapacity9+

updateCapacity(newCapacity: number): void

将缓冲区容量更新为指定容量，如果newCapacity小于或等于0，则抛出异常。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
newCapacity	number	是	指示要为缓冲区自定义的容量。

示例：

复制代码

let pro = new util.LRUCache();
pro.updateCapacity(100);

toString9+

toString(): string

返回对象的字符串表示形式。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
string	返回对象的字符串表示形式。

示例：

复制代码

let pro: util.LRUCache<number, number> = new util.LRUCache();
pro.put(2,10);
pro.get(2);
pro.get(3);
console.log(pro.toString());
// 输出结果：LRUCache[ maxSize = 64, hits = 1, misses = 1, hitRate = 50% ]
// maxSize: 缓存区最大值 hits: 查询值匹配成功的次数 misses: 查询值匹配失败的次数 hitRate: 查询值匹配率

getCapacity9+

getCapacity(): number

获取当前缓冲区的容量。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
number	返回当前缓冲区的容量。

示例：

复制代码

let pro = new util.LRUCache();
let result = pro.getCapacity();

clear9+

clear(): void

从当前缓冲区清除键值对。后续会调用afterRemoval()方法执行后续操作。

系统能力： SystemCapability.Utils.Lang

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
let result = pro.length;
pro.clear();

getCreateCount9+

getCreateCount(): number

获取创建对象的次数。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
number	返回创建对象的次数。

示例：

复制代码

// 创建新类ChildLRUCache继承LRUCache，重写createDefault方法，返回一个非undefined的值。
class ChildLRUCache extends util.LRUCache<number, number> {
  constructor() {
    super();
  }

  createDefault(key: number): number {
    return key;
  }
}
let lru = new ChildLRUCache();
lru.put(2,10);
lru.get(3);
lru.get(5);
let res = lru.getCreateCount();

getMissCount9+

getMissCount(): number

获取查询值不匹配的次数。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
number	返回查询值不匹配的次数。

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
pro.get(2);
let result = pro.getMissCount();

getRemovalCount9+

getRemovalCount(): number

获取缓冲区键值对回收的次数。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
number	返回缓冲区键值对回收的次数。

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
pro.updateCapacity(2);
pro.put(50,22);
let result = pro.getRemovalCount();

getMatchCount9+

getMatchCount(): number

获取查询值匹配成功的次数。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
number	返回查询值匹配成功的次数。

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
pro.get(2);
let result = pro.getMatchCount();

getPutCount9+

getPutCount(): number

获取将值添加到缓冲区的次数。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
number	返回将值添加到缓冲区的次数。

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
let result = pro.getPutCount();

isEmpty9+

isEmpty(): boolean

检查当前缓冲区是否为空。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
boolean	如果当前缓冲区不包含任何值，则返回true。

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
let result = pro.isEmpty();

get9+

get(key: K): V | undefined

表示要查询的键。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
key	K	是	要查询的键。

返回值：

| 类型 | 说明 |
|----|-----------|----------------------------------------|
| V | undefined | 如果指定的键存在于缓冲区中，则返回与键关联的值；否则返回undefined。 |

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
let result  = pro.get(2);

put9+

put(key: K,value: V): V

将键值对添加到缓冲区。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
key	K	是	要添加的密钥。
value	V	是	指示与要添加的键关联的值。

返回值：

类型	说明
V	返回与添加的键关联的值；如果要添加的键已经存在，则返回原始值，如果键或值为空，则抛出此异常。

示例：

复制代码

let pro = new util.LRUCache();
let result = pro.put(2,10);

values9+

values(): V[]

获取当前缓冲区中所有值从最近访问到最近最少访问的顺序列表。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
V []	按从最近访问到最近最少访问的顺序返回当前缓冲区中所有值的列表。

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
pro.put(2,"anhu");
pro.put("afaf","grfb");
let result = pro.values();

keys9+

keys(): K[]

获取当前缓冲区中所有键从最近访问到最近最少访问的升序列表。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
K []	按升序返回当前缓冲区中所有键的列表，从最近访问到最近最少访问。

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
let result = pro.keys();

remove9+

remove(key: K): V | undefined

从当前缓冲区中删除指定的键及其关联的值。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
key	K	是	要删除的密钥。

返回值：

| 类型 | 说明 |
|----|-----------|----------------------------------------------------------------------|
| V | undefined | 返回一个包含已删除键值对的Optional对象；如果key不存在，则返回一个空的Optional对象，如果key为null，则抛出异常。 |

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
let result = pro.remove(20);

afterRemoval9+

afterRemoval(isEvict: boolean,key: K,value: V,newValue: V): void

删除值后执行后续操作。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
isEvict	boolean	是	因容量不足而调用该方法时，参数值为true，其他情况为false。
key	K	是	表示删除的键。
value	V	是	表示删除的值。
newValue	V	是	如果已调用put方法并且要添加的键已经存在，则参数值是关联的新值。其他情况下参数值为空。

示例：

复制代码

class ChildLRUCache<K, V> extends util.LRUCache<K, V> {
  constructor(capacity?: number) {
    super(capacity);
  }

  afterRemoval(isEvict: boolean, key: K, value: V, newValue: V): void {
    if (isEvict === true) {
      console.info('key: ' + key);
      console.info('value: ' + value);
      console.info('newValue: ' + newValue);
    }
  }
}
let lru: ChildLRUCache<number, number>= new ChildLRUCache(2);
lru.put(1, 1);
lru.put(2, 2);
lru.put(3, 3);

contains9+

contains(key: K): boolean

检查当前缓冲区是否包含指定的键。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
key	K	是	表示要检查的键。

返回值：

类型	说明
boolean	如果缓冲区包含指定的键，则返回 true。

示例：

复制代码

let pro = new util.LRUCache();
pro.put(2,10);
let obj = {1:"key"};
let result = pro.contains(obj);

createDefault9+

createDefault(key: K): V

如果未计算特定键的值，则执行后续操作，参数表示丢失的键，返回与键关联的值。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
key	K	是	表示丢失的键。

返回值：

类型	说明
V	返回与键关联的值。

示例：

复制代码

let pro = new util.LRUCache();
let result = pro.createDefault(50);

entries9+

entries(): IterableIterator<[K,V]>

允许迭代包含在这个对象中的所有键值对。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
[K, V]	返回一个可迭代数组。

示例：

复制代码

let pro: util.LRUCache<number, number> = new util.LRUCache();
pro.put(2,10);
pro.put(3,15);
let pair:Iterable<Object[]> = pro.entries();
let arrayValue = Array.from(pair);
for (let value of arrayValue) {
  console.log(value[0]+ ', '+ value[1]);
}

[Symbol.iterator]9+

获取当前缓冲区中所有值从最近访问到最近最少访问的顺序列表。

说明：

从API version 8开始支持，从API version 9开始废弃，建议使用[LRUCache.values9+]替代。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
V []	按从最近访问到最近最少访问的顺序返回当前缓冲区中所有值的列表。

示例：

复制代码

let pro = new util.LruBuffer();
pro.put(2,10);
pro.put(2,"anhu");
pro.put("afaf","grfb");
let result = pro.values();

keys(deprecated)

keys(): K[]

获取当前缓冲区中所有键从最近访问到最近最少访问的升序列表。

说明：

从API version 8开始支持，从API version 9开始废弃，建议使用[LRUCache.keys9+]替代。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
K []	按升序返回当前缓冲区中所有键的列表，从最近访问到最近最少访问。

示例：

复制代码

let pro = new util.LruBuffer();
pro.put(2,10);
let result = pro.keys();

remove(deprecated)

remove(key: K): V | undefined

从当前缓冲区中删除指定的键及其关联的值。

说明：

从API version 8开始支持，从API version 9开始废弃，建议使用[LRUCache.remove9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
key	K	是	要删除的密钥。

返回值：

示例：

复制代码

let pro = new util.LruBuffer();
pro.put(2,10);
let result = pro.remove(20);

afterRemoval(deprecated)

afterRemoval(isEvict: boolean,key: K,value: V,newValue: V): void

删除值后执行后续操作。

说明：

从API version 8开始支持，从API version 9开始废弃，建议使用[LRUCache.afterRemoval9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
isEvict	boolean	是	因容量不足而调用该方法时，参数值为true，其他情况为false。
key	K	是	表示删除的键。
value	V	是	表示删除的值。
newValue	V	是	如果已调用put方法并且要添加的键已经存在，则参数值是关联的新值。其他情况下参数值为空。

示例：

复制代码

class ChildLruBuffer<K, V> extends util.LruBuffer<K, V> {
  constructor(capacity?: number) {
    super(capacity);
  }

  afterRemoval(isEvict: boolean, key: K, value: V, newValue: V): void {
    if (isEvict === true) {
      console.info('key: ' + key);
      console.info('value: ' + value);
      console.info('newValue: ' + newValue);
    }
  }
}
let lru: ChildLruBuffer<number, number> = new ChildLruBuffer(2);
lru.put(11, 1);
lru.put(22, 2);
lru.put(33, 3);

contains(deprecated)

contains(key: K): boolean

检查当前缓冲区是否包含指定的键。

说明：

从API version 8开始支持，从API version 9开始废弃，建议使用[LRUCache.contains9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
key	K	是	表示要检查的键。

返回值：

类型	说明
boolean	如果缓冲区包含指定的键，则返回 true。

示例：

复制代码

let pro = new util.LruBuffer();
pro.put(2,10);
let result = pro.contains(20);

createDefault(deprecated)

createDefault(key: K): V

如果未计算特定键的值，则执行后续操作，参数表示丢失的键，返回与键关联的值。

说明：

从API version 8开始支持，从API version 9开始废弃，建议使用[LRUCache.createDefault9+]替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
key	K	是	表示丢失的键。

返回值：

类型	说明
V	返回与键关联的值。

示例：

复制代码

let pro = new util.LruBuffer();
let result = pro.createDefault(50);

entries(deprecated)

entries(): IterableIterator<[K,V]>

允许迭代包含在这个对象中的所有键值对。

说明：

从API version 8开始支持，从API version 9开始废弃，建议使用[LRUCache.entries9+]替代。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
[K, V]	返回一个可迭代数组。

示例：

复制代码

let pro = new util.LruBuffer();
pro.put(2,10);
let result = pro.entries();