@blackglory/structures 0.14.15 → 0.15.1

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
+  }
+}

package/src/dynamic-typed-array.ts

@@ -1,28 +1,30 @@
 import { TypedArrayConstructor, TypedArrayOfConstructor } from 'justypes'
 import { assert } from '@blackglory/errors'
+import { computeNewCapacity } from '@utils/compute-new-capacity.js'
 
 interface IDynamicTypedArrayOptions {
-  capacity?: number
   growthFactor?: number
+  initialCapacity?: number
+  fillValue?: number
 }
 
-// 相关提案: https://github.com/tc39/proposal-resizablearraybuffer
-export class DynamicTypedArray<T extends TypedArrayConstructor> {
+export class DynamicTypedArray<
+  T extends TypedArrayConstructor
+> implements Iterable<number> {
   private array: TypedArrayOfConstructor<T>
-  private _length: number = 0
-  private initialCapacity: number
+
   readonly growthFactor: number
+  readonly BYTES_PER_ELEMENT: number
+  readonly fillValue: number
 
-  get internalTypedArray(): TypedArrayOfConstructor<T> {
-    return this.array
-  }
+  #length: number = 0
 
   get [Symbol.toStringTag](): string {
     return this.constructor.name
   }
 
-  get BYTES_PER_ELEMENT(): number {
-    return this.typedArrayConstructor.BYTES_PER_ELEMENT
+  get internalTypedArray(): TypedArrayOfConstructor<T> {
+    return this.array
   }
 
   /**
@@ -36,23 +38,39 @@ export class DynamicTypedArray<T extends TypedArrayConstructor> {
    * 数组逻辑上的长度, 总是小于或等于capacity.
    */
   get length(): number {
-    return this._length
+    return this.#length
   }
 
   constructor(
     private typedArrayConstructor: T
   , {
-      capacity = 0
-    , growthFactor = 1.5
+      growthFactor = 1.5
+    , initialCapacity = 0
+    , fillValue = 0
     }: IDynamicTypedArrayOptions = {}
   ) {
-    assert(Number.isInteger(capacity), 'capacity must be an integer')
-    assert(capacity >= 0, 'capacity must be greater than or equal to 0')
     assert(growthFactor >= 1, 'growthFactory must be greater than or equal to 1')
+    assert(Number.isInteger(initialCapacity), 'initialCapacity must be an integer')
+    assert(initialCapacity >= 0, 'initialCapacity must be greater than or equal to 0')
 
-    this.initialCapacity = capacity
-    this.array = new typedArrayConstructor(capacity) as TypedArrayOfConstructor<T>
     this.growthFactor = growthFactor
+    this.fillValue = fillValue
+
+    const array = new typedArrayConstructor(initialCapacity) as TypedArrayOfConstructor<T>
+    if (fillValue !== 0) array.fill(fillValue)
+    this.array = array
+
+    this.BYTES_PER_ELEMENT = typedArrayConstructor.BYTES_PER_ELEMENT
+  }
+
+  [Symbol.iterator](): IterableIterator<number> {
+    return this.values()
+  }
+
+  * values(): IterableIterator<number> {
+    for (let i = 0; i < this.#length; i++) {
+      yield this.array[i]
+    }
   }
 
   set(index: number, value: number): void {
@@ -65,38 +83,39 @@ export class DynamicTypedArray<T extends TypedArrayConstructor> {
       this.resize(newCapacity)
     }
 
-    if (index >= this._length) {
-      this._length = index + 1
+    if (index >= this.#length) {
+      this.#length = index + 1
     }
 
     this.array[index] = value
   }
 
-  setValues(index: number, values: TypedArrayOfConstructor<T>): void {
-    if (index + values.length >= this.capacity) {
+  setValues(index: number, values: ArrayLike<number>): void {
+    const endIndex = index + values.length
+    if (endIndex > this.capacity) {
       const newCapacity = computeNewCapacity(
         this.capacity
-      , index + values.length
+      , endIndex
       , this.growthFactor
       )
       this.resize(newCapacity)
     }
 
-    if (index + values.length > this._length) {
-      this._length = index + values.length
+    if (endIndex > this.#length) {
+      this.#length = endIndex
     }
 
-    this.internalTypedArray.set(values, index)
+    this.array.set(values, index)
   }
 
   get(index: number): number | undefined {
-    return index < this._length
+    return index < this.#length
          ? this.array[index]
          : undefined
   }
 
   push(...values: number[]): void {
-    const newLength = this._length + values.length
+    const newLength = this.#length + values.length
     if (newLength > this.capacity) {
       const newCapacity = computeNewCapacity(
         this.capacity
@@ -107,21 +126,14 @@ export class DynamicTypedArray<T extends TypedArrayConstructor> {
     }
 
     for (const value of values) {
-      this.array[this._length++] = value
+      this.array[this.#length++] = value
     }
   }
 
   pop(): number | undefined {
-    if (this._length > 0) {
-      const value = this.array[this._length - 1]
-      this._length--
-
-      const newCapacity = computeNewCapacity(
-        this.capacity
-      , this.length
-      , this.growthFactor
-      )
-      this.resize(newCapacity)
+    if (this.#length > 0) {
+      const value = this.array[this.#length - 1]
+      this.#length--
 
       return value
     } else {
@@ -130,9 +142,16 @@ export class DynamicTypedArray<T extends TypedArrayConstructor> {
   }
 
   clear(): void {
-    this._length = 0
-    const newArray = new this.typedArrayConstructor(this.initialCapacity)
-    this.array = newArray as TypedArrayOfConstructor<T>
+    this.#length = 0
+  }
+
+  shrink(): void {
+    const newCapacity = computeNewCapacity(
+      this.capacity
+    , this.length
+    , this.growthFactor
+    )
+    this.resize(newCapacity)
   }
 
   sort(compare?: (a: number, b: number) => number): void {
@@ -148,8 +167,14 @@ export class DynamicTypedArray<T extends TypedArrayConstructor> {
     } else if (this.array.length < newCapacity) {
       const newArray = new this.typedArrayConstructor(newCapacity)
       newArray.set(this.array)
+
+      if (this.fillValue !== 0) {
+        const startIndex = this.array.length
+        newArray.fill(this.fillValue, startIndex)
+      }
+
       this.array = newArray as TypedArrayOfConstructor<T>
-    } else if (this.array.length > newCapacity) {
+    } else /* if (this.array.length > newCapacity) */ {
       const newArray = new this.typedArrayConstructor(newCapacity)
       // 不需要的部分将被舍弃.
       for (let i = newCapacity; i--;) {
@@ -159,43 +184,3 @@ export class DynamicTypedArray<T extends TypedArrayConstructor> {
     }
   }
 }
-
-export function computeNewCapacity(
-  oldCapacity: number
-, targetLength: number
-, growthFactor: number
-): number {
-  if (growthFactor === 1) {
-    return targetLength
-  } else {
-    if (oldCapacity === targetLength) {
-      return targetLength
-    } else if (oldCapacity < targetLength) { 
-      // 增加容量以适配targetLength
-      let newCapacity = Math.max(oldCapacity, 1)
-      while (newCapacity < targetLength) {
-        newCapacity *= growthFactor
-      }
-      return Math.floor(newCapacity)
-    } else {
-      // 尝试减少容量以适配targetLength
-
-      // `targetLength = 0`是特殊情况,
-      // 此时无论怎么将oldCapacity除以growthFactory几次, 都不可能得到比targetLength小的结果.
-      if (targetLength === 0) {
-        return 0
-      } else {
-        let newCapacity = oldCapacity
-        while (true) {
-          const temp = newCapacity / growthFactor
-          if (temp < targetLength) {
-            break
-          } else {
-            newCapacity = temp
-          }
-        }
-        return Math.floor(newCapacity)
-      }
-    }
-  }
-}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './box.js'
 export * from './cons.js'
 export * from './array.js'
+export * from './typed-array.js'
 export * from './emitter.js'
 export * from './generator-emitter.js'
 export * from './async-generator-emitter.js'
@@ -17,12 +18,10 @@ export * from './trie-map.js'
 export * from './string-trie-map.js'
 export { RadixTree } from './radix-tree.js'
 export { StringRadixTree } from './string-radix-tree.js'
-export * from './sparse-set.js'
-export * from './sparse-map.js'
-export * from './typed-sparse-map.js'
-export * from './typed-sparse-set.js'
-export { DynamicTypedArray } from './dynamic-typed-array.js'
+export * from './dynamic-typed-array.js'
+export * from './resizable-typed-array.js'
 export * from './sorted-set.js'
-export * from './bit-set.js'
-export * from './typed-bit-set.js'
 export * from './disjoint-set.js'
+export * from './bit-set/index.js'
+export * from './sparse-set/index.js'
+export * from './sparse-map/index.js'