## mxStack - A Stack Implementation for Python

Interface : Examples : C API : Structure : Support : Download : Copyright & License : History : Home | Version 2.0.3

### Introduction

Though stacks can be emulated with Python lists, this type provides a simple interface to the data structure, both in Python and in C. Because of the function call overhead calling the methods from Python it is only a tad faster than a corresponding list emulation. Called from within an C extension shows a more significant performance increase. The included `stackbench.py` gives an impression of how the different methods relate w/r to speed:

    projects/Stack> python1.5 -O stackbench.py 1000 100 100
    list:  1.11
    tuples: 0.6
    Stack (with push + pop): 0.72
    Stack (with push + pop_many): 0.5
    Stack (with << + >>): 0.85
    Stack (with push_many + pop_many): 0.47
    UserStack: 1.79

Note that the tuple version has a few disadvantages when used for big stacks: for one it uses lots of memory (20 bytes per entry slot; Stack uses 20 bytes + 4 bytes per entry slot) and deallocation can become a problem -- this is done using recursion with one level per stack element. For small stacks it still is unbeatable, though (it has no function call overhead). BTW, the UserStack implementation uses the same technique: the figures shown mainly result from Python method call overhead.

Because stacks are normally used only temporarily, the Stack implementation only grows the memory buffer used for holding the entry slots. It never shrinks it. This has an advantage of reducing malloc overhead when doing e.g. depth first search, but also the disadvantage of using more memory in degenerate cases. To compensate for this, simply call the .resize() method every now and then. It forces the used buffer to be resized.

### Interface

Stack Constructors

There are two ways to construct a `Stack` from scratch:

`Stack([initial_size])`
  Returns a new empty Stack instance allocating at least the given number of slots for stack elements. If the parameter is not given a reasonable default is chosen.

`StackFromSequence(seq)`
  Constructs a Stack instance from the given sequence. The instance is filled with all the elements found in the sequence by pushing the items from index 0 to len(seq)-1 in that order, i.e. popping all elements from the Stack results in a reversed sequence.

Instance Methods

A `Stack` instance has the following methods:

`push(x)`
  Pushes the object x onto the stack.

`push_many(sequences)`
  Pushes the objects in `sequence` from left to right onto the stack. If errors occur during this process, the already pushed elements are discarded from the stack and it returns to its original state.

`pop()`
  Pops the top element off of the stack.

`pop_many(n)`
  Pops the top `n` elements and returns them in form of a tuple. If less than `n` elements are on the stack, the tuple will contain all stack entries and the stack will then be empty again. The order is top to bottom, i.e. `s.pop_many(2) == (s.pop(),s.pop())`

`as_tuple()`
  Returns the stack's content as tuple, without modifying it.

`as_list()`
  Returns the stack's content as list, without modifying it.

`clear()`
  Clears the stack.

`resize([size=len(stack)])`
  Resize the stack buffer to hold at least `size` entries.

  You can call this method without argument to force the stack to shrink its memory buffer to the minimal limit needed to hold the contained elements.

`__getitem__(index)`
  This is not really a method, but a slot providing access to the items on the Stack without popping them off the Stack.

  `index` works just like for Python lists, i.e. negative indices are normalized using the current length of the Stack.

  An `IndexError` is raised for invalid indices. This makes the Stack compatible to the `for`-loop statement allowing you to iterate over the Stack contents from bottom to top.

Note that no method for testing emtpyness is provided. Use len() for that or simply test for trueness, e.g. `while s: print s.pop()` will loop as long as there are elements left on the Stack s. This is much faster than going through the method calling process -- even when the method being called is written in C.

### Examples of Use

Well, there's not much to show:

    from mx.Stack import *
    s = Stack()
    for i in range(1000):
        s.push(i)
    while s:
        print s.pop()
    # which could also be done as:
    s = StackFromSequence(range(1000))
    while s:
        print s.pop()
    # or a little different
    s = StackFromSequence(range(1000))
    print s.as_tuple()
    print s.as_list()

### Supported Data Types in the C-API

Please have look at the file `mxStack.h` for details. Basically all of the above Python interfaces are also available in the C API.

To access the module, do the following (note the similarities with Python's way of accessing functions from a module):

    #include "mxStack.h"

    ...
        PyObject *v;

        /* Import the mxStack module */
        if (mxStack_ImportModuleAndAPI())
    	goto onError;

        /* Access functions from the exported C API through mxStack */
        v = mxStack.Stack(0);
        if (!v)
    	goto onError;

        /* Type checking */
        if (mxStack_Check(v))
            printf("Works.\n");

        Py_DECREF(v);
    ...

### Package Structure

    [Stack]
    	mxStack

Entries enclosed in brackets are packages (i.e. they are directories that include a `__init__.py` file). Ones without brackets are just simple subdirectories that are not accessible via `import`. These are used for compiling the C extension modules which will get installed in the same place where all your other site specific extensions live (e.g. `/usr/local/lib/python-x.xx/site-packages`).

The package Stack imports all symbols from the extension mxStack, so `import Stack; s = Stack.Stack()` gives you a Stack instance in `s`.

### Support

eGenix.com is providing commercial support for this package. If you are interested in receiving information about this service please see the eGenix.com Support Conditions.

### Copyright & License

© 1998-2000, Copyright by Marc-André Lemburg; All Rights Reserved. mailto: mal@lemburg.com

© 2000-2001, Copyright by eGenix.com Software GmbH, Langenfeld, Germany; All Rights Reserved. mailto: info@egenix.com

This software is covered by the eGenix.com Public License Agreement. The text of the license is also included as file "LICENSE" in the package's main directory.

By downloading, copying, installing or otherwise using the software, you agree to be bound by the terms and conditions of the eGenix.com Public License Agreement.

### History & Future

There were no significant changes between 2.0.2 and 2.0.3.

Changes from 2.0.0 to 2.0.2:

- Fixed a bug in the coercion code which surfaced due to the rich comparison changes in Python 2.1. Python 2.1 will now compare Stack objects to other objects without raising a TypeError.

Changes from 0.2.2 to 2.0.0:

- Added .pop_many(), .resize() and .clear().

- Added mxStack_PopMany, mxStack_PushMany, mxStack_Clear, mxStack_Length to the C API.

- Fixed a memory leak in StackFromSequence().

- Fixed in bug in the non-zero testing code.

- Added __getitem__ slot and mxStack_GetItem C API. After an idea by Adam Deprince.

- Moved the package under a new top-level package 'mx'. It is part of the eGenix.com mx BASE distribution.

Changes from 0.1 to 0.2.2:

- Version 0.2.2: Fixed a bug that caused stack.push() to dump core when called without argument. Also added some minor speedups.

- Version 0.2.1: added method pop_many().

- Converted the module into a package called 'Stack'. This imports the C extension mxStack.

© 1998-2000, Copyright by Marc-André Lemburg; All Rights Reserved. mailto: mal@lemburg.com

© 2000-2001, Copyright by eGenix.com Software GmbH; All Rights Reserved. mailto: info@egenix.com