@blackglory/structures 0.13.3 → 0.14.0

package/src/typed-bit-set.ts

@@ -0,0 +1,129 @@
+import { UnsignedTypedArrayConstructor } from 'justypes'
+import { assert } from '@blackglory/errors'
+import { DynamicTypedArray } from './dynamic-typed-array.js'
+import { trailingZeros } from '@utils/trailing-zeros.js'
+
+export class TypedBitSet<T extends UnsignedTypedArrayConstructor> {
+  private bitsPerElement: number
+  private length = 0
+  private _size = 0
+
+  constructor(private array: DynamicTypedArray<T>) {
+    const bitsPerElement = array.BYTES_PER_ELEMENT * 8
+
+    assert(
+      Number.isInteger(bitsPerElement)
+    , 'The parameter bitsPerElement must be an integer'
+    )
+    assert(
+      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'
+    )
+
+    this.bitsPerElement = bitsPerElement
+  }
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this._size
+  }
+
+  [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.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
+        }
+      }
+    }
+  }
+
+  _dumpBinaryStrings(): string[] {
+    const result: string[] = []
+    for (let i = 0; i < this.array.length; i++) {
+      const binary = this.array.internalTypedArray[i].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')
+    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++
+    }
+    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.bitsPerElement
+    const quotient = (value - remainder) / this.bitsPerElement
+    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/typed-sparse-map.ts

@@ -0,0 +1,97 @@
+import { assert } from '@blackglory/errors'
+import { TypedArrayConstructor, TypedArrayOfConstructor } from 'justypes'
+import { DynamicTypedArray } from './dynamic-typed-array.js'
+
+export class TypedSparseMap<T extends TypedArrayConstructor> {
+  private keyToIndex: Array<number | undefined> = []
+  private indexToKey: number[] = []
+  private indexToValue: DynamicTypedArray<T>
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.indexToKey.length
+  }
+
+  get internalTypedArray(): TypedArrayOfConstructor<T> {
+    return this.indexToValue.internalTypedArray
+  }
+
+  constructor(array: DynamicTypedArray<T>) {
+    assert(array.length === 0, 'array should be empty')
+
+    this.indexToValue = array
+  }
+
+  * entries(): IterableIterator<[key: number, value: number]> {
+    for (let i = 0; i < this.indexToKey.length; i++) {
+      yield [
+        this.indexToKey[i]
+      , this.indexToValue.internalTypedArray[i]
+      ]
+    }
+  }
+
+  keys(): IterableIterator<number> {
+    return this.indexToKey.values()
+  }
+
+  * values(): IterableIterator<number> {
+    for (let i = 0; i < this.indexToKey.length; i++) {
+      yield this.indexToValue.internalTypedArray[i]
+    }
+  }
+
+  getInternalIndexOfKey(key: number): number | undefined {
+    return this.keyToIndex[key]
+  }
+
+  has(key: number): boolean {
+    return key in this.keyToIndex
+  }
+
+  get(key: number): number | undefined {
+    if (this.has(key)) {
+      const index = this.keyToIndex[key]!
+      return this.indexToValue.internalTypedArray[index]
+    } else {
+      return undefined
+    }
+  }
+
+  set(key: number, value: number): void {
+    if (this.has(key)) {
+      const index = this.keyToIndex[key]!
+      this.indexToValue.internalTypedArray[index] = value
+    } else {
+      const index = this.indexToKey.length
+      this.indexToKey.push(key)
+      this.indexToValue.push(value)
+      this.keyToIndex[key] = index
+    }
+  }
+
+  delete(key: number): void {
+    if (this.has(key)) {
+      const lastKey = this.indexToKey.pop()!
+      const lastValue = this.indexToValue.pop()!
+      if (key === lastKey) {
+        delete this.keyToIndex[key]
+      } else {
+        const index = this.keyToIndex[key]!
+        this.indexToKey[index] = lastKey
+        this.indexToValue.internalTypedArray[index] = lastValue
+        this.keyToIndex[lastKey] = index
+        delete this.keyToIndex[key]
+      }
+    }
+  }
+
+  clear(): void {
+    this.keyToIndex.length = 0
+    this.indexToKey.length = 0
+    this.indexToValue.clear()
+  }
+}

package/src/typed-sparse-set.ts

