Skip to content

Commit

Permalink
docs: higlight what's already done
Browse files Browse the repository at this point in the history
Signed-off-by: Art Shendrik <[email protected]>
  • Loading branch information
amal committed Jun 28, 2024
1 parent d783f0b commit 40ea5a1
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 14 deletions.
48 changes: 41 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,50 @@

---

**⚠ Work-In-Progress**. **API isn’t stable yet!**

Library provides cross-platform `RandomAccessData` abstraction for effective read-only random access to binary data.
> [!CAUTION]
> **⚠ Work-In-Progress**.
> **API isn’t completely stable yet!**<br>
> **Benchmarks and complete test coverage are coming.**
Library provides cross-platform [`RandomAccessData`][RandomAccessData]
abstraction for effective read-only random access to binary data.
Both suspend and blocking APIs are provided.
Different platform-specific implementations are provided.


| API | Platform | Supported for |
|------------:|:-------------|:----------------|
| InputStream | JVM, Android | JVM, Android |

> [!TIP]
> For JVM and Android, compatibility with `ByteBuffer` reads and writes is provided.<br>
> An `InputStream' view is also provided for compatibility with existing APIs.

| API | Platform | Supported for |
|-------------------------------------------:|:-------------|:--------------|
| [ByteArray] | All | All |
| [ByteBuffer] | JVM, Android | JVM, Android |
| [ByteBufferMmap]<br>_(memory-mapped file)_ | JVM, Android | JVM, Android |
| [FileChannel] | JVM, Android | JVM, Android |
| [RandomAccessFile] | JVM, Android | JVM, Android |
| [SeekableByteChannel] | JVM, Android | JVM, Android |
| [() -> InputStream] Factory | JVM, Android | JVM, Android |
| [() -> DataInput] Factory | JVM, Android | JVM, Android |
| [() -> ReadableByteChannel] Factory | JVM, Android | JVM, Android |
| [AsynchronousFileChannel] | JVM, Android | JVM, Android |

[RandomAccessData]: fluxo-io-rad/src/commonMain/kotlin/fluxo/io/rad/RandomAccessData.common.kt#29

[ByteArray]: fluxo-io-rad/src/commonMain/kotlin/fluxo/io/rad/RadByteArrayAccessor.kt#L21
[ByteBuffer]: fluxo-io-rad/src/commonJvmMain/kotlin/fluxo/io/rad/ByteBufferRadAccessor.kt#L30
[ByteBufferMmap]: fluxo-io-rad/src/commonJvmMain/kotlin/fluxo/io/rad/ByteBufferRadAccessor.kt#L85
[FileChannel]: fluxo-io-rad/src/commonJvmMain/kotlin/fluxo/io/rad/FileChannelRadAccessor.kt#L28
[RandomAccessFile]: fluxo-io-rad/src/commonJvmMain/kotlin/fluxo/io/rad/RandomAccessFileRadAccessor.kt#L29
[SeekableByteChannel]: fluxo-io-rad/src/commonJvmMain/kotlin/fluxo/io/rad/SeekableByteChannelRadAccessor.kt#L34
[() -> InputStream]: fluxo-io-rad/src/commonJvmMain/kotlin/fluxo/io/rad/StreamFactoryRadAccessor.kt#L62
[() -> DataInput]: fluxo-io-rad/src/commonJvmMain/kotlin/fluxo/io/rad/StreamFactoryRadAccessor.kt#L92
[() -> ReadableByteChannel]: fluxo-io-rad/src/commonJvmMain/kotlin/fluxo/io/rad/StreamFactoryRadAccessor.kt#L122
[AsynchronousFileChannel]: fluxo-io-rad/src/commonJvmMain/kotlin/fluxo/io/rad/AsyncFileChannelRadAccessor.kt#32

_The first steps of the implementation were dated 2021-03-31 (2d87ec044f5801cd3ad8cc31ac380b17fa31d44a)._<br>
_Open-source since 2024-06._

### Versioning

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ public actual interface RandomAccessData : Closeable, AutoCloseable {


/**
* Returns an new [InputStream] that can be used to read the underlying data.
* Returns a new [InputStream] that can be used to read the underlying data.
*
* **The caller is responsible for closing the stream when it is finished!**
*
Expand Down Expand Up @@ -63,8 +63,8 @@ public actual interface RandomAccessData : Closeable, AutoCloseable {
/**
* Reads a single byte of data.
* The byte is returned as an integer in the range 0 to 255 (`0x00..0x0ff`).
* This method blocks if no input is yet available. Method behaves in exactly the same way as
* the [InputStream.read] method.
* This method blocks if no input is yet available.
* Method behaves in the same way as the [InputStream.read] method.
*
* Note that this method can be highly inefficient for some implementations!
* If multiple bytes are to be read, it is generally
Expand Down Expand Up @@ -104,9 +104,8 @@ public actual interface RandomAccessData : Closeable, AutoCloseable {


/**
* Reads a sequence of bytes of data starting at the given [position].
* If the given [position] is greater than the data size at the time that the read is
* attempted then no bytes are read.
* Reads a sequence of data bytes starting at the given [position].
* If the given [position] is greater than the data size no bytes are read.
*
* @param buffer the buffer into which bytes are to be transferred
* @param position the position from which data should be read
Expand All @@ -125,7 +124,7 @@ public actual interface RandomAccessData : Closeable, AutoCloseable {
public fun read(buffer: ByteBuffer, position: Long): Int

/**
* Reads a sequence of bytes of data starting at the given [position].
* Reads a sequence of data bytes starting at the given [position].
* If the given [position] is greater than the data size no bytes are read.
*
* @param buffer the buffer into which bytes are to be transferred
Expand Down

0 comments on commit 40ea5a1

Please sign in to comment.