philiprehberger-csv_kit 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63dcb3883c3732b41c45224ad90e4ae26ea4af2efced584db70089e0b5802be9
-  data.tar.gz: 672c6414f9620772b8cbb664b6cfdbc7a37f76b38d2456cdf72e83d947bca659
+  metadata.gz: ea3cafa68ee9e49b8c1b305af9e7f796a9c417676a6018ee416dbb978e91eb38
+  data.tar.gz: e34151bbdf97d2e78fc348620fd958fa01a3e6d446744593d7a8474b82885de6
 SHA512:
-  metadata.gz: ca664b0389948c7a12793a238f3b94189ef8bc7bbed4aeecdbb431cc986dfad0386f1e621922ba655bdfe85605ba9f2abcdd11550758604d5dad052e6b42d26e
-  data.tar.gz: 973ccc2da16d11249c0dc4c1f1826a42815503b6800bfa9def603f8884dc041e23c37c81ddd9f1fcd719df58438c445a815add96e4de214513f4b6e01f0679c3
+  metadata.gz: a98d2e7baa28c03c04c44322482cc5a9ec4bef939692f5b3812679efe1d4ab1edc90748d65003ea4ddb287a73d27cb6ba22fd4e254ccf734d9c61cd3fbb28cab
+  data.tar.gz: 04a064667d1cbbde06ab473cad6dd18e4edc9558fa5f6efcff5ea2a0505a3c55846f016ebac118735c3b6c4b035bf48edf4c3cf03750c2ba855bf4ec4fc76f4e

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-04-16
+
+### Added
+- `CsvKit.sample(path, n, dialect:)` — return n randomly sampled rows as symbolized hashes using reservoir sampling (Algorithm R); O(n) memory regardless of file size; returns all rows if file has fewer than n rows
+
+## [0.6.0] - 2026-04-15
+
+### Added
+- `CsvKit.find(path, &block)` — return the first row matching a predicate, stopping as soon as a match is found
+
 ## [0.5.0] - 2026-04-09
 
 ### Added
@@ -91,6 +101,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Type coercion and row validation
 - Quick load and filtering convenience methods
 
+[Unreleased]: https://github.com/philiprehberger/rb-csv-kit/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/philiprehberger/rb-csv-kit/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/philiprehberger/rb-csv-kit/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.5.0
 [0.4.0]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.4.0
 [0.3.1]: https://github.com/philiprehberger/rb-csv-kit/releases/tag/v0.3.1

data/README.md

@@ -69,6 +69,24 @@ adults = Philiprehberger::CsvKit.each_hash("data.csv")
   .first(10)
 ```
 
+### Reservoir Sampling
+
+Return n randomly sampled rows with O(n) memory using Knuth's Algorithm R. If the file has fewer than n rows, all rows are returned:
+
+```ruby
+rows = Philiprehberger::CsvKit.sample("large.csv", 100)
+# => [{name: "Alice", age: "30"}, ...]
+```
+
+### Find First Match
+
+Return the first row that matches a predicate, streaming and stopping on the first hit:
+
+```ruby
+user = Philiprehberger::CsvKit.find("users.csv") { |row| row[:email] == "a@b.com" }
+# => {email: "a@b.com", name: "Alice"} or nil
+```
+
 ### Filter Rows
 
 ```ruby
@@ -166,8 +184,10 @@ delimiter = Philiprehberger::CsvKit::Detector.detect("data.tsv")
 | Method / Class | Description |
 |----------------|-------------|
 | `CsvKit.to_hashes(path, dialect:)` | Load CSV into array of symbolized hashes |
+| `CsvKit.sample(path_or_io, n, dialect:)` | Return n randomly sampled rows using reservoir sampling (Algorithm R) |
 | `CsvKit.pluck(path, *keys, dialect:)` | Extract specific columns |
 | `CsvKit.filter(path, dialect:, &block)` | Filter rows, return CSV string |
+| `CsvKit.find(path, dialect:, &block)` | Return the first row matching the predicate, or nil |
 | `CsvKit.headers(path, dialect:)` | Return header row as array of symbols |
 | `CsvKit.count(path, dialect:)` | Count data rows without loading into memory |
 | `CsvKit.each_hash(path, dialect:, &block)` | Stream rows as symbolized hashes; returns Enumerator if no block |

data/lib/philiprehberger/csv_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CsvKit
-    VERSION = '0.5.0'
+    VERSION = '0.7.0'
   end
 end

data/lib/philiprehberger/csv_kit.rb

@@ -100,6 +100,57 @@ module Philiprehberger
       block ? enum.each(&block) : enum
     end
 
+    # Return n randomly sampled rows using reservoir sampling (Algorithm R).
+    # Memory usage is O(n) regardless of file size.
+    # If the file has fewer than n rows, all rows are returned.
+    #
+    # @param path_or_io [String, IO] file path or IO object
+    # @param n [Integer] number of rows to sample
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
+    # @return [Array<Hash{Symbol => String}>]
+    def self.sample(path_or_io, n, dialect: nil)
+      csv_opts = { headers: true }
+      csv_opts = Dialect.new(dialect).merge_into(csv_opts) if dialect
+
+      reservoir = []
+      index = 0
+
+      iterate = lambda do |row|
+        hash = row.to_h.transform_keys(&:to_sym)
+        if index < n
+          reservoir << hash
+        else
+          j = rand(index + 1)
+          reservoir[j] = hash if j < n
+        end
+        index += 1
+      end
+
+      if path_or_io.is_a?(String)
+        CSV.foreach(path_or_io, **csv_opts, &iterate)
+      else
+        CSV.new(path_or_io, **csv_opts).each(&iterate)
+      end
+
+      reservoir
+    end
+
+    # Find the first row matching a predicate, streaming (stops as soon as a match is found).
+    #
+    # @param path [String] file path
+    # @param dialect [Symbol, Hash, nil] CSV dialect preset or custom options
+    # @yield [Hash{Symbol => String}] each row as a symbolized hash
+    # @return [Hash{Symbol => String}, nil] the first matching row or nil
+    def self.find(path, dialect: nil, &block)
+      csv_opts = { headers: true }
+      csv_opts = Dialect.new(dialect).merge_into(csv_opts) if dialect
+      CSV.foreach(path, **csv_opts) do |row|
+        hash = row.to_h.transform_keys(&:to_sym)
+        return hash if block.call(hash)
+      end
+      nil
+    end
+
     # Filter rows and return matching rows as a CSV string.
     #
     # @param path [String] file path

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_kit
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-10 00:00:00.000000000 Z
+date: 2026-04-17 00:00:00.000000000 Z
 dependencies: []
 description: Streaming CSV processor with row-by-row transforms, validations, column
   plucking, streaming each_hash iteration, filtering, writing, error recovery, and