Skip to content

Commit 402a679

Browse files
MukjepScarletMukjepScarlet
committed
Add README
1 parent 75112e9 commit 402a679

3 files changed

Lines changed: 209 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# fastutil4k
2+
3+
Kotlin-first utilities built on top of [fastutil](https://fastutil.di.unimi.it/).
4+
5+
This repository is a multi-module Gradle project:
6+
7+
- `fastutil4k-extensions-only`: generated and hand-written inline Kotlin extension APIs for fastutil and JDK collections.
8+
- `fastutil4k-more-collections`: additional collection implementations built with fastutil data structures.
9+
10+
## Modules
11+
12+
### `fastutil4k-extensions-only`
13+
14+
Provides a large set of extension helpers in package `net.ccbluex.fastutil`, including:
15+
16+
- collection wrappers: `synchronized()` and `unmodifiable()`
17+
- pair helpers: `pair`, `mutPair`, `refPair`, destructuring support
18+
- primitive/object list, set, and map factories
19+
- typed iteration helpers: `forEachInt`, `forEachDoubleIndexed`, `onEachLong`, etc.
20+
- typed array mapping helpers: `mapToIntArray`, `mapToArray`, ...
21+
- function-like operators for fastutil functional interfaces:
22+
`UnaryOperator.invoke`, `BinaryOperator.invoke`, `Predicate.invoke`, `Consumer.invoke`
23+
24+
Most APIs are generated under:
25+
26+
- `fastutil4k-extensions-only/build/generated/fastutil-kt`
27+
28+
The module is designed to be used as `compileOnly` in downstream projects.
29+
30+
### `fastutil4k-more-collections`
31+
32+
Provides higher-level collection utilities and data structures, including:
33+
34+
- `Pool<E>`: reusable object pool with optional finalizer and synchronized wrapper
35+
- `LfuCache<K, V>`: non-thread-safe LFU cache with LRU tie-breaking
36+
- `WeightedSortedList<E>`: bounds-checked list sorted by element weight
37+
- stepped float/double ranges returning fastutil lists (`ClosedRange<Double>.step`, `ClosedRange<Float>.step`)
38+
39+
## Requirements
40+
41+
- JDK 8+ (toolchain target is Java 8)
42+
- Gradle Wrapper (included)
43+
44+
## Build
45+
46+
```bash
47+
./gradlew clean build
48+
```
49+
50+
## Regenerate extension sources
51+
52+
Generated extension sources are produced by module tasks in `fastutil4k-extensions-only`.
53+
54+
```bash
55+
./gradlew :fastutil4k-extensions-only:generate-all
56+
```
57+
58+
## Dependency coordinates
59+
60+
Group:
61+
62+
- `net.ccbluex`
63+
64+
Artifacts:
65+
66+
- `fastutil4k-extensions-only`
67+
- `fastutil4k-more-collections`
68+
69+
Version is defined in the root build script (`build.gradle.kts`).
70+
71+
## License
72+
73+
MIT. See [LICENSE](LICENSE).

‎fastutil4k-extensions-only/README.md‎

Lines changed: 54 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,69 @@
1-
# fastutil-kt-extensions
1+
# fastutil4k-extensions-only
22

3-
This module only contains `inline` functions. So you can use it as `compileOnly` dependency. It won't make your jar archive larger.
3+
Inline Kotlin extension APIs for fastutil and related JDK collection types.
44

5-
Usage:
5+
This module is primarily generated source plus a few hand-written helpers.
6+
Generated files are located at:
7+
8+
- `build/generated/fastutil-kt`
9+
10+
Package namespace:
11+
12+
- `net.ccbluex.fastutil`
13+
14+
## What this module provides
15+
16+
- wrappers:
17+
- `synchronized()` / `synchronized(lock)`
18+
- `unmodifiable()`
19+
- pair helpers:
20+
- infix constructors like `1 pair 2`, `1 mutPair 2`, `1 refPair someRef`
21+
- destructuring support (`component1`, `component2`) for fastutil pairs
22+
- primitive/object collection factories:
23+
- list, set, and map factory helpers
24+
- typed traversal:
25+
- `forEachInt`, `forEachByteIndexed`, `onEachDouble`, ...
26+
- mapping helpers:
27+
- `mapToArray`, `mapToIntArray`, `mapToLongArray`, ...
28+
- invocation operators for fastutil function interfaces:
29+
- `UnaryOperator.invoke`, `BinaryOperator.invoke`
30+
- `Predicate.invoke`, `Consumer.invoke`, `Function.invoke`
31+
32+
All exported APIs are inline, so `compileOnly` is a common usage mode.
33+
34+
## Usage
635

736
```kotlin
837
repositories {
938
maven {
1039
name = "CCBlueX"
1140
url = uri("https://maven.ccbluex.net/releases")
1241
}
42+
mavenCentral()
1343
}
1444

1545
dependencies {
1646
compileOnly("net.ccbluex:fastutil4k-extensions-only:$version")
1747
}
1848
```
49+
50+
## Example
51+
52+
```kotlin
53+
import net.ccbluex.fastutil.*
54+
55+
val list = intListOf(1, 2, 3)
56+
list.forEachIntIndexed { index, value ->
57+
println("$index -> $value")
58+
}
59+
60+
val pair = 10 pair 20
61+
val (left, right) = pair
62+
println("$left / $right")
63+
```
64+
65+
## Regenerate sources
66+
67+
```bash
68+
./gradlew :fastutil4k-extensions-only:generate-all
69+
```

‎fastutil4k-more-collections/README.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# fastutil4k-more-collections
2+
3+
Additional collection utilities built with fastutil data structures.
4+
5+
Package namespace:
6+
7+
- `net.ccbluex.fastutil`
8+
9+
## Features
10+
11+
### `Pool<E>`
12+
13+
Reusable object pool with:
14+
15+
- `borrow()`, `recycle()`, `recycleAll()`
16+
- batch APIs: `borrowInto(...)`, `clearInto(...)`
17+
- optional finalizer callback before recycle
18+
- synchronized wrapper via `pool.synchronized()`
19+
- scoped helper: `Pool.use { ... }`
20+
21+
### `LfuCache<K, V>`
22+
23+
Map-like LFU cache:
24+
25+
- tracks access counts
26+
- evicts least-frequently-used entry when capacity pressure occurs
27+
- uses LRU tie-breaking among same-frequency keys
28+
- optional discard callback (`onDiscard`)
29+
30+
### `WeightedSortedList<E>`
31+
32+
List-like container sorted by weight:
33+
34+
- weight supplied by `ToDoubleFunction<in E>`
35+
- non-decreasing order is enforced on updates
36+
- optional inclusive/exclusive lower and upper bounds
37+
- exposes weight lookup through `Object2DoubleFunction<E>`
38+
39+
### Stepped ranges
40+
41+
- `ClosedRange<Double>.step(step: Double): DoubleList`
42+
- `ClosedRange<Float>.step(step: Float): FloatList`
43+
44+
Returns virtual read-only fastutil lists with O(1) random access and without materializing all values eagerly.
45+
46+
## Usage
47+
48+
```kotlin
49+
repositories {
50+
maven {
51+
name = "CCBlueX"
52+
url = uri("https://maven.ccbluex.net/releases")
53+
}
54+
mavenCentral()
55+
}
56+
57+
dependencies {
58+
implementation("net.ccbluex:fastutil4k-more-collections:$version")
59+
compileOnly("it.unimi.dsi:fastutil:8.5.15")
60+
}
61+
```
62+
63+
## Examples
64+
65+
```kotlin
66+
import net.ccbluex.fastutil.*
67+
68+
val pool = Pool({ StringBuilder() }) { it.clear() }
69+
val text = pool.use { sb ->
70+
sb.append("hello")
71+
sb.toString()
72+
}
73+
74+
val cache = LfuCache<String, Int>(capacity = 2)
75+
cache["a"] = 1
76+
cache["b"] = 2
77+
cache["a"] // increase frequency of "a"
78+
cache["c"] = 3 // evicts "b"
79+
80+
val steps = (0.0..1.0).step(0.25)
81+
println(steps) // [0.0, 0.25, 0.5, 0.75, 1.0]
82+
```

0 commit comments

Comments
 (0)