Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 435e2e3b5d
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 211 lines (139 sloc) 5.606 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 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)
Something went wrong with that request. Please try again.