@blackglory/structures 0.14.14 → 0.15.0

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

@@ -0,0 +1,169 @@
+import { assert } from '@blackglory/errors'
+import { go } from '@blackglory/go'
+import { getMaxValueOfUnsignedTypedArray, getMaxValueOfUnsignedTypedArrayConstructor } from '@utils/get-max-value-of-unsigned-typed-array.js'
+import { TypedArrayConstructor, UnsignedTypedArrayConstructor, TypedArrayOfConstructor, UnsignedTypedArray } from 'justypes'
+
+export class TypedSparseMap<
+  K extends UnsignedTypedArrayConstructor
+, V extends TypedArrayConstructor
+> {
+  private denseKeys: TypedArrayOfConstructor<K>
+  private denseValues: TypedArrayOfConstructor<V>
+  private sparse: UnsignedTypedArray
+  #length = 0
+
+  readonly internalKeyArray: TypedArrayOfConstructor<K, ArrayBuffer>
+  readonly internalValueArray: TypedArrayOfConstructor<V, ArrayBuffer>
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.#length
+  }
+
+  constructor(
+    keys: TypedArrayOfConstructor<K, ArrayBuffer>
+  , values: TypedArrayOfConstructor<V, ArrayBuffer>
+  ) {
+    assert(!keys.buffer.resizable, 'The keys buffer must not be resizable')
+    assert(!values.buffer.resizable, 'The values buffer must not be resizable')
+    assert(
+      values.length >= keys.length
+    , 'The values.length must greater than or equal to keys.length'
+    )
+
+    this.denseKeys = keys
+    this.denseValues = values
+
+    this.internalKeyArray = keys
+    this.internalValueArray = values
+
+    const sparseConstructor = go(() => {
+      const maxIndex = Math.min(
+        keys.length - 1
+      , getMaxValueOfUnsignedTypedArray(keys) + 1
+      )
+      if (
+        maxIndex <=
+        getMaxValueOfUnsignedTypedArrayConstructor(Uint8Array)
+      ) {
+        return Uint8Array
+      } else if (
+        maxIndex <=
+        getMaxValueOfUnsignedTypedArrayConstructor(Uint16Array)
+      ) {
+        return Uint16Array
+      } else if (
+        maxIndex <=
+        getMaxValueOfUnsignedTypedArrayConstructor(Uint32Array)
+      ) {
+        return Uint32Array
+      } else {
+        throw new Error('The array is too large')
+      }
+    })
+    this.sparse = new sparseConstructor(getMaxValueOfUnsignedTypedArray(keys) + 1)
+  }
+
+  * entries(): IterableIterator<[key: number, value: number]> {
+    for (let i = 0; i < this.#length; i++) {
+      yield [
+        this.denseKeys[i]
+      , this.denseValues[i]
+      ]
+    }
+  }
+
+  * keys(): IterableIterator<number> {
+    for (let i = 0; i < this.#length; i++) {
+      yield this.denseKeys[i]
+    }
+  }
+
+  * values(): IterableIterator<number> {
+    for (let i = 0; i < this.#length; i++) {
+      yield this.denseValues[i]
+    }
+  }
+
+  getInternalIndexOfKey(key: number): number | undefined {
+    const index = this.sparse[key]
+    if (
+      index !== undefined &&
+      index < this.#length &&
+      index < this.denseKeys.length && // 用于改善JIT优化.
+      this.denseKeys[index] === key
+    ) {
+      return index
+    }
+  }
+
+  has(key: number): boolean {
+    const index = this.sparse[key]
+    return index !== undefined
+        && index < this.#length
+        && index < this.denseKeys.length // 用于改善JIT优化.
+        && this.denseKeys[index] === key
+  }
+
+  get(key: number): number | undefined {
+    const index = this.sparse[key]
+    if (
+      index !== undefined &&
+      index < this.#length &&
+      index < this.denseKeys.length && // 用于改善JIT优化.
+      this.denseKeys[index] === key
+    ) {
+      return this.denseValues[index]
+    } else {
+      return undefined
+    }
+  }
+
+  set(key: number, value: number): void {
+    const index = this.sparse[key]
+    if (
+      index !== undefined &&
+      index < this.#length &&
+      index < this.denseKeys.length && // 用于改善JIT优化.
+      this.denseKeys[index] === key
+    ) {
+      this.denseValues[index] = value
+    } else {
+      const index = this.#length++
+      this.denseKeys[index] = key
+      this.denseValues[index] = value
+      this.sparse[key] = index
+    }
+  }
+
+  delete(key: number): boolean {
+    const index = this.sparse[key]
+    if (
+      index !== undefined &&
+      index < this.#length &&
+      index < this.denseKeys.length && // 用于改善JIT优化.
+      this.denseKeys[index] === key
+    ) {
+      const lastIndex = --this.#length
+      const lastKey = this.denseKeys[lastIndex]
+      const lastValue = this.denseValues[lastIndex]
+      if (key !== lastKey) {
+        this.denseKeys[index] = lastKey
+        this.denseValues[index] = lastValue
+        this.sparse[lastKey] = index
+      }
+
+      return true
+    } else {
+      return false
+    }
+  }
+
+  clear(): void {
+    this.#length = 0
+    // 无需清空dense和sparse数组.
+  }
+}

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

