io-stream 0.8.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f73e60fdaf4001c88fcfaa4ccb29bfc8ee90d2fc3ffc81408c8673b414038ae
-  data.tar.gz: 933183cda89e7d555239ba15a752dadccc938628d6197675b3bedb8cfeb60f43
+  metadata.gz: 506d80a7bb9aee846def3d18d0bf53f2085b751de5d511a8a6a31f8a5de0efd2
+  data.tar.gz: 9c828735d78bdeb4dba18b81ed350f5776ba3436cca7f18b17c465d6efd4ce7e
 SHA512:
-  metadata.gz: 732318c46b27af3ecabb0c99361b60de5ae3c2733013261ae3089fbaa0f4f2f542e70ee10c410227262a8d137a59d5f1e36ba9419307e801fefd0cfebb412ce5
-  data.tar.gz: 5ae80afa0d558011183648ce9d34c02dc52e2b8f0cf24bde53a319d1cba3dd188fa8705a477baa8c7fcd5afeb6ee487087e72c1a75d39c80566ea9c378d4e7b1
+  metadata.gz: 19d26e89eca00835b6331548e72fc74bf17add777028af9bb6d6a7749ee760eab41a5bae780876de278c6f82eeec02366ce83bb160c798cb441a28dbef56f263
+  data.tar.gz: 798d2863752eca4a03d9ae7b21000530442b7a4af218f2e89d1590baa2e821650fcb66689e6ae88ba91b5ec742136ef46c328a7a48afb2d7048990084a12af05

data/lib/io/stream/readable.rb

@@ -58,9 +58,18 @@ module IO::Stream
 
 		# Read data from the stream.
 		# @parameter size [Integer | Nil] The number of bytes to read. If nil, read until end of stream.
-		# @returns [String] The data read from the stream.
-		def read(size = nil)
-			return String.new(encoding: Encoding::BINARY) if size == 0
+		# @parameter buffer [String | Nil] An optional buffer to fill with data instead of allocating a new string.
+		# @returns [String] The data read from the stream, or the provided buffer filled with data.
+		def read(size = nil, buffer = nil)
+			if size == 0
+				if buffer
+					buffer.clear
+					buffer.force_encoding(Encoding::BINARY)
+					return buffer
+				else
+					return String.new(encoding: Encoding::BINARY)
+				end
+			end
 			
 			if size
 				until @done or @read_buffer.bytesize >= size
@@ -74,28 +83,50 @@ module IO::Stream
 				until @done
 					fill_read_buffer
 				end
+				
+				if buffer
+					buffer.replace(@read_buffer)
+					@read_buffer.clear
+				else
+					buffer = @read_buffer
+					@read_buffer = StringBuffer.new
+				end
+				
+				# Read without size always returns a non-nil value, even if it is an empty string.
+				return buffer
 			end
 			
-			return consume_read_buffer(size)
+			return consume_read_buffer(size, buffer)
 		end
 		
 		# Read at most `size` bytes from the stream. Will avoid reading from the underlying stream if possible.
-		def read_partial(size = nil)
-			return String.new(encoding: Encoding::BINARY) if size == 0
+		# @parameter size [Integer | Nil] The number of bytes to read. If nil, read all available data.
+		# @parameter buffer [String | Nil] An optional buffer to fill with data instead of allocating a new string.
+		# @returns [String] The data read from the stream, or the provided buffer filled with data.
+		def read_partial(size = nil, buffer = nil)
+			if size == 0
+				if buffer
+					buffer.clear
+					buffer.force_encoding(Encoding::BINARY)
+					return buffer
+				else
+					return String.new(encoding: Encoding::BINARY)
+				end
+			end
 		
 			if !@done and @read_buffer.empty?
 				fill_read_buffer
 			end
 			
-			return consume_read_buffer(size)
+			return consume_read_buffer(size, buffer)
 		end
 		
 		# Read exactly the specified number of bytes.
 		# @parameter size [Integer] The number of bytes to read.
 		# @parameter exception [Class] The exception to raise if not enough data is available.
 		# @returns [String] The data read from the stream.
-		def read_exactly(size, exception: EOFError)
-			if buffer = read(size)
+		def read_exactly(size, buffer = nil, exception: EOFError)
+			if buffer = read(size, buffer)
 				if buffer.bytesize != size
 					raise exception, "Could not read enough data!"
 				end
