README.md

    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

7. 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 based 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

Install with Homebrew http://brew.sh/

Install Homebrew Package Manager

 ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Install homebrew-php

brew tap homebrew/dupes
brew tap homebrew/versions
brew tap homebrew/homebrew-php

Install PHP Judy

brew install php53-judy

PECL Install

Use pecl to install the PHP Judy extension :

sudo pecl -d preferred_state=beta install Judy

Manual install

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

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)