@@ -0,0 +1,76 @@
+/**
+ * 稀疏集的干净sparse数组变体.
+ * 
+ * `has()`和`add()`快于标准实现, `delete()`和`clear()`慢于标准实现.
+ */
+export class CleanSparseSet implements Iterable<number> {
+  private dense: number[] = []
+  private sparse: Array<number | undefined> = []
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.dense.length
+  }
+
+  [Symbol.iterator](): IterableIterator<number> {
+    return this.values()
+  }
+
+  values(): IterableIterator<number> {
+    return this.dense.values()
+  }
+
+  has(value: number): boolean {
+    return this.sparse[value] !== undefined
+  }
+
+  add(value: number): void {
+    if (!this.has(value)) {
+      const index = this.dense.length
+      this.dense.push(value)
+      this.sparse[value] = index
+    }
+  }
+
+  delete(value: number): boolean {
+    const index = this.sparse[value]
+    if (index !== undefined) {
+      this.sparse[value] = undefined
+
+      const lastValue = this.dense.pop()!
+      if (value !== lastValue) {
+        this.dense[index] = lastValue
+        this.sparse[lastValue] = index
+      }
+
+      return true
+    } else {
+      return false
+    }
+  }
+
+  clear(): void {
+    this.dense.length = 0
+    this.sparse.length = 0
+  }
+
+  clone(): CleanSparseSet {
+    const clone = new CleanSparseSet()
+
+    const dense = [...this.dense]
+
+    // 由于`sparse`是稀疏的, 不应用`[...sparse]`复制.
+    const sparse: Array<number | undefined> = []
+    for (const [index, value] of dense.entries()) {
+      sparse[value] = index
+    }
+
+    clone.dense = dense
+    clone.sparse = sparse
+
+    return clone
+  }
+}

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

@@ -0,0 +1,64 @@
+import { DynamicTypedArray } from '@src/dynamic-typed-array.js'
+import { assert } from '@blackglory/errors'
+import { UnsignedTypedArrayConstructor } from 'justypes'
+
+export class DynamicTypedCleanSparseSetLite implements Iterable<number> {
+  private dense: DynamicTypedArray<UnsignedTypedArrayConstructor>
+  private sparse: Array<number | undefined> = []
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.dense.length
+  }
+
+  constructor(array: DynamicTypedArray<UnsignedTypedArrayConstructor>) {
+    assert(array.length === 0, 'The array must be empty')
+
+    this.dense = array
+  }
+
+  [Symbol.iterator](): IterableIterator<number> {
+    return this.values()
+  }
+
+  values(): IterableIterator<number> {
+    return this.dense.values()
+  }
+
+  has(value: number): boolean {
+    return this.sparse[value] !== undefined
+  }
+
+  add(value: number): void {
+    if (!this.has(value)) {
+      const index = this.dense.length
+      this.dense.push(value)
+      this.sparse[value] = index
+    }
+  }
+
+  delete(value: number): boolean {
+    const index = this.sparse[value]
+    if (index !== undefined) {
+      this.sparse[value] = undefined
+
+      const lastValue = this.dense.pop()!
+      if (value !== lastValue) {
+        this.dense.internalTypedArray[index] = lastValue
+        this.sparse[lastValue] = index
+      }
+
+      return true
+    } else {
+      return false
+    }
+  }
+
+  clear(): void {
+    this.dense.clear()
+    this.sparse.length = 0
+  }
+}

package/src/sparse-set/dynamic-typed-clean-sparse-set.ts

