php-pecl-judy: rename

1 files changed, 210 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..99b0f82
--- /dev/null
+++ b/README
@@ -0,0 +1,210 @@
+        PHP Judy - extension creating and accessing dynamic arrays
+     ================================================================
+
+Content
+---------
+ 1. Introduction
+ 2. Directory Contents
+ 3. How to install
+ 4. Usage (Examples)
+ 5. Reporting Bugs
+ 6. Todo
+
+
+1. INTRODUCTION
+-----------------
+
+php-judy is an extension by Nicolas Brousse for the Judy C library.
+  -> http://pecl.php.net/package/Judy
+  -> http://github.com/orieg/php-judy
+
+(see Section 4 of this document for PHP examples)
+
+A Judy array is a complex but very fast associative array data structure for
+storing and looking up values using integer or string keys. Unlike normal
+arrays, Judy arrays may be sparse; that is, they may have large ranges of
+unassigned indices.
+
+  -> http://en.wikipedia.org/wiki/Judy_array
+
+The PHP extension is base on the Judy C library that implements a dynamic array.
+A Judy array consumes memory only when populated yet can grow to take advantage
+of all available memory.  Judy's key benefits are:  scalability, performance,
+memory efficiency, and ease of use. Judy arrays are designed to grow without
+tuning into the peta-element range, scaling near O(log-base-256) -- 1 more RAM
+access at 256 X population.
+
+  -> http://judy.sourceforge.net
+
+2. PHP JUDY TOP DIRECTORY CONTENTS:
+------------------------------------
+
+README       This file.
+LICENSE      The PHP License used by this project.
+EXPERIMENTAL Note about the status of this package.
+
+lib/         Header and source libraries used by the package.
+libjudy/     Bundled libJudy.      
+tests/       Unit tests.
+*.c, *.h     Header and source files used to build the package.
+*.php        PHP test/examples scripts.
+
+
+3. HOW TO INSTALL
+------------------
+
+ A. Linux
+
+   From the PHP Judy sources :
+
+     phpize
+     ./configure --with-judy[=DIR]
+     make
+     make test
+     make install
+
+   If you are using Ubuntu or Debian, you can install libJudy with apt :
+
+     apt-get install libjudydebian1 libjudy-dev
+     phpize
+     ./configure --with-judy=/usr
+     make
+     make test
+     make install
+  
+ B. Windows
+
+   On Windows, you will need to build LibJudy yourself.
+
+   Download the sources at 
+
+     http://sourceforge.net/projects/judy/
+	  
+   Extract the sources, and open the Visual Studio command prompt and navigate to 
+   the source directory. Then execute:
+
+     build
+	  
+   This creates "Judy.lib", copy this into the php-sdk library folder and name it 
+ 
+     libJudy.lib
+	 
+   Then copy the include file "judy.h" into the php-sdk includes folder. Now its 
+   time to build pecl/judy, extract the pecl/judy into your build folder where 
+   the build scripts will be able to pick it up, e.g.:
+	
+     C:\php\pecl\judy\
+	 
+   If your source of PHP is located in:
+	
+     C:\php\src\
+	 
+   The rest of the steps is pretty straight forward, like any other external 
+   extension:
+	
+     buildconf
+     configure --with-judy=shared
+     nmake
+
+ C. Mac OS X
+
+   You will need to install the libJudy first. Download the sources at 
+
+     http://sourceforge.net/projects/judy/
+	  
+   Extract the sources, then cd into the source directory and execute :
+
+     ./configure
+     make
+     make install
+
+   Use pecl to install the PHP Judy extension :
+
+     sudo pecl -d preferred_state=beta install Judy
+
+
+4. USAGE (EXAMPLES)
+------------------
+
+Judy's array can be used like usual PHP arrays. The difference will be in the
+type of key/values that you can use. Judy arrays are optimised for memory usage
+but it force to some limitation in the PHP API.
+
+There is currently 5 type of PHP Judy Arrays :
+ - BITSET (using Judy1)
+ - INT_TO_INT (using JudyL)
+ - INT_TO_MIXED (using JudyL)
+ - STRING_TO_INT (using JudySL)
+ - STRING_TO_MIXED (using JudySL)
+
+You can use foreach() and the PHP array notation on all PHP Judy arrays.
+
+  A. BITSET
+
+  Bitset implementation is quite basic for now. It allow you to set a bunch of index
+  setting the value to false will be the same than using unset().
+
+    $bitset = new Judy(Judy::BITSET);
+    $bitset[124] = true;
+    ...
+ 
+    print $bitset[124]; // will print 1
+ 
+    $bitset[124] = false; // is the same as unset($bitset[124])
+
+  B. INT_TO_INT
+
+  This type let you create an array with key and value of integer, and integer only.
+
+    $int2int = new Judy(Judy::INT_TO_INT);
+    $int2int[125] = 17;
+    ...
+
+    print $int2int[125]; // will print 17
+
+  C. INT_TO_MIXED
+
+  This type let you create an array with key as integer and value of any type, including
+  other judy array or any object.
+
+    $int2mixed = new Judy(Judy::INT_TO_MIXED);
+    $int2mixed[1] = "one";
+    $int2mixed[2] = array('a', 'b', 'c');
+    $int2mixed[3] = new Judy(Judy::BITSET);
+
+  D. STRING_TO_INT
+
+  This type let you create an array with key as string (currently limited to 65536 char.)
+  and an integer as the value.
+
+    $string2int = new Judy(Judy::STRING_TO_INT);
+    $string2int["one"] = 1;
+    $string2int["two"] = 2;
+
+    print $string2int["one"]; // will print 1
+
+  E. STRING_TO_MIXED
+
+  This type let you create an array with key as string and values of any type, including
+  other judy array or any objects.
+
+    $string2mixed = new Judy(Judy::STRING_TO_MIXED);
+    $string2mixed["string"] = "hello world!";
+    $string2mixed["array"] = array('a', 'b', 'c');
+    $string2mixed["integer"] = 632;
+    $string2mixed["bitset"] = new Judy(Judy::BITSET);
+
+
+5. REPORTING BUGS
+------------------
+
+If you encounter a bug, please submit it via the bug tracker on Git Hub:
+
+  https://github.com/orieg/php-judy/issues
+
+
+6. TODO
+--------
+
+ * Implements comparator and cast handler
+ * Add bitset comparator (cf. Judy1Op sample)