Skip to content

Commit

Permalink
test commit
Browse files Browse the repository at this point in the history
  • Loading branch information
mondrake committed Nov 24, 2011
1 parent a3bacc7 commit 0bf37c8
Show file tree
Hide file tree
Showing 3 changed files with 192 additions and 46 deletions.
91 changes: 59 additions & 32 deletions README.markdown
View file
@@ -1,31 +1,61 @@
# PHP AVL binary search tree - Coming soon!#
# PHP AVL binary search tree - COMING SOON! #

A set of PHP classes implementing binary search trees that comply to AVL
rules. The API exposes methods for tree operations (insert, replace,
delete, find), and for in-order traversal (find, first, last, prev,
next, curr). Nodes within the trees are not accessible publicly. Tree
and traversal operations implement relaxed balance factors, and
parent-pointer node structures. Hooks for node comparison, error
handling and diagnostic logging capabilities are provided via a callback
interface.

rules.
The API exposes methods for tree operations (insert, replace, delete,
find), and for inorder traversal (find, first, last, prev, next, curr).
Tree and traversal operations implement relaxed balance factors, and
parent pointer node structures.
Hooks for node comparison, error handling and diagnostic logging
capabilities are provided via a callback interface.

<strong>What are AVL trees?</strong>

In an nutshell, AVL trees are a form of binary search trees that can be
used to keep a set of data efficiently sorted while adding or removing
elements.

