"""
Binary Search Tree: A sorted collection of values that supports
efficient insertion, deletion, and minimum/maximum value finding.
"""
# Copyright (C) 2008 by Edward Loper
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
# IMPLEMENTATION NOTES:
#
# Internally, we represent tree nodes using Python lists. These lists
# may either be empty (for empty nodes) or may have length four (for
# non-empty nodes). The non-empty nodes contain:
#
# [left_child, right_child, value, sort_key]
#
# Using lists rather than a node class more than doubles the overall
# performance in the benchmarks that I have run.
#
# The sort key is always accessed as node[-1]. This allows us to
# optimize the case where the sort key is identical to the value, by
# encoding such nodes as simply:
#
# [left_child, right_child, value]
#
# The following constants are used to access the pieces of each search
# node. If the constant-binding optimization recipe (which can be
# downloaded from <http://code.activestate.com/recipes/277940/>) is
# available, then it is used to replace these constants at
# import-time, increasing the binary search tree efficiency by 3-5%.
_LEFT = 0
_RIGHT = 1
_VALUE = 2
_SORT_KEY = -1
class BinarySearchTree(object):
"""
A sorted collection of values that supports efficient insertion,
deletion, and minimum/maximum value finding. Values may sorted
either based on their own value, or based on a key value whose
value is computed by a key function (specified as an argument to
the constructor).
BinarySearchTree allows duplicates -- i.e., a BinarySearchTree may
contain multiple values that are equal to one another (or multiple
values with the same key). The ordering of equal values, or
values with equal keys, is undefined.
"""
def __init__(self, sort_key=None):
"""
Create a new empty BST. If a sort key is specified, then it
will be used to define the sort order for the BST. If an
explicit sort key is not specified, then each value is
considered its own sort key.
"""
self._root = [] # = empty node
self._sort_key = sort_key
self._len = 0 # keep track of how many items we contain.
#/////////////////////////////////////////////////////////////////
# Public Methods
#/////////////////////////////////////////////////////////////////
def insert(self, value):
"""
Insert the specified value into the BST.
"""
# Get the sort key for this value.
if self._sort_key is None:
sort_key = value
else:
sort_key = self._sort_key(value)
# Walk down the tree until we find an empty node.
node = self._root
while node:
if sort_key < node[_SORT_KEY]:
node = node[_LEFT]
else:
node = node[_RIGHT]
# Put the value in the empty node.
if sort_key is value:
node[:] = [[], [], value]
else:
node[:] = [[], [], value, sort_key]
self._len += 1
def minimum(self):
"""
Return the value with the minimum sort key. If multiple
values have the same (minimum) sort key, then it is undefined
which one will be returned.
"""
return self._extreme_node(_LEFT)[_VALUE]
def maximum(self):
"""
Return the value with the maximum sort key. If multiple values
have the same (maximum) sort key, then it is undefined which one
will be returned.
"""
return self._extreme_node(_RIGHT)[_VALUE]
def find(self, sort_key):
"""
Find a value with the given sort key, and return it. If no such
value is found, then raise a KeyError.
"""
return self._find(sort_key)[_VALUE]
def pop_min(self):
"""
Return the value with the minimum sort key, and remove that value
from the BST. If multiple values have the same (minimum) sort key,
then it is undefined which one will be returned.
"""
return self._pop_node(self._extreme_node(_LEFT))
def pop_max(self):
"""
Return the value with the maximum sort key, and remove that value
from the BST. If multiple values have the same (maximum) sort key,
then it is undefined which one will be returned.
"""
return self._pop_node(self._extreme_node(_RIGHT))
def pop(self, sort_key):
"""
Find a value with the given sort key, remove it from the BST, and
return it. If multiple values have the same sort key, then it is
undefined which one will be returned. If no value has the
specified sort key, then raise a KeyError.
"""
return self._pop_node(self._find(sort_key))
def values(self, reverse=False):
"""Generate the values in this BST in sorted order."""
if reverse:
return self._iter(_RIGHT, _LEFT)
else:
return self._iter(_LEFT, _RIGHT)
__iter__ = values
def __len__(self):
"""Return the number of items in this BST"""
return self._len
def __nonzero__(self):
"""Return true if this BST is not empty"""
return self._len>0
def __repr__(self):
return '<BST: (%s)>' % ', '.join('%r' % v for v in self)
def __str__(self):
return self.pprint()
def pprint(self, max_depth=10, frame=True, show_key=True):
"""
Return a pretty-printed string representation of this binary
search tree.
"""
t,m,b = self._pprint(self._root, max_depth, show_key)
lines = t+[m]+b
if frame:
width = max(40, max(len(line) for line in lines))
s = '+-'+'MIN'.rjust(width, '-')+'-+\n'
s += ''.join('| %s |\n' % line.ljust(width) for line in lines)
s += '+-'+'MAX'.rjust(width, '-')+'-+\n'
return s
else:
return '\n'.join(lines)
#/////////////////////////////////////////////////////////////////
# Private Helper Methods
#/////////////////////////////////////////////////////////////////
def _extreme_node(self, side):
"""
Return the leaf node found by descending the given side of the
BST (either _LEFT or _RIGHT).
"""
if not self._root:
raise IndexError('Empty Binary Search Tree!')
node = self._root
# Walk down the specified side of the tree.
while node[side]:
node = node[side]
return node
def _find(self, sort_key):
"""
Return a node with the given sort key, or raise KeyError if not found.
"""
node = self._root
while node:
node_key = node[_SORT_KEY]
if sort_key < node_key:
node = node[_LEFT]
elif sort_key > node_key:
node = node[_RIGHT]
else:
return node
raise KeyError("Key %r not found in BST" % sort_key)
def _pop_node(self, node):
"""
Delete the given node, and return its value.
"""
value = node[_VALUE]
if node[_LEFT]:
if node[_RIGHT]:
# This node has a left child and a right child; find
# the node's successor, and replace the node's value
# with its successor's value. Then replace the
# sucessor with its right child (the sucessor is
# guaranteed not to have a left child). Note: node
# and successor may not be the same length (3 vs 4)
# because of the key-equal-to-value optimization; so
# we have to be a little careful here.
successor = node[_RIGHT]
while successor[_LEFT]: successor = successor[_LEFT]
node[2:] = successor[2:] # copy value & key
successor[:] = successor[_RIGHT]
else:
# This node has a left child only; replace it with
# that child.
node[:] = node[_LEFT]
else:
if node[_RIGHT]:
# This node has a right child only; replace it with
# that child.
node[:] = node[_RIGHT]
else:
# This node has no children; make it empty.
del node[:]
self._len -= 1
return value
def _iter(self, pre, post):
# Helper for sorted iterators.
# - If (pre,post) = (_LEFT,_RIGHT), then this will generate items
# in sorted order.
# - If (pre,post) = (_RIGHT,_LEFT), then this will generate items
# in reverse-sorted order.
# We use an iterative implemenation (rather than the recursive one)
# for efficiency.
stack = []
node = self._root
while stack or node:
if node: # descending the tree
stack.append(node)
node = node[pre]
else: # ascending the tree
node = stack.pop()
yield node[_VALUE]
node = node[post]
def _pprint(self, node, max_depth, show_key, spacer=2):
"""
Returns a (top_lines, mid_line, bot_lines) tuple,
"""
if max_depth == 0:
return ([], '- ...', [])
elif not node:
return ([], '- EMPTY', [])
else:
top_lines = []
bot_lines = []
mid_line = '-%r' % node[_VALUE]
if len(node) > 3: mid_line += ' (key=%r)' % node[_SORT_KEY]
if node[_LEFT]:
t,m,b = self._pprint(node[_LEFT], max_depth-1,
show_key, spacer)
indent = ' '*(len(b)+spacer)
top_lines += [indent+' '+line for line in t]
top_lines.append(indent+'/'+m)
top_lines += [' '*(len(b)-i+spacer-1)+'/'+' '*(i+1)+line
for (i, line) in enumerate(b)]
if node[_RIGHT]:
t,m,b = self._pprint(node[_RIGHT], max_depth-1,
show_key, spacer)
indent = ' '*(len(t)+spacer)
bot_lines += [' '*(i+spacer)+'\\'+' '*(len(t)-i)+line
for (i, line) in enumerate(t)]
bot_lines.append(indent+'\\'+m)
bot_lines += [indent+' '+line for line in b]
return (top_lines, mid_line, bot_lines)
try:
# Try to use the python recipe:
# <http://code.activestate.com/recipes/277940/>
# This will only work if that recipe has been saved a
# "optimize_constants.py".
from optimize_constants import bind_all
bind_all(BinarySearchTree)
except:
pass
