@blackglory/structures 0.14.15 → 0.15.0

package/lib/utils/trailing-zeros.js.map

@@ -1 +1 @@
-{"version":3,"file":"trailing-zeros.js","sourceRoot":"","sources":["../../src/utils/trailing-zeros.ts"],"names":[],"mappings":"AACA,MAAM,iBAAiB,GAAa;IAClC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;IACjC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IAClC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;IACpC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE;CACxB,CAAA;AAMD,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,iBAAiB,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;AACjD,CAAC"}
+{"version":3,"file":"trailing-zeros.js","sourceRoot":"","sources":["../../src/utils/trailing-zeros.ts"],"names":[],"mappings":"AACA,MAAM,iBAAiB,GAAa;IAClC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;IACjC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IAClC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;IACpC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE;CACxB,CAAA;AAKD,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,CAAA;AACzD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackglory/structures",
-  "version": "0.14.15",
+  "version": "0.15.0",
   "description": "",
   "files": [
     "lib",
@@ -14,58 +14,55 @@
   "author": "BlackGlory <woshenmedoubuzhidao@blackglory.me>",
   "license": "MIT",
   "engines": {
-    "node": ">=18.17.0"
+    "node": ">=22"
   },
   "scripts": {
-    "prepare": "ts-patch install -s",
     "lint": "eslint --ext .js,.jsx,.ts,.tsx --quiet src __tests__",
     "test": "vitest --run",
-    "prepublishOnly": "run-s prepare clean build",
+    "prepublishOnly": "run-s clean build",
     "clean": "rimraf lib",
-    "build": "tsc --project tsconfig.build.json --outDir lib",
+    "build": "tsc --project tsconfig.build.json && tsc-alias --project tsconfig.build.json",
     "bench": "run-s bench:*",
     "bench:bit-set": "tsx benches/bit-set.ts",
     "bench:sparse-map": "tsx benches/sparse-map.ts",
     "bench:sparse-set": "tsx benches/sparse-set.ts",
+    "bench:resizable-array-buffer": "tsx benches/resizable-array-buffer.ts",
     "release": "standard-version"
   },
   "husky": {
     "hooks": {
-      "pre-commit": "run-s prepare lint build test",
+      "pre-commit": "run-s lint build test",
       "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
     }
   },
   "devDependencies": {
-    "@commitlint/cli": "^18.6.1",
-    "@commitlint/config-conventional": "^18.6.2",
-    "@types/node": "16",
-    "@typescript-eslint/eslint-plugin": "^7.0.1",
-    "@typescript-eslint/parser": "^7.0.1",
-    "cross-env": "^7.0.3",
-    "eslint": "^8.56.0",
-    "extra-benchmark": "^0.2.3",
-    "extra-generator": "^0.5.4",
-    "extra-promise": "^6.2.0",
+    "@commitlint/cli": "^21.2.3",
+    "@commitlint/config-conventional": "^21.2.3",
+    "@eslint/js": "^10.0.1",
+    "cross-env": "^10.1.0",
+    "eslint": "^10.12.0",
+    "extra-benchmark": "^0.3.1",
+    "extra-generator": "^0.7.1",
+    "extra-promise": "^7.1.1",
     "husky": "^4.3.8",
     "npm-run-all": "^4.1.5",
-    "return-style": "^3.0.1",
-    "rimraf": "^5.0.5",
+    "return-style": "^4.0.0",
+    "rimraf": "^6.1.3",
     "standard-version": "^9.5.0",
-    "ts-patch": "^3.1.2",
-    "tslib": "^2.6.2",
-    "tsx": "^4.7.1",
-    "typescript": "5.3.3",
-    "typescript-transform-paths": "^3.4.6",
-    "vite": "^5.4.2",
-    "vite-tsconfig-paths": "^5.0.1",
-    "vitest": "^2.0.5"
+    "tsc-alias": "^1.9.7",
+    "tslib": "^2.8.1",
+    "tsx": "^4.23.15",
+    "typescript": "6",
+    "typescript-eslint": "^8.71.0",
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3"
   },
   "dependencies": {
-    "@blackglory/errors": "^3.0.3",
+    "@blackglory/errors": "^3.1.0",
     "@blackglory/go": "^2.0.0",
-    "extra-timers": "^0.2.6",
-    "extra-utils": "^5.6.0",
-    "iterable-operator": "^5.0.0",
-    "justypes": "^4.2.1"
+    "extra-timers": "^0.3.1",
+    "extra-utils": "^6.2.0",
+    "iterable-operator": "^6.0.0",
+    "justypes": "^4.5.0"
   }
 }

package/src/{bit-set.ts → bit-set/bit-set.ts}

@@ -1,10 +1,14 @@
 import { assert } from '@blackglory/errors'
 import { trailingZeros } from '@utils/trailing-zeros.js'
 
-export class BitSet {
-  private array: number[] = []
+export class BitSet implements Iterable<number> {
+  private array: Array<number | undefined> = []
   private length = 0
-  private _size = 0
+  #size = 0
+
+  private isBitsPerElementPowerOfTwo: boolean = false
+  private quotientShift = 0
+  private remainderMask = 0
 
   constructor(private bitsPerElement: number = 8) {
     assert(
@@ -15,11 +19,19 @@ export class BitSet {
       bitsPerElement > 0
     , 'The parameter bitsPerElement must be greater than 0'
     )
-    // `31`是该数据结构中能够处理的最大值
     assert(
-      bitsPerElement <= 31
-    , 'The mask of bitsPerElement must be less than or equal to 31'
+      bitsPerElement <= 32
+    , 'The parameter bitsPerElement must be less than or equal to 32'
     )
+
+    // bitsPerElement为2的幂时, 进行性能优化.
+    this.isBitsPerElementPowerOfTwo = (
+      bitsPerElement & (bitsPerElement - 1)
+    ) === 0
+    if (this.isBitsPerElementPowerOfTwo) {
+      this.quotientShift = Math.log2(bitsPerElement)
+      this.remainderMask = bitsPerElement - 1
+    }
   }
 
   get [Symbol.toStringTag](): string {
@@ -27,7 +39,7 @@ export class BitSet {
   }
 
   get size(): number {
-    return this._size
+    return this.#size
   }
 
   [Symbol.iterator](): IterableIterator<number> {
@@ -40,13 +52,12 @@ export class BitSet {
       const maxArrayLength = ~~(this.length / this.bitsPerElement) + 1
 
       for (let index = 0; index < maxArrayLength; index++) {
-        let element = this.array[index]
-        let offset = 0
-        let indexOfBit: number
-        while ((indexOfBit = trailingZeros(element)) !== 32) {
-          yield index * this.bitsPerElement + offset + indexOfBit
-          offset += indexOfBit + 1
-          element >>= indexOfBit + 1
+        let element = this.array[index] ?? 0
+        while (element !== 0) {
+          const indexOfBit = trailingZeros(element)
+          yield index * this.bitsPerElement + indexOfBit
+          // 移除最低位置的1, 以推进下一个indexOfBit的获取.
+          element &= element - 1
         }
       }
     }
@@ -55,7 +66,7 @@ export class BitSet {
   _dumpBinaryStrings(): string[] {
     const result: string[] = []
     for (let i = 0; i < this.array.length; i++) {
-      const binary = this.array[i].toString(2)
+      const binary = ((this.array[i] ?? 0) >>> 0).toString(2)
       if (binary.length < this.bitsPerElement) {
         result.push('0'.repeat(this.bitsPerElement - binary.length) + binary)
       } else {
@@ -72,39 +83,34 @@ export class BitSet {
   }
 
   add(value: number): boolean {
-    assert(value >= 0, 'value must be greater than or equal to 0')
-    if (value >= this.length) {
-      this.length = value + 1
-    }
-
     const [index, mask] = this.getPosition(value)
 
     const element = this.array[index] ?? 0
     this.array[index] = element | mask
 
     const added = (element & mask) !== mask
-    if (added) {
-      this._size++
-    }
+    if (added) this.#size++
+
+    if (value >= this.length) this.length = value + 1
+
     return added
   }
 
   delete(value: number): boolean {
     const [index, mask] = this.getPosition(value)
 
-    const element = (this.array[index] ?? 0)
+    const element = this.array[index] ?? 0
     this.array[index] = element & ~mask
 
     const deleted = (element & mask) === mask
-    if (deleted) {
-      this._size--
-    }
+    if (deleted) this.#size--
 
     return deleted
   }
 
   clear(): void {
-    this._size = 0
+    this.#size = 0
+    this.length = 0
     this.array.length = 0
   }
 
@@ -113,16 +119,26 @@ export class BitSet {
 
     clone.array = [...this.array]
     clone.length = this.length
-    clone._size = this._size
+    clone.#size = this.#size
 
     return clone
   }
 
   private getPosition(value: number): [index: number, mask: number] {
-    const remainder = value % this.bitsPerElement
-    const quotient = (value - remainder) / this.bitsPerElement
+    let quotient: number
+    let remainder: number
+    if (this.isBitsPerElementPowerOfTwo) {
+      // 当bitsPerElement是2的幂时, 使用位运算版本.
+      remainder = value & this.remainderMask
+      quotient = value >>> this.quotientShift
+    } else {
+      remainder = value % this.bitsPerElement
+      quotient = (value - remainder) / this.bitsPerElement
+    }
+
     const index = quotient
     const mask = this.getMask(remainder)
+
     return [index, mask]
   }
 

package/src/bit-set/dynamic-typed-bit-set.ts

@@ -0,0 +1,131 @@
+import { UnsignedTypedArrayConstructor } from 'justypes'
+import { assert } from '@blackglory/errors'
+import { DynamicTypedArray } from '@src/dynamic-typed-array.js'
+import { trailingZeros } from '@utils/trailing-zeros.js'
+
+export class DynamicTypedBitSet implements Iterable<number> {
+  private bitsPerElement: number
+  private length = 0
+  #size = 0
+
+  private quotientShift = 0
+  private remainderMask = 0
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.#size
+  }
+
+  constructor(private array: DynamicTypedArray<UnsignedTypedArrayConstructor>) {
+    const bitsPerElement = array.BYTES_PER_ELEMENT * 8
+
+    assert(
+      Number.isInteger(bitsPerElement)
+    , 'The bitsPerElement must be an integer'
+    )
+    assert(
+      bitsPerElement > 0
+    , 'The bitsPerElement must be greater than 0'
+    )
+    assert(
+      bitsPerElement <= 32
+    , 'The bitsPerElement must be less than or equal to 31'
+    )
+
+    this.bitsPerElement = bitsPerElement
+    this.quotientShift = Math.log2(bitsPerElement)
+    this.remainderMask = bitsPerElement - 1
+  }
+
+  [Symbol.iterator](): IterableIterator<number> {
+    return this.values()
+  }
+
+  * values(): IterableIterator<number> {
+    if (this.length > 0) {
+      // maxArrayLength = Math.ceil(this.length / this.bitsPerElement)
+      const maxArrayLength = ~~(this.length / this.bitsPerElement) + 1
+
+      for (let index = 0; index < maxArrayLength; index++) {
+        let element = this.array.get(index) ?? 0
+        while (element !== 0) {
+          const indexOfBit = trailingZeros(element)
+          yield index * this.bitsPerElement + indexOfBit
+          // 移除最低位置的1, 以推进下一个indexOfBit的获取.
+          element &= element - 1
+        }
+      }
+    }
+  }
+
+  _dumpBinaryStrings(): string[] {
+    const result: string[] = []
+    for (let i = 0; i < this.array.length; i++) {
+      const binary = ((this.array.get(i) ?? 0) >>> 0).toString(2)
+      if (binary.length < this.bitsPerElement) {
+        result.push('0'.repeat(this.bitsPerElement - binary.length) + binary)
+      } else {
+        result.push(binary)
+      }
+    }
+    return result
+  }
+
+  has(value: number): boolean {
+    const [index, mask] = this.getPosition(value)
+
+    return ((this.array.get(index) ?? 0) & mask) === mask
+  }
+
+  add(value: number): boolean {
+    assert(value >= 0, 'value must be greater than or equal to 0')
+
+    const [index, mask] = this.getPosition(value)
+
+    const element = this.array.get(index) ?? 0
+    this.array.set(index, element | mask)
+
+    const added = (element & mask) !== mask
+    if (added) this.#size++
+
+    if (value >= this.length) this.length = value + 1
+
+    return added
+  }
+
+  delete(value: number): boolean {
+    const [index, mask] = this.getPosition(value)
+
+    const element = (this.array.get(index) ?? 0)
+    this.array.set(index, element & ~mask)
+
+    const deleted = (element & mask) === mask
+    if (deleted) this.#size--
+
+    return deleted
+  }
+
+  clear(): void {
+    this.#size = 0
+    this.array.clear()
+  }
+
+  private getPosition(value: number): [index: number, mask: number] {
+    const remainder = value & this.remainderMask
+    const quotient = value >>> this.quotientShift
+
+    const index = quotient
+    const mask = this.getMask(remainder)
+
+    return [index, mask]
+  }
+
+  // 输入一定是一个小于bitsPerElement的值, 取值范围是[0, bitsPerElement)
+  private getMask(value: number): number {
+    // return 2 ** value
+    return 1 << value
+  }
+}

package/src/bit-set/index.ts

@@ -0,0 +1,4 @@
+export * from './bit-set.js'
+export * from './typed-bit-set.js'
+export * from './dynamic-typed-bit-set.js'
+export * from './resizable-typed-bit-set.js'

package/src/{typed-bit-set.ts → bit-set/resizable-typed-bit-set.ts}

@@ -1,14 +1,25 @@
 import { UnsignedTypedArrayConstructor } from 'justypes'
 import { assert } from '@blackglory/errors'
-import { DynamicTypedArray } from './dynamic-typed-array.js'
+import { ResizableTypedArray } from '@src/resizable-typed-array.js'
 import { trailingZeros } from '@utils/trailing-zeros.js'
 
-export class TypedBitSet<T extends UnsignedTypedArrayConstructor> {
+export class ResizableTypedBitSet implements Iterable<number> {
   private bitsPerElement: number
   private length = 0
-  private _size = 0
+  #size = 0
 
-  constructor(private array: DynamicTypedArray<T>) {
+  private quotientShift = 0
+  private remainderMask = 0
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.#size
+  }
+
+  constructor(private array: ResizableTypedArray<UnsignedTypedArrayConstructor>) {
     const bitsPerElement = array.BYTES_PER_ELEMENT * 8
 
     assert(
@@ -21,19 +32,13 @@ export class TypedBitSet<T extends UnsignedTypedArrayConstructor> {
     )
     // `31`是该数据结构中能够处理的最大值
     assert(
-      bitsPerElement <= 31
-    , 'The mask of bitsPerElement must be less than or equal to 31'
+      bitsPerElement <= 32
+    , 'The bitsPerElement must be less than or equal to 31'
     )
 
     this.bitsPerElement = bitsPerElement
-  }
-
-  get [Symbol.toStringTag](): string {
-    return this.constructor.name
-  }
-
-  get size(): number {
-    return this._size
+    this.quotientShift = Math.log2(bitsPerElement)
+    this.remainderMask = bitsPerElement - 1
   }
 
   [Symbol.iterator](): IterableIterator<number> {
@@ -46,13 +51,12 @@ export class TypedBitSet<T extends UnsignedTypedArrayConstructor> {
       const maxArrayLength = ~~(this.length / this.bitsPerElement) + 1
 
       for (let index = 0; index < maxArrayLength; index++) {
-        let element = this.array.internalTypedArray[index]
-        let offset = 0
-        let indexOfBit: number
-        while ((indexOfBit = trailingZeros(element)) !== 32) {
-          yield index * this.bitsPerElement + offset + indexOfBit
-          offset += indexOfBit + 1
-          element >>= indexOfBit + 1
+        let element = this.array.get(index) ?? 0
+        while (element !== 0) {
+          const indexOfBit = trailingZeros(element)
+          yield index * this.bitsPerElement + indexOfBit
+          // 移除最低位置的1, 以推进下一个indexOfBit的获取.
+          element &= element - 1
         }
       }
     }
@@ -61,7 +65,7 @@ export class TypedBitSet<T extends UnsignedTypedArrayConstructor> {
   _dumpBinaryStrings(): string[] {
     const result: string[] = []
     for (let i = 0; i < this.array.length; i++) {
-      const binary = this.array.internalTypedArray[i].toString(2)
+      const binary = ((this.array.get(i) ?? 0) >>> 0).toString(2)
       if (binary.length < this.bitsPerElement) {
         result.push('0'.repeat(this.bitsPerElement - binary.length) + binary)
       } else {
@@ -78,20 +82,16 @@ export class TypedBitSet<T extends UnsignedTypedArrayConstructor> {
   }
 
   add(value: number): boolean {
-    assert(value >= 0, 'value must be greater than or equal to 0')
-    if (value >= this.length) {
-      this.length = value + 1
-    }
-
     const [index, mask] = this.getPosition(value)
 
     const element = this.array.get(index) ?? 0
     this.array.set(index, element | mask)
 
     const added = (element & mask) !== mask
-    if (added) {
-      this._size++
-    }
+    if (added) this.#size++
+
+    if (value >= this.length) this.length = value + 1
+
     return added
   }
 
@@ -102,22 +102,24 @@ export class TypedBitSet<T extends UnsignedTypedArrayConstructor> {
     this.array.set(index, element & ~mask)
 
     const deleted = (element & mask) === mask
-    if (deleted) {
-      this._size--
-    }
+    if (deleted) this.#size--
+
     return deleted
   }
 
   clear(): void {
-    this._size = 0
+    this.#size = 0
+    this.length = 0
     this.array.clear()
   }
 
   private getPosition(value: number): [index: number, mask: number] {
-    const remainder = value % this.bitsPerElement
-    const quotient = (value - remainder) / this.bitsPerElement
+    const remainder = value & this.remainderMask
+    const quotient = value >>> this.quotientShift
+
     const index = quotient
     const mask = this.getMask(remainder)
+
     return [index, mask]
   }
 

package/src/bit-set/typed-bit-set.ts

@@ -0,0 +1,134 @@
+import { UnsignedTypedArray } from 'justypes'
+import { assert } from '@blackglory/errors'
+import { trailingZeros } from '@utils/trailing-zeros.js'
+
+export class TypedBitSet implements Iterable<number> {
+  private bitsPerElement: number
+  private length = 0
+  #size = 0
+
+  private quotientShift = 0
+  private remainderMask = 0
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get capacity(): number {
+    return this.array.length * this.bitsPerElement
+  }
+
+  get size(): number {
+    return this.#size
+  }
+
+  constructor(private array: UnsignedTypedArray) {
+    const bitsPerElement = array.BYTES_PER_ELEMENT * 8
+
+    assert(
+      Number.isInteger(bitsPerElement)
+    , 'The bitsPerElement must be an integer'
+    )
+    assert(
+      bitsPerElement > 0
+    , 'The bitsPerElement must be greater than 0'
+    )
+    assert(
+      bitsPerElement <= 32
+    , 'The bitsPerElement must be less than or equal to 32'
+    )
+
+    this.bitsPerElement = bitsPerElement
+    this.quotientShift = Math.log2(bitsPerElement)
+    this.remainderMask = bitsPerElement - 1
+  }
+
+  [Symbol.iterator](): IterableIterator<number> {
+    return this.values()
+  }
+
+  * values(): IterableIterator<number> {
+    if (this.length > 0) {
+      // maxArrayLength = Math.ceil(this.length / this.bitsPerElement)
+      const maxArrayLength = ~~(this.length / this.bitsPerElement) + 1
+
+      for (let index = 0; index < maxArrayLength; index++) {
+        let element = this.array[index] ?? 0
+        while (element !== 0) {
+          const indexOfBit = trailingZeros(element)
+          yield index * this.bitsPerElement + indexOfBit
+          // 移除最低位置的1, 以推进下一个indexOfBit的获取.
+          element &= element - 1
+        }
+      }
+    }
+  }
+
+  _dumpBinaryStrings(): string[] {
+    const result: string[] = []
+    for (let i = 0; i < this.array.length; i++) {
+      const binary = ((this.array[i] ?? 0) >>> 0).toString(2)
+      if (binary.length < this.bitsPerElement) {
+        result.push('0'.repeat(this.bitsPerElement - binary.length) + binary)
+      } else {
+        result.push(binary)
+      }
+    }
+    return result
+  }
+
+  has(value: number): boolean {
+    const [index, mask] = this.getPosition(value)
+
+    return (this.array[index] & mask) === mask
+  }
+
+  add(value: number): boolean {
+    const [index, mask] = this.getPosition(value)
+    assert(index < this.capacity, `The array is not large enough`)
+
+    const element = this.array[index]
+    this.array[index] = element | mask
+
+    const added = (element & mask) !== mask
+    if (added) this.#size++
+
+    if (value >= this.length) this.length = value + 1
+
+    return added
+  }
+
+  delete(value: number): boolean {
+    const [index, mask] = this.getPosition(value)
+
+    const element = this.array[index]
+    this.array[index] = element & ~mask
+
+    const deleted = (element & mask) === mask
+    if (deleted) this.#size--
+
+    return deleted
+  }
+
+  clear(): void {
+    this.#size = 0
+    this.length = 0
+    this.array.fill(0)
+  }
+
+  private getPosition(value: number): [index: number, mask: number] {
+    const remainder = value & this.remainderMask
+    const quotient = value >>> this.quotientShift
+
+    const index = quotient
+    const mask = this.getMask(remainder)
+
+    return [index, mask]
+  }
+
+  // 输入一定是一个小于bitsPerElement的值, 取值范围是[0, bitsPerElement)
+  private getMask(value: number): number {
+    // return 2 ** value
+    return 1 << value
+  }
+}