Improve api doc (#13883)

This commit is contained in:
minggo
2022-12-23 11:02:26 +08:00
committed by GitHub
parent 109da649b7
commit dfd6fa8d31
7 changed files with 139 additions and 67 deletions
+3 -3
View File
@@ -28,7 +28,7 @@
* Searches the **ascending sorted** array for an element and returns the index of that element.
* @param array The array to search in.
* @param value The value to search.
* @return The index of the searched element in the sorted array, if found;
* @returns The index of the searched element in the sorted array, if found;
* otherwise, returns the complement of the index of the next element greater than the element to be searched or,
* returns the complement of array's length if no element is greater than the element to be searched or the array is empty.
* @engineInternal
@@ -42,7 +42,7 @@ export function binarySearch (array: number[], value: number) {
* @param array The array to search in.
* @param value The value to search.
* @param EPSILON The epsilon to compare the numbers. Default to `1e-6`.
* @return The index of the searched element in the sorted array, if found;
* @returns The index of the searched element in the sorted array, if found;
* otherwise, returns the complement of the index of the next element greater than the element to be searched or,
* returns the complement of array's length if no element is greater than the element to be searched or the array is empty.
* @engineInternal
@@ -69,7 +69,7 @@ export function binarySearchEpsilon (array: Readonly<ArrayLike<number>>, value:
* @param array The array to search in.
* @param value The value to search.
* @param lessThan Comparison function object which returns ​true if the first argument is less than the second.
* @return The index of the searched element in the sorted array, if found;
* @returns The index of the searched element in the sorted array, if found;
* otherwise, returns the complement of the index of the next element greater than the searching element or,
* returns the complement of array's length if no element is greater than the searching element or the array is empty.
* @engineInternal
+1 -1
View File
@@ -8,7 +8,7 @@ import { assertsArrayIndex } from '../data/utils/asserts';
* @param array @en The array to be rotated. @zh 被修改的数组。
* @param first @en The beginning of the original range. @zh 移动区间的起始坐标。
* @param last @en The end of the original range. @zh 移动区间的结束坐标。
* @return @en The input array. @zh 输入的数组。
* @returns @en The input array. @zh 输入的数组。
* @engineInternal
*/
export function shift<T> (array: T[], first: number, last: number) {
+15 -3
View File
@@ -39,6 +39,13 @@
const getUint8ForString = String.prototype.charCodeAt;
function getUint8ForArray (this: Uint8Array, idx: number) { return this[idx]; }
/**
* @en JS Implementation of MurmurHash2. Original implementation is http://github.com/garycourt/murmurhash-js.
* @zh MurmurHash2 的 JS 实现。原始实现是 http://github.com/garycourt/murmurhash-js 。
* @param input @en ASCII string or a Uint8Array to be hashed. @zh 希望被哈希的 ASCII 字符串或者 Uint8Array.
* @param seed @en Hash seed. Should be a positive integer. @zh 哈希种子。必须是个正整数。
* @returns @en 32-bit positive integer hash. @zh 32位正整数哈希值。
*/
export function murmurhash2_32_gc (input: string | Uint8Array, seed: number) {
let l = input.length;
let h = seed ^ l;
@@ -62,10 +69,15 @@ export function murmurhash2_32_gc (input: string | Uint8Array, seed: number) {
}
switch (l) {
case 3: h ^= (getUint8.call(input, i + 2) & 0xff) << 16;
case 2: h ^= (getUint8.call(input, i + 1) & 0xff) << 8;
case 1: h ^= (getUint8.call(input, i) & 0xff);
case 3: h ^= (getUint8.call(input, i + 2) & 0xff) << 16; break;
case 2: h ^= (getUint8.call(input, i + 1) & 0xff) << 8; break;
case 1:
h ^= (getUint8.call(input, i) & 0xff);
h = (((h & 0xffff) * 0x5bd1e995) + ((((h >>> 16) * 0x5bd1e995) & 0xffff) << 16));
break;
default:
// do nothing, just make VSCode happy.
break;
}
h ^= h >>> 13;
+43 -27
View File
@@ -1,5 +1,5 @@
/*
Copyright (c) 2020 Xiamen Yaji Software Co., Ltd.
Copyright (c) 2020-2022 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
@@ -36,17 +36,17 @@ import { ScalableContainer } from './scalable-container';
export class CachedArray<T> extends ScalableContainer {
/**
* @en
* The array which stores actual content
* The array which stores actual content.
* @zh
* 实际存储数据内容的数组
* 实际存储数据内容的数组。
*/
public array: T[];
/**
* @en
* The actual count of data object
* The actual count of data object.
* @zh
* 实际数据内容数量
* 实际存储的元素数量。
*/
public length = 0;
@@ -54,8 +54,13 @@ export class CachedArray<T> extends ScalableContainer {
private _initSize = 0;
/**
* @param length Initial length
* @param compareFn Comparison function for sorting
* @en Constructor. @zh 构造函数。
* @param length @en Initial length of the CachedArray. @zh CachedArray 的初始长度。
* @param compareFn @en Function used to determine the order of the elements. It is expected to return
* a negative value if the first argument is less than the second argument, zero if they're equal, and a positive
* value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
* @zh 用来确定元素顺序的函数。如果第一个参数小于第二个参数,它应该返回一个负值,如果它们相等,则返回0,否则返回一个正值。
* 如果省略,元素将按 ASCII 字符升序排序。
*/
constructor (length: number, compareFn?: (a: T, b: T) => number) {
super();
@@ -67,10 +72,10 @@ export class CachedArray<T> extends ScalableContainer {
/**
* @en
* Push an element to the end of the array
* Push an element to the end of the array.
* @zh
* 向数组末尾添加一个元素
* @param item The item to be added
* 向数组末尾添加一个元素。
* @param item @en The item to be added. @zh 被添加到数组的元素。
*/
public push (item: T) {
this.array[this.length++] = item;
@@ -80,8 +85,9 @@ export class CachedArray<T> extends ScalableContainer {
* @en
* Pop the last element in the array. The [[length]] will reduce, but the internal array will keep its size.
* @zh
* 弹出数组最后一个元素,CachedArray 的 [[length]] 会减少,但是内部数组的实际长度不变
* @return The last element.
* 弹出数组最后一个元素,CachedArray 的 [[length]] 会减少,但是内部数组的实际长度不变。
* @returns @en The last element of this CachedArray. If CachedArray is empty, will return undefined.
* @zh 数组的最后一个元素。如果数组为空,将返回 undefined。
*/
public pop (): T | undefined {
return this.array[--this.length];
@@ -89,11 +95,12 @@ export class CachedArray<T> extends ScalableContainer {
/**
* @en
* Get the element at the specified index of the array
* Get the element at the specified index of the array.
* @zh
* 得到数组中指定位置的元素
* @param idx The index of the requested element
* @return The element at given index
* 获取数组中指定位置的元素。
* @param idx @en The index of the requested element. @zh 用于获取数组元素的索引。
* @returns @en The element at given index. If idx not in [0, [[length]]) or array is empty, will return undefined.
* @zh 数组下标对应的元素。如果 idx 超出 [0, [[length]]),或者数组是空的,将返回 undefined。
*/
public get (idx: number): T | undefined {
return this.array[idx];
@@ -111,9 +118,9 @@ export class CachedArray<T> extends ScalableContainer {
/**
* @en
* Clear the cache. The [[length]] will be set to 0, and clear the internal array.
* Destroy the array. The [[length]] will be set to 0, and clear the internal array.
* @zh
* 清空数组所有元素。[[length]] 会被设为 0,并且清空内部数组
* 销毁数组。[[length]] 会被设为 0,并且清空内部数组。
*/
public destroy () {
this.length = 0;
@@ -121,6 +128,10 @@ export class CachedArray<T> extends ScalableContainer {
super.destroy();
}
/**
* @en Requests the removal of unused capacity.
* @zh 尝试释放多余的内存。
*/
public tryShrink () {
if (this.array.length >> 2 > this.length) {
this.array.length = Math.max(this._initSize, this.array.length >> 1);
@@ -129,9 +140,10 @@ export class CachedArray<T> extends ScalableContainer {
/**
* @en
* Sort the existing elements in cache
* Sort the existing elements in cache by [[compareFn]] passed in constructor.
* If [[compareFn]] is not passed in, the elements are sorted in ascending, ASCII character order.
* @zh
* 排序所有现有元素
* 使用构造函数传入的 [[compareFn]] 排序所有现有元素。如果没有传入比较函数,将按照 ASCII 升序排序。
*/
public sort () {
this.array.length = this.length;
@@ -140,10 +152,10 @@ export class CachedArray<T> extends ScalableContainer {
/**
* @en
* Add all elements of a given array to the end of the current array
* Add all elements of a given array to the end of the current array.
* @zh
* 添加一个指定数组中的所有元素到当前数组末尾
* @param array The given array to be appended
* 添加一个指定数组中的所有元素到当前数组末尾。
* @param array @en The given array to be appended. @zh 被添加的数组。
*/
public concat (array: T[]) {
for (let i = 0; i < array.length; ++i) {
@@ -154,7 +166,9 @@ export class CachedArray<T> extends ScalableContainer {
/**
* @en Delete the element at the specified location and move the last element to that location.
* @zh 删除指定位置的元素并将最后一个元素移动至该位置。
* @param idx The index of the element to be deleted
* @param idx @en The index of the element to be deleted. If idx out of range [0, length), there is
* not effect.
* @zh 希望被删除的索引。如果索引超出 [0, length),将没有效果。
*/
public fastRemove (idx: number) {
if (idx >= this.length || idx < 0) {
@@ -165,9 +179,11 @@ export class CachedArray<T> extends ScalableContainer {
}
/**
* @en Returns the first index at which a given element can be found in the array.
* @zh 返回在数组中可以找到一个给定元素的第一个索引。
* @param val The element
* @en Returns the first index that compares equal to val.
* @zh 返回在数组中找到的第一个和 val 相等的元素的索引。
* @param val @en Value to search for. @zh 搜索的值。
* @returns The index to the first element that compares equal to val. If no elements match, returns -1.
* @zh 第一个和 val 相等的元素的索引。如果没找到,将返回 -1。
*/
public indexOf (val: T) {
for (let i = 0, len = this.length; i < len; ++i) {
+26 -1
View File
@@ -1,5 +1,5 @@
/*
Copyright (c) 2021 Xiamen Yaji Software Co., Ltd.
Copyright (c) 2021-2022 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
@@ -25,17 +25,32 @@
import { fastRemoveAt } from '../utils/array';
import { ScalableContainer } from './scalable-container';
/**
* @en ContainerManager is a sequence container that stores ScalableContainers.
* It will shrink all managed ScalableContainer in a fixed interval.
*/
class ContainerManager {
private _pools: ScalableContainer[] = [];
private _lastShrinkPassed = 0;
/**
* @en Shrink interval in seconds.
*/
public shrinkTimeSpan = 5;
/**
* @en Add a ScalableContainer. Will add the same ScalableContainer instance once.
* @param pool @en The ScalableContainer to add.
*/
addContainer (pool: ScalableContainer) {
if (pool._poolHandle !== -1) return;
pool._poolHandle = this._pools.length;
this._pools.push(pool);
}
/**
* @en Remove a ScalableContainer.
* @param pool @en The ScalableContainer to remove.
*/
removeContainer (pool: ScalableContainer) {
if (pool._poolHandle === -1) return;
this._pools[this._pools.length - 1]._poolHandle = pool._poolHandle;
@@ -43,12 +58,19 @@ class ContainerManager {
pool._poolHandle = -1;
}
/**
* @en Try to shrink all managed ScalableContainers.
*/
tryShrink () {
for (let i = 0; i < this._pools.length; i++) {
this._pools[i].tryShrink();
}
}
/**
* @en An update function invoked every frame.
* @param dt @en Delta time of frame interval in secondes.
*/
update (dt: number) {
this._lastShrinkPassed += dt;
if (this._lastShrinkPassed > this.shrinkTimeSpan) {
@@ -58,4 +80,7 @@ class ContainerManager {
}
}
/**
* @en A global ContainerManager instance.
*/
export const containerManager = new ContainerManager();
+34 -22
View File
@@ -1,5 +1,5 @@
/*
Copyright (c) 2020 Xiamen Yaji Software Co., Ltd.
Copyright (c) 2020-2022 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
@@ -36,15 +36,20 @@ export class Pool<T> extends ScalableContainer {
private _ctor: () => T;
private _elementsPerBatch: number;
private _nextAvail: number;
private _freepool: T[] = [];
private _freePool: T[] = [];
private _dtor: ((obj: T) => void) | null;
/**
* @en Constructor with the allocator of elements and initial pool size
* @zh 使用元素的构造器和初始大小的构造函数
* @param ctor The allocator of elements in pool, it's invoked directly without `new`
* @param elementsPerBatch Initial pool size, this size will also be the incremental size when the pool is overloaded
* @param dtor The finalizer of element, it's invoked when this container is destroyed or shrunk
* @en Constructor with the allocator of elements and initial pool size.
* @zh 使用元素的构造器和初始大小的构造函数。
* @param ctor @en The allocator of elements in pool, it's invoked directly without `new` in Pool.
* @zh 元素的构造器,Pool 内部使用该构造器直接创建实例。
* @param elementsPerBatch @en Initial pool size, this size will also be the incremental size when
* the pool is overloaded.
* @zh 对象池的初始大小。当对象池扩容时,也会使用该值。
* @param dtor @en The finalizer of element, it's invoked when this Pool is destroyed or shrunk if
* it is valid.
* @zh 元素的析构器。如果存在的话,当对象池销毁或者缩容时,会使用该析构器。
*/
constructor (ctor: () => T, elementsPerBatch: number, dtor?: (obj: T) => void) {
super();
@@ -54,56 +59,63 @@ export class Pool<T> extends ScalableContainer {
this._nextAvail = this._elementsPerBatch - 1;
for (let i = 0; i < this._elementsPerBatch; ++i) {
this._freepool.push(ctor());
this._freePool.push(ctor());
}
}
/**
* @en Take an object out of the object pool.
* @zh 从对象池中取出一个对象。
* @return An object ready for use. This function always return an object.
* @returns @en An object ready for use. This function always returns an object.
* @zh 该函数总是返回一个可用的对象。
*/
public alloc (): T {
if (this._nextAvail < 0) {
this._freepool.length = this._elementsPerBatch;
this._freePool.length = this._elementsPerBatch;
for (let i = 0; i < this._elementsPerBatch; i++) {
this._freepool[i] = this._ctor();
this._freePool[i] = this._ctor();
}
this._nextAvail = this._elementsPerBatch - 1;
}
return this._freepool[this._nextAvail--];
return this._freePool[this._nextAvail--];
}
/**
* @en Put an object back into the object pool.
* @zh 将一个对象放回对象池中。
* @param obj The object to be put back into the pool
* @param obj @en The object to be put back into the pool.
* @zh 放回对象池中的对象。
*/
public free (obj: T) {
this._freepool[++this._nextAvail] = obj;
this._freePool[++this._nextAvail] = obj;
}
/**
* @en Put multiple objects back into the object pool.
* @zh 将一组对象放回对象池中。
* @param objs An array of objects to be put back into the pool
* @param objs @en An array of objects to be put back into the pool.
* @zh 放回对象池中的一组对象。
*/
public freeArray (objs: T[]) {
this._freepool.length = this._nextAvail + 1;
Array.prototype.push.apply(this._freepool, objs);
this._freePool.length = this._nextAvail + 1;
Array.prototype.push.apply(this._freePool, objs);
this._nextAvail += objs.length;
}
/**
* @en Try to shrink the object pool to reduce memory usage.
* @zh 尝试缩容对象池,以释放内存。
*/
public tryShrink () {
if (this._nextAvail >> 1 > this._elementsPerBatch) {
if (this._dtor) {
for (let i = this._nextAvail >> 1; i <= this._nextAvail; i++) {
this._dtor(this._freepool[i]);
this._dtor(this._freePool[i]);
}
}
this._freepool.length = this._nextAvail >> 1;
this._nextAvail = this._freepool.length - 1;
this._freePool.length = this._nextAvail >> 1;
this._nextAvail = this._freePool.length - 1;
}
}
@@ -117,10 +129,10 @@ export class Pool<T> extends ScalableContainer {
const readDtor = dtor || this._dtor;
if (readDtor) {
for (let i = 0; i <= this._nextAvail; i++) {
readDtor(this._freepool[i]);
readDtor(this._freePool[i]);
}
}
this._freepool.length = 0;
this._freePool.length = 0;
this._nextAvail = -1;
super.destroy();
}
+17 -10
View File
@@ -1,5 +1,5 @@
/*
Copyright (c) 2020 Xiamen Yaji Software Co., Ltd.
Copyright (c) 2020-2022 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
@@ -79,8 +79,8 @@ export class RecyclePool<T = any> extends ScalableContainer {
}
/**
* @en Resets the object pool. Only changes the length to 0
* @zh 清空对象池。目前仅仅会设置尺寸为 0
* @en Resets the object pool. Only changes the length to 0.
* @zh 清空对象池。目前仅仅会设置尺寸为 0。
*/
public reset () {
this._count = 0;
@@ -89,7 +89,7 @@ export class RecyclePool<T = any> extends ScalableContainer {
/**
* @en Resize the object poo, and fills with new created elements.
* @zh 设置对象池大小,并填充新的元素。
* @param size The new size of the pool
* @param size @en The new size of the pool. @zh 新的对象池大小。
*/
public resize (size: number) {
if (size > this._data.length) {
@@ -100,9 +100,8 @@ export class RecyclePool<T = any> extends ScalableContainer {
}
/**
* @en Expand the object pool, the size will be increment to current size times two, and fills with new created elements.
* @zh 扩充对象池容量,会自动扩充尺寸到两倍,并填充新的元素。
* @param idx
* @en Expand the array size to 2 times the original size, and fills with new created elements.
* @zh 扩充对象池容量,会自动扩充尺寸到原来的 2 倍,并填充新的元素。
*/
public add () {
if (this._count >= this._data.length) {
@@ -112,6 +111,10 @@ export class RecyclePool<T = any> extends ScalableContainer {
return this._data[this._count++];
}
/**
* @en Destroy the object pool. Please don't use it any more after it is destroyed.
* @zh 销毁对象池。销毁后不能继续使用。
*/
public destroy () {
if (this._dtor) {
for (let i = 0; i < this._data.length; i++) {
@@ -123,6 +126,10 @@ export class RecyclePool<T = any> extends ScalableContainer {
super.destroy();
}
/**
* @en Try to shrink the object pool to free memory.
* @zh 尝试回收没用的对象,释放内存。
*/
public tryShrink () {
if (this._data.length >> 2 > this._count) {
const length = Math.max(this._initSize, this._data.length >> 1);
@@ -136,9 +143,9 @@ export class RecyclePool<T = any> extends ScalableContainer {
}
/**
* @en Remove an element of the object pool. This will also decrease size of the pool
* @zh 移除对象池中的一个元素,同时会减小池子尺寸。
* @param idx The index of the element to be removed
* @en Remove the element with the specified index from the object pool. This will decrease pool size.
* @zh 移除对象池中指定索引的元素,会减小池子尺寸。
* @param idx @en The index of the element to remove. @zh 被移除的元素的索引。
*/
public removeAt (idx: number) {
if (idx >= this._count) {