@@ -0,0 +1,71 @@
+import { UnsignedTypedArrayConstructor } from 'justypes'
+import { DynamicTypedArray } from './dynamic-typed-array.js'
+
+export class TypedSparseSet<
+  T extends UnsignedTypedArrayConstructor
+> implements Iterable<number> {
+  private valueToIndex: Array<number | undefined>
+  private indexToValue: DynamicTypedArray<T>
+
+  constructor(array: DynamicTypedArray<T>) {
+    const valueToIndex: Array<number | undefined> = []
+    if (array.length > 0) {
+      for (const [index, value] of array.internalTypedArray.entries()) {
+        valueToIndex[value] = index
+      }
+    }
+
+    this.indexToValue = array
+    this.valueToIndex = valueToIndex
+  }
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  [Symbol.iterator](): IterableIterator<number> {
+    return this.values()
+  }
+
+  get size(): number {
+    return this.indexToValue.length
+  }
+
+  * values(): IterableIterator<number> {
+    for (let i = 0; i < this.indexToValue.length; i++) {
+      yield this.indexToValue.internalTypedArray[i]
+    }
+  }
+
+  has(value: number): boolean {
+    const index = this.valueToIndex[value]
+    return this.indexToValue.internalTypedArray[index!] === value
+  }
+
+  add(value: number): void {
+    if (!this.has(value)) {
+      const index = this.indexToValue.length
+      this.indexToValue.push(value)
+      this.valueToIndex[value] = index
+    }
+  }
+
+  delete(value: number): boolean {
+    const index = this.valueToIndex[value]
+    if (this.indexToValue.internalTypedArray[index!] === value) {
+      const lastValue = this.indexToValue.pop()!
+      if (value !== lastValue) {
+        this.indexToValue.internalTypedArray[index!] = lastValue
+        this.valueToIndex[lastValue] = index
+      }
+      return true
+    } else {
+      return false
+    }
+  }
+
+  clear(): void {
+    this.valueToIndex.length = 0
+    this.indexToValue.clear()
+  }
+}

package/src/utils/skip-list.ts

