Crate petname 

petname() will generate a single (English) name with a default random number generator:

let name: Option<String> = petname::petname(3, "-");
// e.g. deftly-apt-swiftlet

You can bring your own random number generator from rand:

let mut rng = rand::rngs::ThreadRng::default();
let petnames = petname::Petnames::default();
let name = petnames.namer(7, ":").iter(&mut rng).next().expect("no names");

See that call to namer above? It returned a Namer. Calling iter on that gives a standard Iterator. This is more efficient than calling petname() repeatedly, plus you get all the features of Rust iterators:

let mut rng = rand::rngs::ThreadRng::default();
let petnames = petname::Petnames::default();
let ten_thousand_names: Vec<String> =
  petnames.namer(3, "_").iter(&mut rng).take(10000).collect();

💡 Even more efficient but slightly less convenient is Namer::generate_into.

Word lists

You can populate a petname generator with your own word lists at runtime, but word lists are included with the default-words feature (which is enabled by default). For example, see lang::english::Petnames::small (and medium and large) or lang::turkish::Petnames::small to select a particular built-in word list – or check out the generators’ Default implementations.

Embedding your own word lists

The english! macro – aliased as petnames! – will statically embed your own word lists at compile-time. These are available with the macros feature (enabled by default). This same mechanism is used to embed the default word lists.

A turkish! macro is also available when the lang-turkish feature is enabled.

Basic filtering

You can modify the word lists to, for example, only use words beginning with the letter “b”:

let mut petnames = petname::lang::english::Petnames::default();
petnames.retain(|s| s.starts_with("b"));
let name = petnames.namer(3, ".").iter(&mut rand::rng()).next().expect("no names");
assert!(name.starts_with('b'));

Alliterating

There is another way to generate alliterative petnames, useful in particular when you don’t need or want each name to be limited to using the same initial letter as the previous generated name. Create the Petnames as before, and then convert it into an Alliterations:

let mut petnames = petname::lang::english::Petnames::default();
let mut alliterations: petname::Alliterations = petnames.into();
alliterations.namer(3, "/").iter(&mut rand::rng()).next().expect("no names");

The Generator trait

Both Petnames and Alliterations implement Generator. It’s object-safe so you can use them as trait objects:

use petname::Generator;
let mut buf = String::new();
let petnames: &dyn Generator = &petname::Petnames::default();
petnames.generate_into(&mut buf, &mut rand::rng(), 3, "/");
let alliterations: &dyn Generator = &petname::Alliterations::default();
alliterations.generate_into(&mut buf, &mut rand::rng(), 3, "/");

Re-exports

pub use crate::lang::english::Petnames;

Modules

lang

Language-specific petname generators.

Macros

englishmacros

Construct an English petname generator from word list files at compile time.

petnamesmacros

Alias for english!.

turkishlang-turkish and macros

Construct a Turkish petname generator from word list files at compile time.

Structs

Alliterations

Word lists prepared for alliteration.

Namer

A configured petname generator.

Traits

Generator

Trait that defines a generator of petnames, as consumed by Namer.

Functions

petnamedefault-rng and default-words

Convenience function to generate a new (English) petname from default word lists.

Type Aliases

Words

A word list.