@blackglory/structures 0.14.15 → 0.15.0

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

@@ -17,12 +17,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'

package/src/resizable-typed-array.ts

@@ -0,0 +1,214 @@
+import { TypedArrayConstructor, TypedArrayOfConstructor } from 'justypes'
+import { assert } from '@blackglory/errors'
+import { computeNewCapacity } from '@utils/compute-new-capacity.js'
+
+interface IResizableTypedArrayOptions {
+  maxCapacity: number
+
+  initialCapacity?: number
+  growthFactor?: number
+
+  fillValue?: number
+}
+
+export class ResizableTypedArray<
+  T extends TypedArrayConstructor
+> implements Iterable<number> {
+  private array: TypedArrayOfConstructor<T, ArrayBuffer>
+
+  readonly maxCapacity: number
+  readonly growthFactor: number
+  readonly BYTES_PER_ELEMENT: number
+  readonly internalTypedArray: TypedArrayOfConstructor<T>
+  readonly fillValue: number
+
+  #length: number = 0
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  /**
+   * 数组当前的容量.
+   */
+  get capacity(): number {
+    return this.array.length
+  }
+
+  /**
+   * 数组逻辑上的长度, 总是小于或等于capacity.
+   */
+  get length(): number {
+    return this.#length
+  }
+
+  constructor(
+    typedArrayConstructor: T
+  , {
+      maxCapacity
+    , initialCapacity = 0
+    , growthFactor = 1.5
+    , fillValue = 0
+    }: IResizableTypedArrayOptions
+  ) {
+    assert(growthFactor >= 1, 'growthFactory must be greater than or equal to 1')
+    assert(initialCapacity >= 0, 'initialCapacity must be greater than or equal to 0')
+    assert(Number.isInteger(initialCapacity), 'capacity must be an integer')
+    assert(initialCapacity >= 0, 'capacity must be greater than or equal to 0')
+    assert(Number.isInteger(maxCapacity), 'maxCapacity must be an integer')
+    assert(maxCapacity >= initialCapacity, 'maxCapacity must be greater than or equal to capacity')
+
+    this.growthFactor = growthFactor
+    this.maxCapacity = maxCapacity
+    this.fillValue = fillValue
+
+    const buffer = new ArrayBuffer(
+      initialCapacity * typedArrayConstructor.BYTES_PER_ELEMENT
+    , { maxByteLength: maxCapacity * typedArrayConstructor.BYTES_PER_ELEMENT }
+    )
+    const array = new typedArrayConstructor(buffer)
+    if (fillValue !== 0) array.fill(fillValue)
+    this.array = array as TypedArrayOfConstructor<T, ArrayBuffer>
+
+    this.internalTypedArray = array as TypedArrayOfConstructor<T, ArrayBuffer>
+    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 {
+    if (index >= this.capacity) {
+      assert(index < this.maxCapacity, 'index must be less than maxCapacity')
+
+      const newCapacity = Math.min(
+        computeNewCapacity(
+          this.capacity
+        , index + 1
+        , this.growthFactor
+        )
+      , this.maxCapacity
+      )
+
+      this.resize(newCapacity)
+    }
+
+    if (index >= this.#length) {
+      this.#length = index + 1
+    }
+
+    this.array[index] = value
+  }
+
+  setValues(index: number, values: ArrayLike<number>): void {
+    const endIndex = index + values.length
+    if (endIndex > this.capacity) {
+      assert(
+        endIndex <= this.maxCapacity
+      , 'endIndex must be less than or equal tomaxCapacity'
+      )
+
+      const newCapacity = Math.min(
+        computeNewCapacity(
+          this.capacity
+        , index + values.length
+        , this.growthFactor
+        )
+      , this.maxCapacity
+      )
+
+      this.resize(newCapacity)
+    }
+
+    if (endIndex > this.#length) {
+      this.#length = endIndex
+    }
+
+    this.array.set(values, index)
+  }
+
+  get(index: number): number | undefined {
+    return index < this.#length
+         ? this.array[index]
+         : undefined
+  }
+
+  push(...values: number[]): void {
+    const newLength = this.#length + values.length
+    if (newLength > this.capacity) {
+      assert(
+        newLength <= this.maxCapacity
+      , 'newLength must be less than or equal to maxCapacity'
+      )
+
+      const newCapacity = Math.min(
+        computeNewCapacity(
+          this.capacity
+        , newLength
+        , this.growthFactor
+        )
+      , this.maxCapacity
+      )
+
+      this.resize(newCapacity)
+    }
+
+    for (const value of values) {
+      this.array[this.#length++] = value
+    }
+  }
+
+  pop(): number | undefined {
+    if (this.#length > 0) {
+      const value = this.array[this.#length - 1]
+      this.#length--
+
+      return value
+    } else {
+      return undefined
+    }
+  }
+
+  clear(): void {
+    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 {
+    const capacity = this.capacity
+    this.resize(this.length)
+    this.array.sort(compare)
+    this.resize(capacity)
+  }
+
+  private resize(newCapacity: number): void {
+    if (this.array.length === newCapacity) {
+      return
+    } else if (this.array.length < newCapacity) {
+      if (this.fillValue === 0) {
+        this.array.buffer.resize(newCapacity * this.BYTES_PER_ELEMENT)
+      } else {
+        const startIndex = this.array.length
+        this.array.buffer.resize(newCapacity * this.BYTES_PER_ELEMENT)
+        this.array.fill(this.fillValue, startIndex)
+      }
+    } else /* if (this.array.length > newCapacity) */ {
+      this.array.buffer.resize(newCapacity * this.BYTES_PER_ELEMENT)
+    }
+  }
+}

package/src/sparse-map/clean-sparse-map.ts

@@ -0,0 +1,84 @@
+export class CleanSparseMap<T> {
+  private denseKeys: number[] = []
+  private denseValues: T[] = []
+  private sparse: Array<number | undefined> = []
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.denseKeys.length
+  }
+
+  readonly internalKeyArray: readonly number[] = this.denseKeys
+  readonly internalValueArray: T[] = this.denseValues
+
+  ;* entries(): IterableIterator<[key: number, value: T]> {
+    for (let i = 0; i < this.denseKeys.length; i++) {
+      yield [this.denseKeys[i], this.denseValues[i]]
+    }
+  }
+
+  keys(): IterableIterator<number> {
+    return this.denseKeys.values()
+  }
+
+  values(): IterableIterator<T> {
+    return this.denseValues.values()
+  }
+
+  getInternalIndexOfKey(key: number): number | undefined {
+    return this.sparse[key]
+  }
+
+  has(key: number): boolean {
+    return this.sparse[key] !== undefined
+  }
+
+  get(key: number): T | undefined {
+    const index = this.sparse[key]
+    if (index !== undefined) {
+      return this.denseValues[index]
+    } else {
+      return undefined
+    }
+  }
+
+  set(key: number, value: T): void {
+    const index = this.sparse[key]
+    if (index !== undefined) {
+      this.denseValues[index] = value
+    } else {
+      const index = this.denseKeys.length
+      this.denseKeys.push(key)
+      this.denseValues.push(value)
+      this.sparse[key] = index
+    }
+  }
+
+  delete(key: number): boolean {
+    const index = this.sparse[key]
+    if (index !== undefined) {
+      this.sparse[key] = undefined
+
+      const lastKey = this.denseKeys.pop()!
+      const lastValue = this.denseValues.pop()!
+      if (key !== lastKey) {
+        this.denseKeys[index] = lastKey
+        this.denseValues[index] = lastValue
+        this.sparse[lastKey] = index
+      }
+
+      return true
+    } else {
+      return false
+    }
+  }
+
+  clear(): void {
+    this.denseKeys.length = 0
+    this.denseValues.length = 0
+    this.sparse.length = 0
+  }
+}

package/src/sparse-map/dynamic-typed-clean-sparse-map-lite.ts

@@ -0,0 +1,109 @@
+import { assert } from '@blackglory/errors'
+import { TypedArrayConstructor, UnsignedTypedArrayConstructor, TypedArrayOfConstructor } from 'justypes'
+import { DynamicTypedArray } from '@src/dynamic-typed-array.js'
+
+export class DynamicTypedCleanSparseMapLite<
+  K extends UnsignedTypedArrayConstructor
+, V extends TypedArrayConstructor
+> {
+  private denseKeys: DynamicTypedArray<K>
+  private denseValues: DynamicTypedArray<V>
+  private sparse: Array<number | undefined> = []
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.denseKeys.length
+  }
+
+  get internalKeyArray(): TypedArrayOfConstructor<K> {
+    return this.denseKeys.internalTypedArray
+  }
+
+  get internalValueArray(): TypedArrayOfConstructor<V> {
+    return this.denseValues.internalTypedArray
+  }
+
+  constructor(
+    keys: DynamicTypedArray<K>
+  , values: DynamicTypedArray<V>
+  ) {
+    assert(keys.length === 0, 'keys must be empty')
+
+    this.denseKeys = keys
+    this.denseValues = values
+  }
+
+  * entries(): IterableIterator<[key: number, value: number]> {
+    for (let i = 0; i < this.denseKeys.length; i++) {
+      yield [
+        this.denseKeys.internalTypedArray[i]
+      , this.denseValues.internalTypedArray[i]
+      ]
+    }
+  }
+
+  keys(): IterableIterator<number> {
+    return this.denseKeys.values()
+  }
+
+  values(): IterableIterator<number> {
+    return this.denseValues.values()
+  }
+
+  getInternalIndexOfKey(key: number): number | undefined {
+    return this.sparse[key]
+  }
+
+  has(key: number): boolean {
+    return this.sparse[key] !== undefined
+  }
+
+  get(key: number): number | undefined {
+    const index = this.sparse[key]
+    if (index !== undefined) {
+      return this.denseValues.internalTypedArray[index]
+    } else {
+      return undefined
+    }
+  }
+
+  set(key: number, value: number): void {
+    const index = this.sparse[key]
+    if (index !== undefined) {
+      this.denseValues.internalTypedArray[index] = value
+    } else {
+      const index = this.denseKeys.length
+      this.denseKeys.push(key)
+      this.denseValues.push(value)
+      this.sparse[key] = index
+    }
+  }
+
+  delete(key: number): boolean {
+    const index = this.sparse[key]
+    if (index !== undefined) {
+      this.sparse[key] = undefined
+
+      const lastKey = this.denseKeys.pop()!
+      const lastValue = this.denseValues.pop()!
+      if (key !== lastKey) {
+        this.denseKeys.internalTypedArray[index] = lastKey
+        this.denseValues.internalTypedArray[index] = lastValue
+        this.sparse[lastKey] = index
+      }
+
+      return true
+    } else {
+      return false
+    }
+  }
+
+  clear(): void {
+    this.denseKeys.clear()
+    this.denseValues.clear()
+    this.sparse.length = 0
+  }
+}