M.A.N.G. Code
Brought to you by:
marcmueller1991
File | Date | Author | Commit |
---|---|---|---|
mang | 2009-12-05 | Marc Müller | [d7e26f] Updated documentation. |
Benchmark.txt | 2009-11-30 | Marc Müller | [771ef6] First git commit. |
License.txt | 2009-11-30 | Marc Müller | [771ef6] First git commit. |
README | 2009-11-30 | Marc Müller | [771ef6] First git commit. |
mang-1.0-doc.zip | 2009-12-05 | Marc Müller | [3380b7] Updated documentation. |
====================================================== * 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.