@@ -0,0 +1,195 @@
+import { isntNull } from 'extra-utils'
+
+export class SkipListNode<T> {
+  previous: SkipListNode<T> | null = null
+  next: SkipListNode<T> | null = null
+  up: SkipListNode<T> | null = null
+  down: SkipListNode<T> | null = null
+
+  constructor(public value: T | null) {}
+}
+
+export class SkipList<T> {
+  // 最顶层的首个节点
+  private head: SkipListNode<T> = new SkipListNode<T>(null)
+  // 最顶层的最后一个节点
+  private tail: SkipListNode<T> = new SkipListNode<T>(null)
+
+  private height: number = 0
+  private _size: number = 0
+
+  // 元素数量
+  get size(): number {
+    return this._size
+  }
+
+  constructor(private compare: (a: T, b: T) => number) {
+    this.head.next = this.tail
+    this.tail.previous = this.head
+  }
+
+  * elements(): IterableIterator<SkipListNode<T>> {
+    let currentNode: SkipListNode<T> = this.head
+
+    while (currentNode.down) {
+      currentNode = currentNode.down
+    }
+
+    while (currentNode.next && isntNull(currentNode.next.value)) {
+      currentNode = currentNode.next
+      yield currentNode
+    }
+  }
+
+  dumpList(): Array<Array<T | null | undefined>> {
+    const result: Array<Array<T | null | undefined>> = []
+    let head: SkipListNode<T> | null = this.head
+
+    do {
+      result.push([])
+      let currentNode: SkipListNode<T> | null = head
+      do {
+        result[result.length - 1].push(currentNode.value)
+        currentNode = currentNode.next
+      } while (currentNode)
+    } while (head = head.down)
+
+    return result
+  }
+
+  delete(value: T): void {
+    let currentNode: SkipListNode<T> | null = this.findNode(value)
+
+    while (currentNode) {
+      // 被删除的节点肯定不会是head或tail, 因此一定有previous
+      currentNode.previous!.next = currentNode.next
+
+      // 被删除的节点肯定不会是head或tail, 因此一定有next
+      currentNode.next!.previous = currentNode.previous
+
+      currentNode = currentNode.down
+    }
+
+    this._size--
+  }
+
+  has(value: T): boolean {
+    return isntNull(this.findNode(value))
+  }
+
+  findNode(value: T): SkipListNode<T> | null {
+    let currentNode: SkipListNode<T> = this.head
+
+    while (true) {
+      while (currentNode.next && isntNull(currentNode.next.value)) {
+        const result = this.compare(currentNode.next.value, value)
+        if (result === 0) {
+          return currentNode.next
+        } else if (result < 0) {
+          currentNode = currentNode.next
+        } else {
+          break
+        }
+      }
+
+      if (currentNode.down) {
+        currentNode = currentNode.down
+      } else {
+        return null
+      }
+    }
+  }
+
+  add(value: T): void {
+    let previousNode: SkipListNode<T> = this.findPreviousNode(value)
+
+    // 如果previousNode.next.value等于value, 则说明value已经存在
+    if (
+      previousNode.next &&
+      isntNull(previousNode.next.value) &&
+      this.compare(previousNode.next.value, value) === 0
+    ) {
+      return
+    }
+
+    let newNode: SkipListNode<T> = new SkipListNode(value)
+    // 在底层加入新节点
+    if (previousNode.next) {
+      newNode.next = previousNode.next
+      previousNode.next.previous = newNode
+    }
+    previousNode.next = newNode
+    newNode.previous = previousNode
+
+    // 在高层加入新节点, 具体加到多高是随机的, 从第一层(将其视作索引值0)开始建造
+    // 层数非常高是极为罕见的, 因为每次建造层都会导致下一层被建造的概率减半.
+    let level = 0
+    while (Math.random() < 0.5) {
+      // currentLevel的索引与当前跳跃列表的高度相同, 需要在这之上建立一个新层
+      if (level === this.height) {
+        const newHead: SkipListNode<T> = new SkipListNode<T>(null)
+        const newTail: SkipListNode<T> = new SkipListNode<T>(null)
+
+        newHead.next = newTail
+        newHead.down = this.head
+
+        newTail.previous = newHead
+        newTail.down = this.tail
+
+        this.head.up = newHead
+        this.tail.up = newTail
+
+        this.head = newHead
+        this.tail = newTail
+
+        this.height++
+      }
+
+      // 从新节点的前一个节点遍历, 直到找到能够通往上层的节点
+      while (!previousNode.up) {
+        // head节点必然会有up, 所以不可能访问进入循环体, 不可能访问`head.previous`
+        previousNode = previousNode.previous!
+      }
+      // 上一层的对应节点
+      previousNode = previousNode.up!
+
+      // 创建新节点的上层节点
+      const upperNewNode: SkipListNode<T> = new SkipListNode<T>(value)
+      if (previousNode.next) {
+        upperNewNode.next = previousNode.next
+        previousNode.next.previous = upperNewNode
+      }
+      previousNode.next = upperNewNode
+      upperNewNode.previous = previousNode
+
+      upperNewNode.down = newNode
+      newNode.up = upperNewNode
+      newNode = upperNewNode
+
+      level++
+    }
+
+    this._size++
+  }
+
+  private findPreviousNode(value: T): SkipListNode<T> {
+    let currentNode: SkipListNode<T> = this.head
+
+    while (true) {
+      while (currentNode.next && isntNull(currentNode.next.value)) {
+        const result = this.compare(currentNode.next.value, value)
+        if (result >= 0) {
+          break
+        } else {
+          currentNode = currentNode.next
+        }
+      }
+
+      if (currentNode.down) {
+        currentNode = currentNode.down
+      } else {
+        return currentNode
+      }
+    }
+  }
+}

package/src/utils/trailing-zeros.ts

@@ -0,0 +1,15 @@
+// http://graphics.stanford.edu/~seander/bithacks.html#ZerosOnRightModLookup
+const mod37BitPositions: number[] = [
+  32, 0, 1, 26, 2, 23, 27, 0, 3, 16
+, 24, 30, 28, 11, 0, 13, 4, 7, 17, 0
+, 25, 22, 31, 15, 29, 10, 12, 6, 0, 21
+, 14, 9, 5, 20, 8, 19, 18
+]
+
+/**
+ * 该函数在找不到结果时返回32, 与Rust内置函数的表现一致.
+ * https://doc.rust-lang.org/std/primitive.u32.html#method.trailing_zeros
+ */
+export function trailingZeros(value: number): number {
+  return mod37BitPositions[(-value & value) % 37]
+}