======================================================
* M.A.N.G. v1.0 *
======================================================
Table of contents:
1. Introduction
2. Features
3. Build instructions
4. Quick-Tutorial
5. Name file specifications
6. Performance
7. Contact
1. Introduction
M.A.N.G. is a java based library for random generation of first and last names. It is designed to
be used in an application that occasionally needs to create a new name, though that does not mean
the M.A.N.G. library does not perform well. It just means the name generation can be stored as
an object inside another application and be accessed randomly.
2. Features
The M.A.N.G. library includes various features to ease the generation of random names. These include:
- Easy name parsing based on external files
- Easy and fast generation of names
- Names caching through serializtation
- Name database including meta information like the name's origin and meaning
- Name retrieval based on certain criteria
- Generation of full names, including middle and last names
- Easily extendable conditioning method, which allows the developer to implement
his own methods of choosing names from a collection
3. Build instructions
To build M.A.N.G. simply type:
javac -d /destination/path/for/classes -cp /destination/path/for/classes -source 1.5 -sourcepath /path/to/sources/*.java
and to create a jar:
jar cfv /path/to/your/jarfile /path/to/mang/classes/*
4. Quick-Tutorial
Creating names is very easy with M.A.N.G. First, make sure you have either a cache file created
from a previous NameCollection instance via serialization or a raw text file fitting the format
specified in the next chapter.
To generate names you just create an instance of the NameGenerator class, with the paths to your
first- and lastnames files and a boolean indicating whether or not the given files are raw text
or cache files. Then you can start generating names by calling the generateRandomName() method.
Advanced generation with restricting criteria is done through the Criterion class and the Decider
interface. Instances of the Criterion class (which utilizes the Decider interface) are passed in
an ArrayList to the generateRandomName() method, which then retrieves all the names fitting every
condition in the ArrayList.
5. Name file specifications
A name consists of 4 lines. Each of these lines should contain nothing
but the information described.
The first line contains the name string, this line's format is:
[Name:<name>]
The second line contains the gender in the format:
Gender=<gender>
The gender is supposed to be a number and can be female (1), unisex (0)
or male (-1).
The third line contains the uses of the name. The uses are also the
origins of the name. The usage line should be formatted as:
Usage=<usage1>;<usage2>;...;<usagen>;
with each usage separated by a semi-colon.
The fourth and last line contains the meaning. The meaning's format is
simply:
Meaning=<text>
So, an example name would look like:
[Name:MARC]
Gender=-1
Usages=French;Catalan;Welsh;
Meaning=French, Catalan and Welsh form of MARK.
The lines of the next name follow the lines of the previous name DIRECTLY.
6. Performance
M.A.N.G. performs quite well. Random name retrieval from a NameCollection of 160,000 names is
almost always faster than 1ms. The current method for retrieval of names based on certain criteria
is a little slow. It can take up to 10ms to filter about 160,000 names. The complexity of the
current method is O(n). This, however, is only true for single names. If you use the same criteria
more than once, the NameCollection class makes use of its cache, which retrieves a name in usually
less than 1 ms. I might add that I actually mean using the _same_ criteria, the very same instance.
Not just a criterion which does the same thing as a previously used criterion.
7. Contact
I can be contacted via marcmueller1991@gmail.com. This is also my Windows Live address.
