name_bank 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 184aced32d90cfa194129bdb48895055b2738ed7bef92c1c1a42532421e6e4c6
-  data.tar.gz: 6305e8defeb53e8a6bbb2d7fd47e73a41c6e870cd83659dfad56f24a96f3ebd8
+  metadata.gz: 6e238aa5013b3c3a8513f0bd233bb7365f7703c6f852270d93044ee424f6df95
+  data.tar.gz: 697fe182bc1222111617ca9dd2803d208cff375aff171b41d42bf32047cef45c
 SHA512:
-  metadata.gz: 4eae078ebdd3bab2e6c3d455d3c783a6d03b5d119c386017c81d76e5ead0312e066cc24911621506b8c3b7637a88f679a1f5b8b1dfd3202427c0f274a3d3ef87
-  data.tar.gz: 3c7ea3d49e618280f40734193e487c61fc5c6a9c762a16925843533099e7e727feb693dd9c22a1453a29d63316c962506199a493f7469a898ef559f5f5f3020a
+  metadata.gz: 12411b5e09c5e83bcecefc555c7568843832ed4a37c42553d5fc8efef2c1f4699f828731b1ac68c7e5cd1db93fdbc2baf8be34207553f67bb901b9e2fbc05c6f
+  data.tar.gz: f959d2ec630d8d53cf461c22dfa261935e8369e866d95ce513d5e64c86b42082c0c5622ce129d4e41bce9d42a87a7182c82202baa8c842b34b478e34b61ad2ab

data/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-08-16
+
+Many names in one call. Nothing that worked before changes: sampling from the
+existing methods is byte-identical to 0.3.0 over 2830 samples across every
+country, script and variant, and the name data is untouched.
+
+### Added
+- `full_names(country:, gender:, rng:, count:)` draws that many distinct
+  given/family pairs in one call — the shape a database seed needs. No pair
+  repeats; single names do, because only the pair is unique. The guarantee
+  holds within one call, so no state is kept between calls and sampling stays
+  a function of the caller's RNG. `count:` is required, and asking for more
+  pairs than the two pools can form raises the new `NameBank::PoolExhausted`
+  rather than silently returning fewer.
+
+### Fixed
+- README: the first usage example showed a name pair that the seed above it
+  never produces. Every `# =>` in the README is now the value the code actually
+  returns, checked against the shipped pools. The sampling examples under
+  *Scripts* and *Variants* name their seed too, so all of them can be
+  reproduced rather than taken on trust. No code or data changed.
+
 ## [0.3.0] - 2026-08-11
 
 Lookup, documentation and one platform bug. Sampling behaviour and the name

data/README.md

@@ -27,23 +27,23 @@ gem install name_bank
 ```ruby
 require "name_bank"
 
-rng = Random.new(1234)
+rng = Random.new(10246)
 
 # A full name (given + family) for a country and gender:
 NameBank.full_name(country: "DE", gender: :female, rng: rng)
-# => { firstname: "Sabine", lastname: "Müller" }
+# => { firstname: "Alexandra", lastname: "Werner" }
 
 # Just a given name or a surname:
-NameBank.first_name(country: "IT", gender: :male, rng: rng)   # => "Amor"
-NameBank.last_name(country: "JP", rng: rng)                   # => "Tsuru"
+NameBank.first_name(country: "IT", gender: :male, rng: rng)   # => "Settimio"
+NameBank.last_name(country: "JP", rng: rng)                   # => "Katsuta"
 
 # Latin (default), or the country's native script where it has one:
-NameBank.first_name(country: "JP", gender: :female, rng: rng)                   # => "Sasahara"
-NameBank.first_name(country: "JP", gender: :female, rng: rng, script: :native)  # => "ちゃこ"
+NameBank.first_name(country: "JP", gender: :female, rng: rng)                   # => "Misako"
+NameBank.first_name(country: "JP", gender: :female, rng: rng, script: :native)  # => "さえ"
 
 # Default pool, or an alternate cultural pool where one exists:
-NameBank.first_name(country: "US", gender: :male, rng: rng)                               # => "Abe"
-NameBank.first_name(country: "US", gender: :male, rng: rng, variant: "african_american")  # => "Roosevelt"
+NameBank.first_name(country: "US", gender: :male, rng: rng)                               # => "Jonah"
+NameBank.first_name(country: "US", gender: :male, rng: rng, variant: "african_american")  # => "Tyrone"
 
 # List available countries (ISO alpha-2 codes):
 NameBank.countries.size       # => 106
@@ -54,10 +54,38 @@ Sampling is uniform over each pool and fully deterministic for a given
 `rng` — the same seed always yields the same name. `gender:` is `:male`
 or `:female`.
 
+## Many at once
+
+Seeding a table wants many names in one call, and wants them to differ.
+`full_names` draws distinct given/family pairs:
+
+```ruby
+rng = Random.new(24134)
+
+NameBank.full_names(country: "DE", gender: :female, rng: rng, count: 3)
+# => [{ firstname: "Gerlinde", lastname: "Nowak" },
+#     { firstname: "Juliane",  lastname: "Stark" },
+#     { firstname: "Kornelia", lastname: "Lenz" }]
+```
+
+No pair is drawn twice. Single names do recur once the draw is large enough —
+only the pair is unique, which is what a real population looks like. The
+guarantee holds within one call; two calls know nothing of each other.
+
+`count:` is required, because there is no pool of pairs to hand back without
+one. A country can form as many pairs as given names × surnames: 1500 × 1500
+for most, 30 × 30 for the hand-curated `CN` and `UA` pools. Asking for more
+raises rather than quietly returning fewer:
+
+```ruby
+NameBank.full_names(country: "UA", gender: :male, rng: rng, count: 901)
+# => NameBank::PoolExhausted: UA: 901 pairs requested, 900 available
+```
+
 ## Whole pools
 
-Where sampling one name is not enough — drawing many names without repeats,
-applying your own weighting, or checking what a country actually ships —
+Where sampling is not enough — applying your own weighting, drawing single
+names without repeats, or checking what a country actually ships —
 take the pool itself. `first_names` and `last_names` accept the same
 `country:`, `variant:` and `script:` options as the samplers, and return the
 frequency-ordered pool as a frozen array:
@@ -68,6 +96,11 @@ NameBank.first_names(country: "DE", gender: :female).first(3)  # => ["Nicole", "
 NameBank.last_names(country: "JP", script: :native).first(3)   # => ["佐藤", "鈴木", "田中"]
 ```
 
