summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorRemi Collet <fedora@famillecollet.com>2013-10-21 06:30:20 +0200
committerRemi Collet <fedora@famillecollet.com>2013-10-21 06:30:20 +0200
commit37c0b3cbdbb66b29ae8bc25c19561a400dddd502 (patch)
tree87f41165275407e3a9128211e8e1b179c51f3827 /README
php-pecl-judy: rename
Diffstat (limited to 'README')
-rw-r--r--README210
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)