@@ -0,0 +1,101 @@
+import { TypedArrayConstructor, UnsignedTypedArrayConstructor } from 'justypes'
+import { DynamicTypedArray } from '@src/dynamic-typed-array.js'
+import { assert } from '@blackglory/errors'
+import { getMaxValueOfUnsignedTypedArray, getMaxValueOfUnsignedTypedArrayConstructor } from '@utils/get-max-value-of-unsigned-typed-array.js'
+import { go } from '@blackglory/go'
+
+export class DynamicTypedCleanSparseSet implements Iterable<number> {
+  private dense: DynamicTypedArray<TypedArrayConstructor>
+  private sparse: DynamicTypedArray<UnsignedTypedArrayConstructor>
+  private readonly NULL: number
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.dense.length
+  }
+
+  constructor(array: DynamicTypedArray<UnsignedTypedArrayConstructor>) {
+    assert(array.length === 0, 'The array must be empty')
+
+    this.dense = array
+
+    const NULL = getMaxValueOfUnsignedTypedArray(array.internalTypedArray)
+               + 1
+    this.NULL = NULL
+
+    const sparseInternalArrayConstructor = go(() => {
+      if (
+        NULL <=
+        getMaxValueOfUnsignedTypedArrayConstructor(Uint8Array)
+      ) {
+        return Uint8Array
+      } else if (
+        NULL <=
+        getMaxValueOfUnsignedTypedArrayConstructor(Uint16Array)
+      ) {
+        return Uint16Array
+      } else if (
+        NULL <=
+        getMaxValueOfUnsignedTypedArrayConstructor(Uint32Array)
+      ) {
+        return Uint32Array
+      } else {
+        throw new Error('The array is too large')
+      }
+    })
+    const sparse = new DynamicTypedArray(sparseInternalArrayConstructor, {
+      fillValue: NULL
+    })
+    this.sparse = sparse
+  }
+
+  [Symbol.iterator](): IterableIterator<number> {
+    return this.values()
+  }
+
+  values(): IterableIterator<number> {
+    return this.dense.values()
+  }
+
+  has(value: number): boolean {
+    const index = this.sparse.get(value)
+    return index !== undefined
+        && index !== this.NULL
+  }
+
+  add(value: number): void {
+    if (!this.has(value)) {
+      const index = this.dense.length
+      this.dense.push(value)
+      this.sparse.set(value, index)
+    }
+  }
+
+  delete(value: number): boolean {
+    const index = this.sparse.get(value)
+    if (
+      index !== undefined &&
+      index !== this.NULL
+    ) {
+      this.sparse.internalTypedArray[value] = this.NULL
+
+      const lastValue = this.dense.pop()!
+      if (value !== lastValue) {
+        this.dense.internalTypedArray[index] = lastValue
+        this.sparse.internalTypedArray[lastValue] = index
+      }
+
+      return true
+    } else {
+      return false
+    }
+  }
+
+  clear(): void {
+    this.dense.clear()
+    this.sparse.clear()
+  }
+}

package/src/sparse-set/dynamic-typed-sparse-set-lite.ts

@@ -0,0 +1,67 @@
+import { DynamicTypedArray } from '@src/dynamic-typed-array.js'
+import { assert } from '@blackglory/errors'
+import { UnsignedTypedArrayConstructor } from 'justypes'
+
+export class DynamicTypedSparseSetLite implements Iterable<number> {
+  private dense: DynamicTypedArray<UnsignedTypedArrayConstructor>
+  private sparse: Array<number | undefined> = []
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.dense.length
+  }
+
+  constructor(array: DynamicTypedArray<UnsignedTypedArrayConstructor>) {
+    assert(array.length === 0, 'The array must be empty')
+
+    this.dense = array
+  }
+
+  [Symbol.iterator](): IterableIterator<number> {
+    return this.values()
+  }
+
+  values(): IterableIterator<number> {
+    return this.dense.values()
+  }
+
+  has(value: number): boolean {
+    const index = this.sparse[value]
+    return index !== undefined
+        && this.dense.get(index) === value
+  }
+
+  add(value: number): void {
+    if (!this.has(value)) {
+      const index = this.dense.length
+      this.dense.push(value)
+      this.sparse[value] = index
+    }
+  }
+
+  delete(value: number): boolean {
+    const index = this.sparse[value]
+    if (
+      index !== undefined &&
+      this.dense.get(index) === value
+    ) {
+      const lastValue = this.dense.pop()!
+      if (value !== lastValue) {
+        this.dense.internalTypedArray[index] = lastValue
+        this.sparse[lastValue] = index
+      }
+
+      return true
+    } else {
+      return false
+    }
+  }
+
+  clear(): void {
+    this.dense.clear()
+    // 无需清空sparse数组.
+  }
+}

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

