125 lines
6.0 KiB
Markdown
125 lines
6.0 KiB
Markdown
### Bitmap-Index Library
|
||
[![NPM version][npm-image]][npm-url]
|
||
[![Downloads][downloads-image]][downloads-url]
|
||
|
||
This TypeScript library provides a bitmap implementation (`Bitmap`) that allows efficient manipulation of a bitmap data structure, useful for various indexing and set operations.
|
||
|
||
#### Features
|
||
|
||
- **Set Operations:** `set`, `remove`, `contains`, and `clear` operations on the bitmap.
|
||
- **Logical Operations:** `and`, `andNot`, `or`, and `xor` operations between bitmaps.
|
||
- **Iteration and Filtering:** `range` iteration, generator-based iteration via `[Symbol.iterator]`, and `filter` based on user-defined conditions.
|
||
- **Count and Extremes:** Methods to count set bits (`count`), find the minimum and maximum set bit (`min`, `max`), as well as the minimum and maximum unset bit (`minZero`, `maxZero`).
|
||
- **Cloning:** Supports cloning of the bitmap instance.
|
||
- **Iterable Support:** Can be used directly in `for...of` loops and spread syntax (`[...bitmap]`) for convenient iteration over set bits.
|
||
|
||
#### Installation
|
||
|
||
You can install the library via npm:
|
||
|
||
```bash
|
||
npm install bitmap-index
|
||
````
|
||
|
||
#### Usage Example
|
||
|
||
```typescript
|
||
import { Bitmap } from 'bitmap-index';
|
||
|
||
// Create a new Bitmap with a size of 32 bits
|
||
const bitmap = new Bitmap(32);
|
||
|
||
// Set bits
|
||
bitmap.set(2);
|
||
bitmap.set(5);
|
||
bitmap.set(10);
|
||
|
||
// Check if a bit is set
|
||
console.log(bitmap.contains(5)); // true
|
||
console.log(bitmap.contains(3)); // false
|
||
|
||
// Perform logical operations with another bitmap
|
||
const otherBitmap = new Bitmap(32);
|
||
otherBitmap.set(5);
|
||
otherBitmap.set(10);
|
||
|
||
const andResult = bitmap.and(otherBitmap); // Bitmap with bits [5, 10]
|
||
const orResult = bitmap.or(otherBitmap); // Bitmap with bits [2, 5, 10]
|
||
const xorResult = bitmap.xor(otherBitmap); // Bitmap with bits [2]
|
||
|
||
// Iterate over set bits using range
|
||
bitmap.range((x) => {
|
||
console.log(`Bit ${x} is set`);
|
||
return true; // Continue iterating
|
||
});
|
||
|
||
// Iterate using for...of (generator)
|
||
for (const bit of bitmap) {
|
||
console.log(`Iterated bit: ${bit}`);
|
||
}
|
||
|
||
// Spread operator
|
||
const bitsArray = [...bitmap]; // [2, 5, 10]
|
||
|
||
// Filter based on a condition
|
||
bitmap.filter((x) => x % 2 === 0); // Remove odd-numbered bits
|
||
|
||
// Count the number of set bits
|
||
console.log(bitmap.count()); // 1
|
||
|
||
// Find the minimum and maximum set bits
|
||
console.log(bitmap.min()); // 2
|
||
console.log(bitmap.max()); // 10
|
||
|
||
// Clear all bits
|
||
bitmap.clear();
|
||
|
||
// Clone the bitmap
|
||
const clonedBitmap = bitmap.clone();
|
||
```
|
||
|
||
#### API Documentation
|
||
|
||
* **Bitmap Class**
|
||
|
||
* **Constructor:** `new Bitmap(size: number = 32)`
|
||
* **Set Operations:** `set(x: number)`, `remove(x: number)`, `contains(x: number)`, `clear()`
|
||
* **Logical Operations:** `and(bitmap: Bitmap)`, `andNot(bitmap: Bitmap)`, `or(bitmap: Bitmap)`, `xor(bitmap: Bitmap)`
|
||
* **Iteration and Filtering:** `range(fn: (x: number) => boolean)`, `filter(fn: (x: number) => boolean)`, `[Symbol.iterator](): Iterator<number>`
|
||
* **Count and Extremes:** `count()`, `min()`, `max()`, `minZero()`, `maxZero()`
|
||
* **Cloning:** `clone(): Bitmap`
|
||
|
||
#### Performance
|
||
# Benchmark Results (10k bits)
|
||
|
||
| # | Task | Avg Latency (ns) | Med Latency (ns) | Avg Throughput (ops/s) | Med Throughput (ops/s) | Samples |
|
||
| --- | ------------------------------------ | ------------------ | -------------------- | ---------------------- | ---------------------- | ------- |
|
||
| 0 | set() – random bits | 31,371 ± 1.16% | 29,200 ± 900 | 33,212 ± 0.17% | 34,247 ± 1089 | 15,939 |
|
||
| 1 | set() – sequential bits | 32,537 ± 0.96% | 30,100 ± 700 | 32,169 ± 0.20% | 33,223 ± 755 | 15,368 |
|
||
| 2 | contains() – hit | 28,800 ± 0.86% | 27,200 ± 1000 | 36,235 ± 0.18% | 36,765 ± 1403 | 17,361 |
|
||
| 3 | contains() – miss | 29,773 ± 0.89% | 27,500 ± 600 | 35,239 ± 0.19% | 36,364 ± 811 | 16,794 |
|
||
| 4 | and() – 10k vs 10k | 92,188 ± 0.97% | 79,600 ± 4900 | 11,443 ± 0.50% | 12,563 ± 824 | 5,424 |
|
||
| 5 | or() – 10k vs 10k | 92,291 ± 0.91% | 79,600 ± 5800 | 11,430 ± 0.51% | 12,563 ± 969 | 5,418 |
|
||
| 6 | xor() – 10k vs 10k | 89,627 ± 0.98% | 78,400 ± 3500 | 11,741 ± 0.46% | 12,755 ± 578 | 5,579 |
|
||
| 7 | andNot() – 10k vs 10k | 89,869 ± 0.92% | 79,500 ± 1800 | 11,642 ± 0.43% | 12,579 ± 278 | 5,564 |
|
||
| 8 | for…of iteration | 145,013 ± 0.48% | 139,100 ± 1700 | 6,990 ± 0.32% | 7,189 ± 87 | 3,448 |
|
||
| 9 | [...bmp] spread | 245,514 ± 0.69% | 237,200 ± 3200 | 4,130 ± 0.40% | 4,216 ± 56 | 2,037 |
|
||
| 10 | filter(x => x % 2 === 0) | 360,279 ± 0.66% | 352,300 ± 1100 | 2,797 ± 0.33% | 2,838 ± 9 | 1,388 |
|
||
| 11 | BigInt alternative – set random bits | 27,976,819 ± 1.43% | 27,535,900 ± 690,250 | 36 ± 1.26% | 36 ± 1 | 64 |
|
||
| 12 | Set<number> – add sequential | 246,334 ± 4.63% | 219,700 ± 7700 | 4,454 ± 0.47% | 4,552 ± 163 | 2,030 |
|
||
| 13 | Set<number> – has() hits | 256,280 ± 5.11% | 224,350 ± 12,050 | 4,346 ± 0.55% | 4,457 ± 245 | 1,952 |
|
||
|
||
|
||
#### Note
|
||
|
||
This library is designed for bitmap indexing operations and is not related to image processing. For more information on bitmap indexing, please refer to [Bitmap Index Wiki](https://en.wikipedia.org/wiki/Bitmap_index).
|
||
|
||
---
|
||
|
||
Feel free to contribute, report issues, or suggest improvements on [GitHub](https://github.com/yazmeyaa/bitmap-index).
|
||
|
||
[npm-image]: https://img.shields.io/npm/v/bitmap-index.svg?style=flat-square
|
||
[npm-url]: https://npmjs.org/package/bitmap-index
|
||
[downloads-image]: https://img.shields.io/npm/dm/bitmap-index.svg?style=flat-square
|
||
[downloads-url]: https://npmjs.org/package/bitmap-index
|