names/
lib.rs

1//! This crate provides a generate that constructs random name strings suitable
2//! for use in container instances, project names, application instances, etc.
3//!
4//! The name `Generator` implements the `Iterator` trait so it can be used with
5//! adapters, consumers, and in loops.
6//!
7//! ## Usage
8//!
9//! This crate is [on crates.io](https://crates.io/crates/names) and can be
10//! used by adding `names` to your dependencies in your project's `Cargo.toml`
11//! file:
12//!
13//! ```toml
14//! [dependencies]
15//! names = { version = "0.14.0", default-features = false }
16//! ```
17//! ## Examples
18//!
19//! ### Example: painless defaults
20//!
21//! The easiest way to get started is to use the default `Generator` to return
22//! a name:
23//!
24//! ```
25//! use names::Generator;
26//!
27//! let mut generator = Generator::default();
28//! println!("Your project is: {}", generator.next().unwrap());
29//! // #=> "Your project is: rusty-nail"
30//! ```
31//!
32//! If more randomness is required, you can generate a name with a trailing
33//! 4-digit number:
34//!
35//! ```
36//! use names::{Generator, Name};
37//!
38//! let mut generator = Generator::with_naming(Name::Numbered);
39//! println!("Your project is: {}", generator.next().unwrap());
40//! // #=> "Your project is: pushy-pencil-5602"
41//! ```
42//!
43//! ### Example: with custom dictionaries
44//!
45//! If you would rather supply your own custom adjective and noun word lists,
46//! you can provide your own by supplying 2 string slices. For example,
47//! this returns only one result:
48//!
49//! ```
50//! use names::{Generator, Name};
51//!
52//! let adjectives = &["imaginary"];
53//! let nouns = &["roll"];
54//! let mut generator = Generator::new(adjectives, nouns, Name::default());
55//!
56//! assert_eq!("imaginary-roll", generator.next().unwrap());
57//! ```
58
59#![doc(html_root_url = "https://docs.rs/names/0.14.0")]
60#![deny(missing_docs)]
61
62use rand::{rngs::ThreadRng, seq::SliceRandom, Rng};
63
64/// List of English adjective words
65pub const ADJECTIVES: &[&str] = &include!(concat!(env!("OUT_DIR"), "/adjectives.rs"));
66
67/// List of English noun words
68pub const NOUNS: &[&str] = &include!(concat!(env!("OUT_DIR"), "/nouns.rs"));
69
70/// A naming strategy for the `Generator`
71pub enum Name {
72    /// This represents a plain naming strategy of the form `"ADJECTIVE-NOUN"`
73    Plain,
74    /// This represents a naming strategy with a random number appended to the
75    /// end, of the form `"ADJECTIVE-NOUN-NUMBER"`
76    Numbered,
77}
78
79impl Default for Name {
80    fn default() -> Self {
81        Name::Plain
82    }
83}
84
85/// A random name generator which combines an adjective, a noun, and an
86/// optional number
87///
88/// A `Generator` takes a slice of adjective and noun words strings and has
89/// a naming strategy (with or without a number appended).
90pub struct Generator<'a> {
91    adjectives: &'a [&'a str],
92    nouns: &'a [&'a str],
93    naming: Name,
94    rng: ThreadRng,
95}
96
97impl<'a> Generator<'a> {
98    /// Constructs a new `Generator<'a>`
99    ///
100    /// # Examples
101    ///
102    /// ```
103    /// use names::{Generator, Name};
104    ///
105    /// let adjectives = &["sassy"];
106    /// let nouns = &["clocks"];
107    /// let naming = Name::Plain;
108    ///
109    /// let mut generator = Generator::new(adjectives, nouns, naming);
110    ///
111    /// assert_eq!("sassy-clocks", generator.next().unwrap());
112    /// ```
113    pub fn new(adjectives: &'a [&'a str], nouns: &'a [&'a str], naming: Name) -> Self {
114        Generator {
115            adjectives,
116            nouns,
117            naming,
118            rng: ThreadRng::default(),
119        }
120    }
121
122    /// Construct and returns a default `Generator<'a>` containing a large
123    /// collection of adjectives and nouns
124    ///
125    /// ```
126    /// use names::{Generator, Name};
127    ///
128    /// let mut generator = Generator::with_naming(Name::Plain);
129    ///
130    /// println!("My new name is: {}", generator.next().unwrap());
131    /// ```
132    pub fn with_naming(naming: Name) -> Self {
133        Generator::new(ADJECTIVES, NOUNS, naming)
134    }
135}
136
137impl<'a> Default for Generator<'a> {
138    fn default() -> Self {
139        Generator::new(ADJECTIVES, NOUNS, Name::default())
140    }
141}
142
143impl<'a> Iterator for Generator<'a> {
144    type Item = String;
145
146    fn next(&mut self) -> Option<String> {
147        let adj = self.adjectives.choose(&mut self.rng).unwrap();
148        let noun = self.nouns.choose(&mut self.rng).unwrap();
149
150        Some(match self.naming {
151            Name::Plain => format!("{}-{}", adj, noun),
152            Name::Numbered => format!("{}-{}-{:04}", adj, noun, rand_num(&mut self.rng)),
153        })
154    }
155}
156
157fn rand_num(rng: &mut ThreadRng) -> u16 {
158    rng.gen_range(1..10000)
159}
names/lib.rs

names/
lib.rs
