io-stream 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f73e60fdaf4001c88fcfaa4ccb29bfc8ee90d2fc3ffc81408c8673b414038ae
-  data.tar.gz: 933183cda89e7d555239ba15a752dadccc938628d6197675b3bedb8cfeb60f43
+  metadata.gz: 108295b1d28ce05e7c9e9e3f7b3d26427f564a85527a9f23a24ad5b47a261dea
+  data.tar.gz: 2aa1c2f6d600d38667e5030122aecd1faa97f81be44695edf6776dda541d5a89
 SHA512:
-  metadata.gz: 732318c46b27af3ecabb0c99361b60de5ae3c2733013261ae3089fbaa0f4f2f542e70ee10c410227262a8d137a59d5f1e36ba9419307e801fefd0cfebb412ce5
-  data.tar.gz: 5ae80afa0d558011183648ce9d34c02dc52e2b8f0cf24bde53a319d1cba3dd188fa8705a477baa8c7fcd5afeb6ee487087e72c1a75d39c80566ea9c378d4e7b1
+  metadata.gz: c6c9fc15b84c0ef6d58e2400aeebaac0a36fd67f656dcf10e2f4a1dde2176434dc8f9464809f2b5c05af2563c8bcb1a74ef1e243b7263348d36d24f00df2af7c
+  data.tar.gz: 92c3a90776a6f6308ab7d0fa25d35b7df65021f70cb8aadf01e7363961c818392c2ce3fe861b20b38965acebcca851e7419708ad18b2536ae892496b9ea39ade

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
@@ -76,26 +85,37 @@ module IO::Stream
 				end
 			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 +127,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 +353,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.0"
 end

data/readme.md

@@ -12,6 +12,10 @@ 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.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.
@@ -58,10 +62,6 @@ Please see the [project releases](https://socketry.github.io/io-streamreleases/i
 
   - 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,9 @@
 # Releases
 
+## 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.0
 platform: ruby
 authors:
 - Samuel Williams