@@ -0,0 +1,93 @@
+import { UnsignedTypedArrayConstructor } from 'justypes'
+import { DynamicTypedArray } from '@src/dynamic-typed-array.js'
+import { assert } from '@blackglory/errors'
+import { go } from '@blackglory/go'
+import { getMaxValueOfUnsignedTypedArray, getMaxValueOfUnsignedTypedArrayConstructor } from '@utils/get-max-value-of-unsigned-typed-array.js'
+
+export class DynamicTypedSparseSet implements Iterable<number> {
+  private dense: DynamicTypedArray<UnsignedTypedArrayConstructor>
+  private sparse: DynamicTypedArray<UnsignedTypedArrayConstructor>
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.dense.length
+  }
+
+  constructor(array: DynamicTypedArray<UnsignedTypedArrayConstructor>) {
+    assert(array.length === 0, 'The array must be empty')
+
+    this.dense = array
+
+    const sparseInternalArrayConstructor = go(() => {
+      const maxIndex = getMaxValueOfUnsignedTypedArray(array.internalTypedArray)
+                     + 1
+      if (
+        maxIndex <=
+        getMaxValueOfUnsignedTypedArrayConstructor(Uint8Array)
+      ) {
+        return Uint8Array
+      } else if (
+        maxIndex <=
+        getMaxValueOfUnsignedTypedArrayConstructor(Uint16Array)
+      ) {
+        return Uint16Array
+      } else if (
+        maxIndex <=
+        getMaxValueOfUnsignedTypedArrayConstructor(Uint32Array)
+      ) {
+        return Uint32Array
+      } else {
+        throw new Error('The array is too large')
+      }
+    })
+    this.sparse = new DynamicTypedArray(sparseInternalArrayConstructor)
+  }
+
+  [Symbol.iterator](): IterableIterator<number> {
+    return this.values()
+  }
+
+  values(): IterableIterator<number> {
+    return this.dense.values()
+  }
+
+  has(value: number): boolean {
+    const index = this.sparse.get(value)
+    return index !== undefined
+        && this.dense.get(index) === value
+  }
+
+  add(value: number): void {
+    if (!this.has(value)) {
+      const index = this.dense.length
+      this.dense.push(value)
+      this.sparse.set(value, index)
+    }
+  }
+
+  delete(value: number): boolean {
+    const index = this.sparse.get(value)
+    if (
+      index !== undefined &&
+      this.dense.get(index) === value
+    ) {
+      const lastValue = this.dense.pop()!
+      if (value !== lastValue) {
+        this.dense.internalTypedArray[index] = lastValue
+        this.sparse.set(lastValue, index)
+      }
+
+      return true
+    } else {
+      return false
+    }
+  }
+
+  clear(): void {
+    this.dense.clear()
+    // 无需清空sparse数组.
+  }
+}

package/src/sparse-set/index.ts

@@ -0,0 +1,15 @@
+export * from './sparse-set.js'
+export * from './typed-sparse-set.js'
+export * from './typed-sparse-set-lite.js'
+export * from './dynamic-typed-sparse-set.js'
+export * from './dynamic-typed-sparse-set-lite.js'
+export * from './resizable-typed-sparse-set.js'
+export * from './resizable-typed-sparse-set-lite.js'
+
+export * from './clean-sparse-set.js'
+export * from './typed-clean-sparse-set.js'
+export * from './typed-clean-sparse-set-lite.js'
+export * from './dynamic-typed-clean-sparse-set.js'
+export * from './dynamic-typed-clean-sparse-set-lite.js'
+export * from './resizable-typed-clean-sparse-set.js'
+export * from './resizable-typed-clean-sparse-set-lite.js'

package/src/sparse-set/resizable-typed-clean-sparse-set-lite.ts

@@ -0,0 +1,64 @@
+import { UnsignedTypedArrayConstructor } from 'justypes'
+import { ResizableTypedArray } from '@src/resizable-typed-array.js'
+import { assert } from '@blackglory/errors'
+
+export class ResizableTypedCleanSparseSetLite implements Iterable<number> {
+  private dense: ResizableTypedArray<UnsignedTypedArrayConstructor>
+  private sparse: Array<number | undefined> = []
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.dense.length
+  }
+
+  constructor(array: ResizableTypedArray<UnsignedTypedArrayConstructor>) {
+    assert(array.length === 0, 'The array must be empty')
+
+    this.dense = array
+  }
+
+  [Symbol.iterator](): IterableIterator<number> {
+    return this.values()
+  }
+
+  values(): IterableIterator<number> {
+    return this.dense.values()
+  }
+
+  has(value: number): boolean {
+    return this.sparse[value] !== undefined
+  }
+
+  add(value: number): void {
+    if (!this.has(value)) {
+      const index = this.dense.length
+      this.dense.push(value)
+      this.sparse[value] = index
+    }
+  }
+
+  delete(value: number): boolean {
+    const index = this.sparse[value]
+    if (index !== undefined) {
+      this.sparse[value] = undefined
+
+      const lastValue = this.dense.pop()!
+      if (value !== lastValue) {
+        this.dense.internalTypedArray[index] = lastValue
+        this.sparse[lastValue] = index
+      }
+
+      return true
+    } else {
+      return false
+    }
+  }
+
+  clear(): void {
+    this.dense.clear()
+    this.sparse.length = 0
+  }
+}