From fcc06f52699bd367ec5a90c61cb3e8aca2e5b34b Mon Sep 17 00:00:00 2001 From: Ruiyang Sun Date: Thu, 27 Jun 2024 00:03:05 +0800 Subject: [PATCH] doc(readme): rewrite Readme --- README.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index a23931c..39e12e7 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,21 @@ -# ``SyncStream`` +# `StreamUtilities` -SyncStream Package provides two classes, One is SyncStream which is similar to the swift `AsyncStream` but run in synchronous way. The other is `BidirectionalSyncStream` which is inspired by the generator in python, have the ability to send values back to the stream. +`StreamUtilities` is a toolbox providing two utilities for working with stream in swift: + ++ `SyncStream`: a class that generates a sequence of values, inspired by `AsyncStream` from the swift standard library, but operates synchronously. ++ `BidirectionalStream`: aims to bring features similar to Python's Generator to Swift. Users can generate values using `yield`, send values back with `send`, and close the stream by throwing a `StopIteration` error. ## Overview -### SyncStream +### `SyncStream` - `SyncStream` is inspired by Swift's [`AsyncStream`](https://developer.apple.com/documentation/swift/asyncstream) and offers a convenient way to generate a sequence using a closure, without the need to implement the `Sequence` protocol. +[`AsyncStream`](https://developer.apple.com/documentation/swift/asyncstream) offers a convenient method to create a sequence from a closure that invokes a continuation to generate elements. However, in certain cases, you may need to produce a sequence synchronously using a closure. To address this need, we introduce [`SyncStream`](syncstream/syncstream), which shares the same API as `AsyncStream` but operates synchronously. -Just like the [`AsyncStream`](https://developer.apple.com/documentation/swift/asyncstream) , the `SyncStream` also utilizes a class called `Continuation` to manage the production progress. The `Continuation` offers two main methods, `yield(_:)` and `finish`, similar to those in the `AsyncStream`, but operates synchronously. If you are familiar with Python, you can consider the `SyncStream` as a generator. +Here is a simple example of how to use `SyncStream`: ```swift let stream = SyncStream { continuation in - for i in 0..<10 { + for i in 0 ..< 10 { continuation.yield(i) } continuation.finish() @@ -24,12 +27,14 @@ for value in stream { // 0 1 2 3 4 5 6 7 8 9 ``` -### BidirectionalSyncStream +### `BidirectionalStream` -Inspired by the generator in python, which can not only use the `yield` to generate new value, but also can use `send` to sendback value and use `return` to throw `StopIteration` error to stop the stream. The `BidirectionalSyncStream` is a class that provides the same functionality in Swift. +Inspired by Python generators, which not only can use `yield` to produce values, but also can use `send` to receive values, and `return` to raise a `StopIteration` error and halt the stream, the ``BidirectionalSyncStream`` and ``BidirectionalAsyncStream`` in Swift offer similar features for synchronous and asynchronous operations respectively. For more information about the generator in python, See: [PEP 255](https://peps.python.org/pep-0255/), [PEP 342](https://peps.python.org/pep-0342/#new-generator-method-send-value), [Doc](https://docs.python.org/3/reference/expressions.html#generator-iterator-methods) +In the following example, the stream uses the `send(_:)` method to send a value back to the stream, which is received by the `yield(_:)` return value. + ```swift let stream = BidirectionalSyncStream { continuation in var value = 0 @@ -43,7 +48,9 @@ try stream.next() // 0 start the stream try stream.send(5) // 6 send value back to the stream, and get the next value ``` -``` +In the following example, when the stream's closure uses `return(_:)` to stop the streaming process, a `StopIteration` error containing the return value will be caught outside the closure. + +```swift let stream = BidirectionalSyncStream { continuation in var value = 0 while true { @@ -66,8 +73,8 @@ do { ## Contribution -We welcome contributions to HttpX by opening a pull request on GitHub. +We welcome contributions to StreamUtilities by opening a pull request on GitHub. ## License -HttpX is released under the Apache License, Version 2.0. +StreamUtilities is released under the Apache License, Version 2.0.