diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 210 |
1 files changed, 210 insertions, 0 deletions
@@ -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) |