io-stream 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c48d464c539d56862e04437f88dee2997e4393951efca83cf622a23bac9e4b75
-  data.tar.gz: 610277102a9233e5d470daabd4f12917d429dc6a141cf52897ff95af3a06de95
+  metadata.gz: 108295b1d28ce05e7c9e9e3f7b3d26427f564a85527a9f23a24ad5b47a261dea
+  data.tar.gz: 2aa1c2f6d600d38667e5030122aecd1faa97f81be44695edf6776dda541d5a89
 SHA512:
-  metadata.gz: 5761c359f16364169757dca90c4f41bfb87269ab3219b6a565b0081aafb3146f2ff6b11e77a95bebd478b31cbc702752e486c484666536f286e4ccdb4a2c6520
-  data.tar.gz: 6e44c1ce99d3741c6c9e8f65976f5664d287586e5a704749466a70992dcfcf5bac55ab84e1429cc5a22417af889ee7938af55ec63081309b3522629a9e05721b
+  metadata.gz: c6c9fc15b84c0ef6d58e2400aeebaac0a36fd67f656dcf10e2f4a1dde2176434dc8f9464809f2b5c05af2563c8bcb1a74ef1e243b7263348d36d24f00df2af7c
+  data.tar.gz: 92c3a90776a6f6308ab7d0fa25d35b7df65021f70cb8aadf01e7363961c818392c2ce3fe861b20b38965acebcca851e7419708ad18b2536ae892496b9ea39ade

data/lib/io/stream/buffered.rb

@@ -106,23 +106,26 @@ module IO::Stream
 			end
 		end
 		
-		def syswrite(buffer)
-			# This fails due to re-entrancy issues with a concurrent call to `sysclose`.
-			# return @io.write(buffer)
-			
-			while true
-				result = @io.write_nonblock(buffer, exception: false)
-				
-				case result
-				when :wait_readable
-					@io.wait_readable(@io.timeout) or raise ::IO::TimeoutError, "read timeout"
-				when :wait_writable
-					@io.wait_writable(@io.timeout) or raise ::IO::TimeoutError, "write timeout"
-				else
-					if result == buffer.bytesize
-						return
+		if RUBY_VERSION >= "3.3"
+			def syswrite(buffer)
+				return @io.write(buffer)
+			end
+		else
+			def syswrite(buffer)
+				while true
+					result = @io.write_nonblock(buffer, exception: false)
+					
+					case result
+					when :wait_readable
+						@io.wait_readable(@io.timeout) or raise ::IO::TimeoutError, "read timeout"
+					when :wait_writable
+						@io.wait_writable(@io.timeout) or raise ::IO::TimeoutError, "write timeout"
 					else
-						buffer = buffer.byteslice(result, buffer.bytesize)
+						if result == buffer.bytesize
+							return
+						else
+							buffer = buffer.byteslice(result, buffer.bytesize)
+						end
 					end
 				end
 			end

data/lib/io/stream/generic.rb

@@ -35,7 +35,7 @@ module IO::Stream
 			return if closed?
 			
 			begin
-				flush
+				self.flush
 			rescue
 				# We really can't do anything here unless we want #close to raise exceptions.
 			ensure

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.
@@ -116,17 +139,28 @@ module IO::Stream
 		# @parameter offset [Integer] The offset to start searching from.
 		# @parameter limit [Integer | Nil] The maximum number of bytes to read while searching.
 		# @returns [Integer | Nil] The index of the pattern, or nil if not found.
-		private def index_of(pattern, offset, limit)
+		private def index_of(pattern, offset, limit, discard = false)
 			# We don't want to split on the pattern, so we subtract the size of the pattern.
 			split_offset = pattern.bytesize - 1
-
+			
 			until index = @read_buffer.index(pattern, offset)
 				offset = @read_buffer.bytesize - split_offset
 				
 				offset = 0 if offset < 0
 				
-				return nil if limit and offset >= limit
-				return nil unless fill_read_buffer
+				if limit and offset >= limit
+					return nil
+				end
+				
+				unless fill_read_buffer
+					return nil
+				end
+				
+				if discard
+					# If we are discarding, we should consume the read buffer up to the offset:
+					consume_read_buffer(offset)
+					offset = 0
+				end
 			end
 			
 			return index
@@ -136,7 +170,8 @@ module IO::Stream
 		# @parameter pattern [String] The pattern to match.
 		# @parameter offset [Integer] The offset to start searching from.
 		# @parameter limit [Integer] The maximum number of bytes to read, including the pattern (even if chomped).
-		# @returns [String | Nil] The contents of the stream up until the pattern, which is consumed but not returned.
+		# @parameter chomp [Boolean] Whether to remove the pattern from the returned data.
+		# @returns [String | Nil] The contents of the stream up until the pattern, or nil if the pattern was not found. 
 		def read_until(pattern, offset = 0, limit: nil, chomp: true)
 			if index = index_of(pattern, offset, limit)
 				return nil if limit and index >= limit
@@ -149,6 +184,28 @@ module IO::Stream
 			end
 		end
 		
+		# Efficiently discard data from the stream until encountering pattern.
+		# @parameter pattern [String] The pattern to match.
+		# @parameter offset [Integer] The offset to start searching from.
+		# @parameter limit [Integer] The maximum number of bytes to read, including the pattern.
+		# @returns [String | Nil] The contents of the stream up until the pattern, or nil if the pattern was not found.
+		def discard_until(pattern, offset = 0, limit: nil)
+			if index = index_of(pattern, offset, limit, true)
+				@read_buffer.freeze
+				
+				if limit and index >= limit
+					@read_buffer = @read_buffer.byteslice(limit, @read_buffer.bytesize)
+					
+					return nil
+				end
+				
+				matched = @read_buffer.byteslice(0, index+pattern.bytesize)
+				@read_buffer = @read_buffer.byteslice(index+pattern.bytesize, @read_buffer.bytesize)
+				
+				return matched
+			end
+		end
+		
 		# Peek at data in the buffer without consuming it.
 		# @parameter size [Integer | Nil] The number of bytes to peek at. If nil, peek at all available data.
 		# @returns [String] The data in the buffer without consuming it.
@@ -296,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.7.0"
+	VERSION = "0.9.0"
 end

data/readme.md

@@ -12,6 +12,15 @@ 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.
+  - Introduce support for `Readable#discard_until` method to discard data until a specific pattern is found.
+
 ### v0.7.0
 
   - Split stream functionality into separate `Readable` and `Writable` modules for better modularity and composition.
@@ -53,15 +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.
-
-### v0.2.0
-
-  - Prefer `write_nonblock` in `syswrite` implementation for better non-blocking behavior.
-  - Add test cases for crash scenarios.
-
 ## See Also
 
   - [async-io](https://github.com/socketry/async-io) — Where this implementation originally came from.

data/releases.md

@@ -1,5 +1,14 @@
 # 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.
+  - Introduce support for `Readable#discard_until` method to discard data until a specific pattern is found.
+
 ## v0.7.0
 
   - Split stream functionality into separate `Readable` and `Writable` modules for better modularity and composition.

metadata

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