@blackglory/structures 0.13.3 → 0.13.4

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@blackglory/structures",
-  "version": "0.13.3",
+  "version": "0.13.4",
   "description": "",
   "files": [
-    "lib"
+    "lib",
+    "src"
   ],
   "type": "module",
   "main": "lib/index.js",

package/src/array.ts

@@ -0,0 +1,19 @@
+export function sliceArrayLeft<T>(arr: T[], num: number): T[] {
+  return arr.slice(0, num)
+}
+
+export function sliceArrayRight<T>(arr: T[], num: number): T[] {
+  const startIndex = arr.length - num
+  return arr.slice(startIndex >= 0 ? startIndex : 0)
+}
+
+export function truncateArrayLeft<T>(arr: T[], num: number): void {
+  if (arr.length > num) {
+    arr.length = num
+  }
+}
+
+export function truncateArrayRight<T>(arr: T[], num: number): void {
+  const startIndex = arr.length - num
+  arr.splice(0, startIndex)
+}

package/src/big-map.ts

@@ -0,0 +1,98 @@
+/**
+ * A `Map` that supports unlimited elements.
+ * 
+ * Note that `BigMap` cannot preserve the insertion order of elements.
+ */
+export class BigMap<K, V> implements Iterable<[K, V]> {
+  _maps: Array<Map<K, V>> = []
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this._maps
+      .map(map => map.size)
+      .reduce((acc, cur) => acc + cur, 0)
+  }
+
+  * [Symbol.iterator](): IterableIterator<[K, V]> {
+    for (const map of this._maps) {
+      yield* map[Symbol.iterator]()
+    }
+  }
+
+  set(key: K, value: V): void {
+    {
+      const map = this._maps.find(map => map.has(key))
+      if (map) {
+        map.set(key, value)
+        return
+      }
+    }
+
+    for (const map of this._maps) {
+      try {
+        map.set(key, value)
+        return
+      } catch (e) {
+        if (e instanceof RangeError) continue
+        throw e
+      }
+    }
+
+    const map = new Map<K, V>()
+    map.set(key, value)
+    this._maps.push(map)
+  }
+
+  has(key: K): boolean {
+    return this._maps.some(set => set.has(key))
+  }
+
+  get(key: K): V | undefined {
+    for (const map of this._maps) {
+      if (map.has(key)) {
+        return map.get(key)!
+      }
+    }
+  }
+
+  delete(key: K): boolean {
+    for (const [index, map] of this._maps.entries()) {
+      if (map.has(key)) {
+        map.delete(key)
+
+        if (map.size === 0) {
+          this._maps.splice(index, 1)
+        }
+
+        return true
+      }
+    }
+
+    return false
+  }
+
+  clear(): void {
+    this._maps = []
+  }
+
+  * entries(): IterableIterator<[K, V]> {
+    for (const map of this._maps) {
+      yield* map.entries()
+    }
+  }
+
+  * keys(): IterableIterator<K> {
+    for (const map of this._maps) {
+      yield* map.keys()
+    }
+  }
+
+  * values(): IterableIterator<V> {
+    for (const map of this._maps) {
+      yield* map.values()
+    }
+  }
+}

package/src/big-set.ts

@@ -0,0 +1,72 @@
+/**
+ * A `Set` that supports unlimited elements.
+ * 
+ * Note that `BigSet` cannot preserve the insertion order of elements.
+ */
+export class BigSet<T> implements Iterable<T> {
+  _sets: Array<Set<T>> = []
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this._sets
+      .map(set => set.size)
+      .reduce((acc, cur) => acc + cur, 0)
+  }
+
+  * [Symbol.iterator](): IterableIterator<T> {
+    for (const set of this._sets) {
+      yield* set[Symbol.iterator]()
+    }
+  }
+
+  add(value: T): void {
+    if (this._sets.some(set => set.has(value))) return
+
+    for (const set of this._sets) {
+      try {
+        set.add(value)
+        return
+      } catch (e) {
+        if (e instanceof RangeError) continue
+        throw e
+      }
+    }
+
+    const set = new Set<T>()
+    set.add(value)
+    this._sets.push(set)
+  }
+
+  has(value: T): boolean {
+    return this._sets.some(set => set.has(value))
+  }
+
+  delete(value: T): boolean {
+    for (const [index, set] of this._sets.entries()) {
+      if (set.has(value)) {
+        set.delete(value)
+
+        if (set.size === 0) {
+          this._sets.splice(index, 1)
+        }
+
+        return true
+      }
+    }
+
+    return false
+  }
+
+  clear(): void {
+    this._sets = []
+  }
+
+  * values(): IterableIterator<T> {
+    for (const set of this._sets) {
+      yield* set.values()
+    }
+  }
+}

package/src/bit-set.ts