@@ -107,8 +138,11 @@ module IO::Stream
 		end
 		
 		# This is a compatibility shim for existing code that uses `readpartial`.
-		def readpartial(size = nil)
-			read_partial(size) or raise EOFError, "Encountered done while reading data!"
+		# @parameter size [Integer | Nil] The number of bytes to read.
+		# @parameter buffer [String | Nil] An optional buffer to fill with data instead of allocating a new string.
+		# @returns [String] The data read from the stream.
+		def readpartial(size = nil, buffer = nil)
+			read_partial(size, buffer) or raise EOFError, "Encountered done while reading data!"
 		end
 		
 		# Find the index of a pattern in the read buffer, reading more data if needed.
@@ -330,25 +364,43 @@ module IO::Stream
 		
 		# Consumes at most `size` bytes from the buffer.
 		# @parameter size [Integer | Nil] The amount of data to consume. If nil, consume entire buffer.
-		def consume_read_buffer(size = nil)
+		# @parameter buffer [String | Nil] An optional buffer to fill with data instead of allocating a new string.
+		# @returns [String | Nil] The consumed data, or nil if no data available.
+		def consume_read_buffer(size = nil, buffer = nil)
 			# If we are at done, and the read buffer is empty, we can't consume anything.
-			return nil if @done && @read_buffer.empty?
+			if @done && @read_buffer.empty?
+				# Clear the buffer even when returning nil
+				if buffer
+					buffer.clear
+					buffer.force_encoding(Encoding::BINARY)
+				end
+				return nil
+			end
 			
 			result = nil
 			
 			if size.nil? or size >= @read_buffer.bytesize
 				# Consume the entire read buffer:
-				result = @read_buffer
+				if buffer
+					buffer.clear
+					buffer << @read_buffer
+					result = buffer
+				else
+					result = @read_buffer
+				end
 				@read_buffer = StringBuffer.new
 			else
-				# This approach uses more memory.
-				# result = @read_buffer.slice!(0, size)
-				
 				# We know that we are not going to reuse the original buffer.
 				# But byteslice will generate a hidden copy. So let's freeze it first:
 				@read_buffer.freeze
 				
-				result = @read_buffer.byteslice(0, size)
+				if buffer
+					# Use replace instead of clear + << for better performance
+					buffer.replace(@read_buffer.byteslice(0, size))
+					result = buffer
+				else
+					result = @read_buffer.byteslice(0, size)
+				end
 				@read_buffer = @read_buffer.byteslice(size, @read_buffer.bytesize)
 			end
 			

data/lib/io/stream/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2023-2024, by Samuel Williams.
 
 module IO::Stream
-	VERSION = "0.8.0"
+	VERSION = "0.9.1"
 end

data/readme.md

@@ -12,6 +12,14 @@ Please see the [project documentation](https://socketry.github.io/io-stream) for
 
 Please see the [project releases](https://socketry.github.io/io-streamreleases/index) for all releases.
 
+### v0.9.1
+
+  - Fix EOF behavior to match Ruby IO semantics: `read()` returns empty string `""` at EOF while `read(size)` returns `nil` at EOF.
+
+### v0.9.0
+
+  - Add support for `buffer` parameter in `read`, `read_exactly`, and `read_partial` methods to allow reading into a provided buffer.
+
 ### v0.8.0
 
   - On Ruby v3.3+, use `IO#write` directly instead of `IO#write_nonblock`, for better performance.
@@ -54,14 +62,6 @@ Please see the [project releases](https://socketry.github.io/io-streamreleases/i
   - Add `#to_io` method to `IO::Stream::Buffered` for better compatibility.
   - Modernize gem structure and dependencies.
 
-### v0.4.0
-
-  - Add convenient `IO.Stream()` constructor method for creating buffered streams.
-
-### v0.3.0
-
-  - Add support for timeouts with compatibility shims for various IO types.
-
 ## See Also
 
   - [async-io](https://github.com/socketry/async-io) — Where this implementation originally came from.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.9.1
+
+  - Fix EOF behavior to match Ruby IO semantics: `read()` returns empty string `""` at EOF while `read(size)` returns `nil` at EOF.
+
+## v0.9.0
+
+  - Add support for `buffer` parameter in `read`, `read_exactly`, and `read_partial` methods to allow reading into a provided buffer.
+
 ## v0.8.0
 
   - On Ruby v3.3+, use `IO#write` directly instead of `IO#write_nonblock`, for better performance.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-stream
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Samuel Williams