Crate petname 

petname() will generate a single 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 Petnames with your own word lists at runtime, but the word lists from upstream petname are included with the default-words feature (which is enabled by default). See Petnames::small, Petnames::medium, and Petnames::large to select a particular built-in word list, or use Petnames::default.

Embedding your own word lists

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

Basic filtering

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

let mut petnames = petname::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::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, "/");

Macros

petnames

Construct a Petnames from word list files at compile time.

Structs

Alliterations

Word lists prepared for alliteration.

Namer

A configured petname generator.

Petnames

Word lists and the logic to combine them into petnames.

Traits

Generator

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

Functions

petname

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

Type Aliases

Words

A word list.