Added initial txt2tags documentation.

2005-01-20 12:28:42 +00:00
parent 31e9d838e8
commit 76f7be31e4
5 changed files with 333 additions and 4 deletions
--- a/147
+++ b/147
@@ -0,0 +1,147 @@
+== cmph - C Minimal Perfect Hashing Library ==
+
+Description
+
+C Minimal Perfect Hashing Library is a portable LGPLed library to create and
+work with minimal perfect hashes. The cmph library encapsulates the newest
+and more efficient algorithms in the literature in a ease-to-use, 
+production-quality, fast API. The library is designed to work big entries that 
+won't fit in the main memory. It has been used successfully to create hashes
+bigger than 100 million entries. Although there is a lack of similar libraries
+in the free software world, we can point out some of the "distinguishing" 
+features of cmph:
+
+- Fast
+- Space-efficient with main memory usage carefully documented
+- The best modern algorithms are available (or at least scheduled for implementation :-))
+- Object oriented implementation
+- Works with in-disk key sets through use of adapter pattern
+- Serialization of hash functions
+- Easily extensible
+- Well encapsulated API aiming binary compatibility through releases
+- Free Software
+
+News for version 0.3
+
+- New heuristics in bmz algorithm, providing hash creation with only
+  (0.93 * 16 + 4)*n bytes and hash query with (0.93*4)n bytes
+
+Examples
+
+Using cmph is quite ease. Take a look.
+
+
+   // Create minimal perfect hash from in-memory vector
+   #include <cmph.h>
+   ...
+   
+   const char **vector;
+   unsigned int nkeys;
+   //Fill vector
+   //...
+   
+   //Create minimal perfect hash
+   cmph_config_t *config = cmph_config_new(cmph_io_vector_adapter(vector, nkeys));
+   cmph_t *hash = cmph_new(config);
+   cmph_config_destroy(config);
+   
+   //Find key
+   const char *key = "sample key";
+   unsigned int id = cmph_search(hash, key);
+   
+   //Destroy hash
+   cmph_destroy(hash);
+
+-------------------------------
+
+
+   // Create minimal perfect hash from in-disk keys using BMZ algorithm
+   #include <cmph.h>
+   ...
+   
+   //Open file with newline separated list of keys
+   FILE *fd = fopen("keysfile_newline_separated", "r");
+   //check for errors
+   //...
+   
+   cmph_config_t *config = cmph_config_new(cmph_io_nlfile_adapter(fd));
+   cmph_config_set_algo(config, CMPH_BMZ);
+   cmph_t *hash = cmph_new(config);
+   cmph_config_destroy(config);
+   fclose(fd);
+   
+   //Find key
+   const char *key = "sample key";
+   unsigned int id = cmph_search(hash, key);
+   
+   //Destroy hash
+   cmph_destroy(hash);
+
+--------------------------------------
+
+The cmph application
+
+cmph is the name of both the library and the utility
+application that comes with this package. You can use the cmph
+application to create minimal perfect hashes from command line. The cmph utility
+comes with a number of flags, but it is very simple to create and query 
+minimal perfect hashes:
+
+
+   $ # Create mph for keys in file keys_file
+   $ ./cmph keys_file
+   $ # Query id of keys in the file keys_query
+   $ ./cmph -m keys_file.mph keys_query
+
+
+The additional options let you set most of the parameters you have
+available through the C API. Below you can see the full help message for the 
+utility.
+
+
+   usage: cmph [-v] [-h] [-V] [-k] [-g [-s seed] ] [-m file.mph] [-a algorithm] keysfile
+   Minimum perfect hashing tool
+   
+     -h	 print this help message
+     -c	 c value that determines the number of vertices in the graph
+     -a	 algorithm - valid values are
+       	  * czech
+       	  * bmz
+     -f	 hash function (may be used multiple times) - valid values are
+       	  * jenkins
+       	  * djb2
+       	  * sdbm
+       	  * fnv
+       	  * glib
+       	  * pjw
+     -V	 print version number and exit
+     -v	 increase verbosity (may be used multiple times)
+     -k	 number of keys
+     -g	 generation mode
+     -s	 random seed
+     -m	 minimum perfect hash function file 
+     keysfile	 line separated file with keys
+
+
+Downloads
+
+Use the project page at sourceforge: http://sf.net/projects/cmph
+
+License Stuff
+
+Code is under the LGPL. 
+
+----------------------------------------
+
+Enjoy!
+
+Davi de Castro Reis
+
+Fabiano Cupertino Botelho
+
+Last Updated: Thu Jan 20 11:01:01 2005
+
+
+
+
+