@@ -0,0 +1,124 @@
+import { assert } from '@blackglory/errors'
+import { trailingZeros } from '@utils/trailing-zeros.js'
+
+export class BitSet {
+  private array: number[] = []
+  private length = 0
+  private _size = 0
+
+  constructor(private bitsPerElement: number = 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'
+    )
+  }
+
+  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[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[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[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[index] ?? 0
+    this.array[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[index] ?? 0)
+    this.array[index] = element & ~mask
+
+    const deleted = (element & mask) === mask
+    if (deleted) {
+      this._size--
+    }
+
+    return deleted
+  }
+
+  clear(): void {
+    this._size = 0
+    this.array.length = 0
+  }
+
+  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/box.ts

@@ -0,0 +1,15 @@
+export class Box<T> {
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  constructor(private value: T) {}
+
+  set(value: T): void {
+    this.value = value
+  }
+
+  get(): T {
+    return this.value
+  }
+}

package/src/cons.ts

@@ -0,0 +1,15 @@
+import { isNull } from 'extra-utils'
+import { Cons } from 'justypes'
+export { Cons } from 'justypes'
+
+export function convertConsToArray<T>([value, next]: Cons<T>): T[] {
+  if (isNull(next)) {
+    return [value]
+  } else {
+    return [value, ...convertConsToArray(next)]
+  }
+}
+
+export function convertArrayToCons<T>([value, ...next]: T[]): Cons<T> {
+  return [value, next.length ? convertArrayToCons(next) : null]
+}

package/src/dynamic-typed-array.ts

@@ -0,0 +1,201 @@
+import { TypedArrayConstructor, TypedArrayOfConstructor } from 'justypes'
+import { assert } from '@blackglory/errors'
+
+interface IDynamicTypedArrayOptions {
+  capacity?: number
+  growthFactor?: number
+}
+
+// 相关提案: https://github.com/tc39/proposal-resizablearraybuffer
+export class DynamicTypedArray<T extends TypedArrayConstructor> {
+  private array: TypedArrayOfConstructor<T>
+  private _length: number = 0
+  private initialCapacity: number
+  readonly growthFactor: number
+
+  get internalTypedArray(): TypedArrayOfConstructor<T> {
+    return this.array
+  }
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get BYTES_PER_ELEMENT(): number {
+    return this.typedArrayConstructor.BYTES_PER_ELEMENT
+  }
+
+  /**
+   * 数组当前的容量.
+   */
+  get capacity(): number {
+    return this.array.length
+  }
+
+  /**
+   * 数组逻辑上的长度, 总是小于或等于capacity.
+   */
+  get length(): number {
+    return this._length
+  }
+
+  constructor(
+    private typedArrayConstructor: T
+  , {
+      capacity = 0
+    , growthFactor = 1.5
+    }: 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')
+
+    this.initialCapacity = capacity
+    this.array = new typedArrayConstructor(capacity) as TypedArrayOfConstructor<T>
+    this.growthFactor = growthFactor
+  }
+
+  set(index: number, value: number): void {
+    if (index >= this.capacity) {
+      const newCapacity = computeNewCapacity(
+        this.capacity
+      , index + 1
+      , this.growthFactor
+      )
+      this.resize(newCapacity)
+    }
+
+    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) {
+      const newCapacity = computeNewCapacity(
+        this.capacity
+      , index + values.length
+      , this.growthFactor
+      )
+      this.resize(newCapacity)
+    }
+
+    if (index + values.length > this._length) {
+      this._length = index + values.length
+    }
+
+    this.internalTypedArray.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) {
+      const newCapacity = computeNewCapacity(
+        this.capacity
+      , newLength
+      , this.growthFactor
+      )
+      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--
+
+      const newCapacity = computeNewCapacity(
+        this.capacity
+      , this.length
+      , this.growthFactor
+      )
+      this.resize(newCapacity)
+
+      return value
+    } else {
+      return undefined
+    }
+  }
+
+  clear(): void {
+    this._length = 0
+    const newArray = new this.typedArrayConstructor(this.initialCapacity)
+    this.array = newArray as TypedArrayOfConstructor<T>
+  }
+
+  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) {
+      const newArray = new this.typedArrayConstructor(newCapacity)
+      newArray.set(this.array)
+      this.array = newArray as TypedArrayOfConstructor<T>
+    } else if (this.array.length > newCapacity) {
+      const newArray = new this.typedArrayConstructor(newCapacity)
+      // 不需要的部分将被舍弃.
+      for (let i = newCapacity; i--;) {
+        newArray[i] = this.array[i]
+      }
+      this.array = newArray as TypedArrayOfConstructor<T>
+    }
+  }
+}
+
+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/emitter.ts

@@ -0,0 +1,76 @@
+import { go } from '@blackglory/go'
+
+type Listener<Args extends unknown[]> = (...args: Args) => void
+
+export class Emitter<
+  EventToArgs extends Record<Event, unknown[]> = Record<
+    string | number | symbol
+  , unknown[]
+  >
+, Event extends string | number | symbol = keyof EventToArgs
+> {
+  private map = new Map<
+    Event
+  , Set<Listener<EventToArgs[Event]>>
+  >()
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  on<T extends Event>(
+    event: T
+  , listener: Listener<EventToArgs[T]>
+  ): () => void {
+    const set = go(() => {
+      const set = this.map.get(event)
+      if (set) {
+        return set
+      } else {
+        const set = new Set<Listener<EventToArgs[keyof EventToArgs]>>()
+        this.map.set(event, set)
+        return set
+      }
+    })
+    set.add(handler as Listener<EventToArgs[Event]>)
+
+    return () => {
+      const handlers = this.map.get(event)
+      if (handlers) {
+        const deleted = handlers.delete(
+          handler as Listener<EventToArgs[Event]>
+        )
+        if (deleted && handlers.size === 0) {
+          this.map.delete(event)
+        }
+      }
+    }
+
+    function handler(...args: Parameters<Listener<EventToArgs[T]>>): void {
+      listener(...args)
+    }
+  }
+
+  once<T extends Event>(
+    event: T
+  , listener: Listener<EventToArgs[T]>
+  ): () => void {
+    const removeListener = this.on(
+      event
+    , (...args: Parameters<Listener<EventToArgs[T]>>) => {
+        listener(...args)
+        removeListener()
+      }
+    )
+
+    return removeListener
+  }
+
+  emit<T extends Event>(event: T, ...args: EventToArgs[T]): void {
+    this.map.get(event)?.forEach(cb => cb(...args))
+  }
+
+  removeAllListeners<T extends Event>(event: T): void {
+    this.map.get(event)?.clear()
+  }
+}