dasmig / name-generator

A very simple c++ name generator library. Generates real world first names and surnames from culture/gender specific lists.

Name Generator for C++

Features

The library currently supports the following:

• Name Generation. The library generates a name randomly from a list of given names, organized through gender and country of origin.

• Surname Generation. The library generates a surname randomly from a list of surnames, organized through the country of origin.

• Full Name. Easily append one or more names and surnames to generate a full name with an intuitive API.

• Deterministic Generation. The user is capable of seeding the random generator.

• ISO 2-Letter Code. API allowing requests through countries 2-Letter code along the library enum.

• Countries Supported. Currently, the following countries are supported by the library and contain a relevant database (unchecked countries are currently lacking or contain an incomplete database):

  • Australia
  • Argentina
  • Brazil
  • Bulgaria
  • Canada
  • China
  • Denmark
  • Finland
  • France
  • Germany
  • Kazakhstan
  • Mexico
  • Norway
  • Poland
  • Portugal
  • Russia
  • Spain
  • Sweden
  • Turkey
  • Ukraine
  • United Kingdom
  • United States of America

Integration

namegen.hpp contains all the library code released here. You need to add

#include <dasmig/namegen.hpp>

// For convenience.
using ng = dasmig::ng;

to the files you want to generate names/surnames and set the necessary switches to enable C++17 (e.g., -std=c++17 for GCC and Clang).

Additionally, you must supply the name generator with the resources folder also available in the release.

As of v0.2, the library makes use of a random generation library by effolkronium. For the convenience of the user, the header-only file containing the implementation was added to this repository.

Usage

It's important to note that due to the necessity of supporting multiple cultures characters and the way std::string works on windows, this library uses std::wstring to return the generated names.

When requesting a name for the first time the library will attempt to load the resource files containing each country's databases (the default path is ./resources). It's important to manually load the resources folder if it's present in a different location. The library will recursively iterate through all entries in the loading directory, so only a single call to the root folder containing the name databases is necessary.

using ng = dasmig::ng;

// Manually load the resources folder if necessary.
ng::instance().load("path//containing//names");

// Generates a name of any culture and any gender.
std::wstring name = ng::instance().get_name();

// Generates a female name of any culture.
std::wstring female_name = ng::instance().get_name(ng::gender::f);

// Generates a male name of bulgarian culture.
std::wstring bulgarian_name = ng::instance().get_name(ng::gender::m, ng::culture::bulgarian);

// Generates a male name of any gender and any culture and append two surnames of same culture.
std::wstring full_name = ng::instance().get_name().append_surname().append_surname();

// Output to stream a french female name with a surname.
std::wcout << ng::instance().get_name(ng::gender::f, ng::culture::french).append_surname();

Planned Features

• Specialized Support for Surnames. Appropriate handling of gendered surnames in some cultures.

Disclaimer

Ukrainian and Russian surnames are all in their male or neutral versions.

This README was heavily inspired by 'nlhomann/json'.