< index < 16. Name generator < 16.1 Creating a generator | ===================================== 16.2 Generating a name ===================================== | > 16.3 Destroying a generator

### TCODNamegen::generate

The following will output a random name generated using one of the generation rules specified in the syllable set:

    C++ : static char * TCODNamegen::generate(char * name, bool allocate = false)
    C   : char * TCOD_namegen_generate(char * name, bool allocate);
    Py  : namegen_generate(name, allocate=0)

Parameter | Description
--- | ---
name | The structure name you wish to refer to, for instance, "celtic female". For more about how structure names work, please refer to chapters 16.5 and 7.1.
allocate | Whether memory should be allocated for the output or not.

Should you choose to allocate memory for the output, you need to remember to deallocate it once you don't need the name anymore using the free() function. This applies to C++ as well (delete won't work - you have to use free()).
On the other hand, should you choose not to allocate memory, be aware that subsequent calls will overwrite the previously returned pointer, so make sure to copy the output using strcpy(), strdup() or other means of your choosing.
The name you specify needs to be in one of the files the generator has previously parsed (see TCODNamegen::parse). If such a name doesn't exist, a warning will be displayed and NULL will be returned.
Example :

    C++ : TCODNamegen::parse("data/names.txt",TCODRandom::getInstance());
          char * myName = TCODNamegen::generate("fantasy female");
    C   : TCOD_namegen_parse("data/names.txt",TCOD_random_get_instance());
          char * my_name = TCOD_namegen_generate("Celtic male",false);
    Py  : libtcod.namegen_parse('data/names.txt')
          name = libtcod.namegen_generate('fantasy female')

### TCODNamegen::generateCustom

It is also possible to generate a name using custom generation rules. This overrides the random choice of a generation rule from the syllable set. Please refer to chapter 16.5 to learn about the name generation rules syntax.

    C++ : static char * TCODNamegen::generateCustom(char * name, char * rule, bool allocate = false)
    C   : char * TCOD_namegen_generate_custom(char * name, char * rule, bool allocate);
    Py  : namegen_generate_custom(name, rule, allocate=0)

Parameter | Description
--- | ---
name | The structure name you wish to refer to, for instance, "celtic female". For more about how structure names work, please refer to chapters 16.5 and 7.1.
rule | The name generation rule. See chapter 16.5 for more details.
allocate | Whether memory should be allocated for the output or not.

Example :

    C++ : TCODNamegen::create("data/names.txt",TCODRandom::getInstance());
          char * myName = TCODNamegen::generateCustom("Nordic male","$s$e");
    C   : TCOD_namegen_new("data/names.txt",TCOD_random_get_instance());
          char * my_name = TCOD_namegen_generate_custom("Mesopotamian female","$s$e",false);
    Py  : libtcod.namegen_parse('data/names.txt')
          name = libtcod.namegen_generate('fantasy female','$s$e')