For more details, Wikipedia has articles for [binary search trees](http://en.wikipedia.org/wiki/Binary_search_tree)
and [AVL trees](http://en.wikipedia.org/wiki/AVL_tree).

<strong>What about 'relaxed balance factors'?</strong>
Without getting into all the theory, AVL trees in their 'canonical
form', i.e. where the heights of the two child subtrees of any node
differ by at most one, are very efficient for lookup, but require in
average a rotation operation every two insert or delete operations. By
default, Rbppavl handles trees in canonical AVL form, but optionally
allows to 'relax' the balancing factor, allowing the height difference
to be any integer value. Empirical evidence shows that, in average, each
increase of the allowed imbalance almost _halves_ the number of
rotations expected. On the other side, the overall height of the tree
will increase and lookup operations become less efficient.

<strong>What about parent pointer node structures?</strong>
In Rbppavl, each node in the tree stores a link to its 'parent' node.
This allows to simplify traversal by eliminating the need for a stack,
i.e. given a node, getting to previous or next inorder node can be
accomplished just with the information stored in the node itself.

<strong>Prerequisites</strong>
- PHP 5.2.13 (this is the lowest PHP release _tested_ with)

<strong>License</strong>
[GNU GPLv3](http://www.gnu.org/licenses/gpl.html)

<strong>Documentation</strong>
Rbppavl documentation is available in the _Rbppavl_doc_ directory.
Documentation is generated by [docBlox](http://www.docblox-project.org/).

<strong>Acknowledgments</strong>
Large parts of Rbppavl implementation are taken from Ben Pfaff's [GNU libavl](http://adtinfo.org/).

....
# Usage examples #

<strong>Basic usage</strong>
<strong>Basic usage example</strong>

Define your data object and the callback interface to be used by Rbppavl
1. Include Rbppavl

require_once 'Rbppavl/Rbppavl.php';

2. Define your data object and the callback interface to be used by Rbppavl

class TestObject {
public $q;
Expand All @@ -41,40 +71,37 @@ Define your data object and the callback interface to be used by Rbppavl
return $a->q;
}

public function diagnosticMessage($severity, $id, $text, $params, $className = null) {
public function diagnosticMessage($severity, $id, $text, $params, $qText,$className = null) {
return null;
}

public function errorHandler($id, $text, $params, $className = null) {
public function errorHandler($id, $text, $params, $qText, $className = null) {
return null;
}
}

Create a tree
3. Create a tree

$tree = new RbppavlTree("callbackClass");
$tree = new RbppavlTree('TestCallback');

Insert data objects in the tree
4. Insert some data objects

$data = new TestObject;
$data->q = 12;
$t = $tree->insert($data);
$data = new TestObject;
$data->q = 7;
$t = $tree->insert($data);
$data = new TestObject;
$data->q = 36;
$t = $tree->insert($data);
$seq = array(12, 7, 36, 4, 1, 28, 3);
foreach ($seq as $value) {
$data = new TestObject;
$data->q = $value;
$t = $tree->insert($data);
}

Perform in-order traversal
5. Perform inorder traversal, printing each value

$trav = new RbppavlTraverser($tree);
$r = $trav->first();
while ($r != NULL) {
print($r->q . '<br/>);
print($r->q . '<br/>');
$r = $trav->next();
}

<strong>More examples</strong>

See more examples in simple_test.php and full_test.php
More examples in simple_test.php and full_test.php

113 changes: 113 additions & 0 deletions Rbppavl/Rbppavl.php
View file
@@ -0,0 +1,113 @@
<?php
/**
* PHP AVL binary tree
*
* A set of PHP classes implementing management of binary trees according to
* AVL rules.
* The API exposes tree management operations (insert, replace, delete, find),
* traversal (find, first, last, prev, next, curr). Nodes within the trees are
* not exposed publicly.
* Tree and traversal operations implement relaxed balance factors, and
* parent-pointer node structures.
* Hooks for node comparison, error handling and logging capabilities are provided
* via a callback interface.
*
* PHP version 5
*
* @category Structures
* @package Rbppavl
* @author mondrake <mondrake@mondrake.org>
* @license http://www.gnu.org/licenses/gpl.html GNU GPLv3
* @link http://github.com/mondrake/Rbppavl
*/

/**
* Rbppavl version number
*/
define('RBPPAVL_VERSION_NUMBER', '0.1.0');

/**
* Rbppavl version state
*/
define('RBPPAVL_VERSION_STATE', 'beta');

/**
* @defgroup severity_levels Status and diagnostic severity levels
* @{
* Status and diagnostic levels as defined in RFC 3164.
*
* @see http://www.faqs.org/rfcs/rfc3164.html
*/

/**
* 'Debug' status level or diagnostic
*/
define('RBPPAVL_DEBUG', 7);

/**
* 'Information' status level or diagnostic
*/
define('RBPPAVL_INFO', 6);

/**
* 'Notice' status level or diagnostic
*/
define('RBPPAVL_NOTICE', 5);

/**
* 'Warning' status level or diagnostic - partial failure not preventing further processing
*/
define('RBPPAVL_WARNING', 4);

/**
* 'Error' status level or diagnostic - failure preventing further processing
*/
define('RBPPAVL_ERROR', 3);

/**
* @} End of "defgroup severity_levels".
*/

/**
* Identifier for textual diagnostic strings
*/
define('RBPPAVL_TEXT', -1);

/**
* AVL Tree validation - success
*/
define('RBPPAVL_VALIDATION_OK', 0);

/**
* AVL Tree validation - failure - node's stored tree height not
* consistent with computed height
*/
define('RBPPAVL_VALIDATION_HEIGHT_FAILURE', 1);

/**
* AVL Tree validation - failure - actual node's balance factor
* exceeds limit
*/
define('RBPPAVL_VALIDATION_BALANCE_FAILURE', 2);

require_once 'RbppavlNode.php';
require_once 'RbppavlCommon.php';
require_once 'RbppavlTree.php';
require_once 'RbppavlTraverser.php';
require_once 'RbppavlCbInterface.php';

/**
* Baseline Rbppavl class.
*
* Rbppavl root abstract class. This is empty to set a common parent class for the entire package.
*
* @category Structures
* @package Rbppavl
* @author mondrake <mondrake@mondrake.org>
* @license http://www.gnu.org/licenses/gpl.html GNU GPLv3
* @link http://github.com/mondrake/Rbppavl
* @access private
*/
abstract class Rbppavl
{
}
34 changes: 20 additions & 14 deletions simple_test.php
View file
@@ -1,13 +1,24 @@
<head>
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<link rel="stylesheet" href="style.css" type="text/css">
<?php
/**
* PHP AVL binary tree
*
* A simple test script for Rbppavl package.
*
* PHP version 5
*
* @category Structures
* @package Rbppavl
* @author mondrake <mondrake@mondrake.org>
* @license http://www.gnu.org/licenses/gpl.html GNU GPLv3
* @link http://github.com/mondrake/Rbppavl
*/

require_once "Rbppavl/Rbppavl.php";

// change value below to increase/decrease the number of nodes to be generated
$howManyNodes = 10;


// ------------------------------------------------------------------
// Test classes
// ------------------------------------------------------------------
Expand All @@ -26,25 +37,20 @@ public function dump($a) {
return $a->q;
}

public function diagnosticMessage($severity, $id, $text, $params, $className = null) {
if ($params) {
foreach ($params as $a => $b) {
$text = str_replace($a, $b, $text);
}
}
print ($text . '<br/>');
public function diagnosticMessage($severity, $id, $text, $params, $qText, $className = null) {
print($qText . '<br/>');
}

public function errorHandler($id, $text, $params, $className = null) {
return null;
public function errorHandler($id, $text, $params, $qText, $className = null) {
throw new exception($qText, $id);
}
}

// ------------------------------------------------------------------
// Main routine
// ------------------------------------------------------------------

print ('<h2>Simple Rbppavl tree test - a standard AVL tree</h2>');
print ('<h2>Simple Rbppavl tree test: a standard AVL tree</h2>');
print ("This test generates $howManyNodes random integers, inserts them in a standard AVL tree, validates the tree,<br/>");
print ('performs an inorder traversal, then deletes the tree and its content.<br/>');
print ('For more complex scenarios, see full test <a href="full_test.php">here</a>.<br/>');
Expand Down

0 comments on commit 0bf37c8

Please sign in to comment.