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)