namegenerator

README

namegenerator

NameGenerator is a Golang package that provides a simple yet powerful tool for generating human-readable and pronounceable random names. The names are generated by namegenerator.py from https://www.cs.cmu.edu/ dataset.

Installation

go get github.com/0x6flab/namegenerator

Usage

package main

import (
    "fmt"

    "github.com/0x6flab/namegenerator"
)

func main() {
    generator := namegenerator.NewGenerator()

    // Generate a random name
    name := generator.Generate()

    // Print the name
    fmt.Println(name)
}

Examples

See examples directory for more examples.

Benchmarks

Benchmark tests can be found in test file and collision tests can be found in test file.

goos: linux
goarch: amd64
pkg: github.com/0x6flab/namegenerator
cpu: AMD Ryzen 7 7735HS with Radeon Graphics
BenchmarkNameGenerator_Generate-16                967677              1158 ns/op
BenchmarkNameGenerator_Generate10Names-16          97788             11577 ns/op
BenchmarkNameGenerator_Generate1KNames-16            973           1156777 ns/op
BenchmarkNameGenerator_Generate10KNames-16            88          11594857 ns/op

For collision tests:

Number of Names	Options	Collisions	Collision range
1K	with random string (2) or (5)	0	0
10K	with random string (2) or (5)	0	0
100K	with random string (2) or (5)	0	0
1M	with random string (2) or (5)	0	0
1K	without	0	0
10K	without	0	0
100K	without	1	0-5
1M	without	147	135-163
1K	male names	0	0
10K	male names	1	0-4
100K	male names	127	105-152
1M	male names	12516	12394-12630
1K	female names	0	0
10K	female names	0	0-3
100K	female names	74	57-98
1M	female names	7404	7289-7542

License

This project is licensed under the Apache-2.0 LICENSE - see the LICENSE file for details.

Documentation

Overview

Package namegenerator provides a simple way to generate random names.

Index

• Variables
• type Gender
• type NameGenerator
  • func NewGenerator() NameGenerator
• type Options
  • func WithGender(gender Gender) Options
  • func WithPrefix(prefix string) Options
  • func WithRandomString(length int) Options
  • func WithSuffix(suffix string) Options

Variables

var (
	// FamilyNames is a list of family names
	FamilyNames = []string{}/* 13479 elements not displayed */

	// FemaleNames is a list of female names
	FemaleNames = []string{}/* 4999 elements not displayed */

	// MaleNames is a list of male names
	MaleNames = []string{}/* 2943 elements not displayed */

	// GeneralNames is a list of general names
	GeneralNames = []string{}/* 58254 elements not displayed */

)

Types

type Gender

type Gender uint8

const (
	Male Gender = iota
	Female
	NonBinary
)

type NameGenerator

type NameGenerator interface {
	// Generate generates a name based on the gender.
	//
	// Example:
	//  generator := namegenerator.NewGenerator()
	//  name := generator.Generate()
	//  fmt.Println(name)
	// Output:
	//  `John-Smith`
	// Example with options:
	//  generator := namegenerator.NewGenerator()
	//  name := generator.Generate(namegenerator.WithGender(namegenerator.Male))
	//  fmt.Println(name)
	// Output:
	//  `John-Smith`
	Generate(options ...Options) string

	// GenerateMultiple generates a list of names.
	//
	// Example:
	//  generator := namegenerator.NewGenerator()
	//  names := generator.GenerateMultiple(10)
	//  fmt.Println(names)
	// Example with options:
	//  generator := namegenerator.NewGenerator()
	//  names := generator.GenerateMultiple(10, namegenerator.WithGender(namegenerator.Male))
	//  fmt.Println(names)
	GenerateMultiple(count int, options ...Options) []string

	// WithGender generates a name based on the gender.
	//
	// Example:
	//  generator := namegenerator.NewGenerator().WithGender(namegenerator.Male)
	//  name := generator.Generate()
	//  fmt.Println(name)
	// Output:
	//  `John-Smith`
	WithGender(gender Gender) NameGenerator

	// WithPrefix generates a name with a prefix.
	//
	// Example:
	//  generator := namegenerator.NewGenerator().WithPrefix("Mr. ")
	//  name := generator.Generate()
	//  fmt.Println(name)
	// Output:
	//  `Mr. John-Smith`
	WithPrefix(prefix string) NameGenerator

	// WithSuffix generates a name with a suffix.
	//
	// Example:
	//  generator := namegenerator.NewGenerator().WithSuffix("@gmail.com")
	//  name := generator.Generate()
	//  fmt.Println(name)
	// Output:
	//  `John-Smith@gmail.com`
	WithSuffix(suffix string) NameGenerator

	// WithRandomString generates a name with a random string.
	//
	// Example:
	//  generator := namegenerator.NewGenerator().WithRandomString(5)
	//  name := generator.Generate()
	//  fmt.Println(name)
	// Output:
	//  `John-Smith-abcde`
	WithRandomString(lenOfRandomString int) NameGenerator
}

NameGenerator is an interface for generating names.

func NewGenerator

func NewGenerator() NameGenerator

NewGenerator returns a new NameGenerator.

Example to generate general names:

generator := namegenerator.NewGenerator()

Example to generate male names:

generator := namegenerator.NewGenerator().WithGender(namegenerator.Male)

Example to generate female names:

generator := namegenerator.NewGenerator().WithGender(namegenerator.Female)

Example to generate non-binary names:

generator := namegenerator.NewGenerator().WithGender(namegenerator.NonBinary)

Example to generate names with a prefix:

generator := namegenerator.NewGenerator().WithPrefix("Mr. ")

Example to generate names with a suffix:

generator := namegenerator.NewGenerator().WithSuffix("@gmail.com")

Example to generate names with a random string:

generator := namegenerator.NewGenerator().WithRandomString(5)

type Options

type Options func(*nameGenerator)

func WithGender

func WithGender(gender Gender) Options

WithGender generates a name based on the gender.

func WithPrefix

func WithPrefix(prefix string) Options

WithPrefix generates a name with a prefix.

func WithRandomString

func WithRandomString(length int) Options

WithRandomString generates a name with a random string.

func WithSuffix

func WithSuffix(suffix string) Options

WithSuffix generates a name with a suffix.