+For single names without repeats, the pool plus Ruby is the whole answer:
+`pool.sample(200, random: rng)` returns 200 different names, deterministically.
+Note that `Array#sample` returns fewer than asked for rather than complaining
+when the pool is too small — unlike `full_names`, which raises.
+
 Every method shown so far is also available on an instance, which lets you
 point name_bank at your own directory of pool files:
 `NameBank.new(data_dir: "…").first_name(country: "DE", gender: :male, rng: rng)`.
@@ -153,6 +186,8 @@ Names come in Latin (default) and, for countries with a non-Latin writing
 system, their native script. Pass `script:`:
 
 ```ruby
+rng = Random.new(325089)
+
 NameBank.first_name(country: "RU", gender: :male, rng: rng)                  # => "Dmitry"
 NameBank.first_name(country: "RU", gender: :male, rng: rng, script: :native) # => "Алексей"
 
@@ -179,6 +214,8 @@ Some countries offer an alternate cultural name pool layered on the default.
 Pass `variant:`:
 
 ```ruby
+rng = Random.new(41)
+
 NameBank.first_name(country: "US", gender: :male, rng: rng, variant: "african_american")
 # => "DeShawn"
 
@@ -199,10 +236,11 @@ still catches the two that are genuinely caller mistakes:
 | `NameBank::UnknownCountry` | `StandardError` | no pool file for that country code |
 | `NameBank::UnknownVariant` | `StandardError` | no pool file for that variant |
 | `NameBank::EmptyPool` | `StandardError` | the pool exists but holds no names |
+| `NameBank::PoolExhausted` | `StandardError` | `full_names` was asked for more distinct pairs than the pools can form |
 | `NameBank::MalformedPool` | `StandardError` | a pool file is missing a key, or holds something other than a list |
 
-The last two cannot occur with the shipped data; they matter when you point
-`NameBank.new(data_dir:)` at pool files of your own.
+`EmptyPool` and `MalformedPool` cannot occur with the shipped data; they matter
+when you point `NameBank.new(data_dir:)` at pool files of your own.
 
 ```ruby
 begin

data/lib/name_bank/errors.rb

@@ -28,6 +28,11 @@ class NameBank
     include Error
   end
 
+  # More distinct pairs were asked for than the pools can form.
+  class PoolExhausted < StandardError
+    include Error
+  end
+
   # script: was neither :latin nor :native.
   class UnknownScript < ArgumentError
     include Error

data/lib/name_bank/version.rb

@@ -2,5 +2,5 @@
 
 # Declared as a class, not a module: NameBank itself is one (see lib/name_bank.rb).
 class NameBank
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/name_bank.rb

@@ -27,6 +27,7 @@ class NameBank
     def first_name(...) = default.first_name(...)
     def last_name(...) = default.last_name(...)
     def full_name(...) = default.full_name(...)
+    def full_names(...) = default.full_names(...)
     def first_names(...) = default.first_names(...)
     def last_names(...) = default.last_names(...)
     def countries(...) = default.countries(...)
@@ -53,6 +54,21 @@ class NameBank
     }
   end
 
+  # Distinct given/family pairs, for seeding many rows at once. No pair is drawn
+  # twice; single names do recur, which is what a population looks like. The
+  # guarantee holds within one call — two calls know nothing of each other.
+  # Asking for more pairs than the two pools can form raises PoolExhausted.
+  def full_names(country:, gender:, rng:, count:, variant: nil, script: :latin)
+    firsts = first_names(country: country, gender: gender, variant: variant, script: script)
+    lasts = last_names(country: country, variant: variant, script: script)
+    available = firsts.size * lasts.size
+    raise PoolExhausted, "#{country}: #{count} pairs requested, #{available} available" if count > available
+
+    distinct_indices(available, count, rng).map do |index|
+      { firstname: firsts[index / lasts.size], lastname: lasts[index % lasts.size] }
+    end
+  end
+
   # The whole frequency-ordered pool, frozen. The name strings stay mutable.
   def first_names(country:, gender:, variant: nil, script: :latin)
     pool(country, variant, PoolSchema.gender_key(gender), script)
@@ -79,6 +95,20 @@ class NameBank
 
   private
 
+  # Partial Fisher-Yates over the space of pair indices, with the swaps kept in
+  # a Hash so that the untouched majority of a two-million-pair space is never
+  # built. Drawing every pair a country has takes count steps; drawing at random
+  # until enough distinct pairs turn up would stall on the last few.
+  def distinct_indices(available, count, rng)
+    swapped = {}
+    Array.new(count) do |drawn|
+      index = rng.rand(drawn...available)
+      picked = swapped.fetch(index, index)
+      swapped[index] = swapped.fetch(drawn, drawn)
+      picked
+    end
+  end
+
   def pool(country, variant, key, script)
     names = names_for_script(@store.pools(country, variant), key, script)
     raise EmptyPool, "#{country}/#{script}" if names.empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: name_bank
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Patrick Bartels