### Install Python Package

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Install the orderedstructs package from PyPi using pip.

```sh
$ pip install orderedstructs
```

--------------------------------

### Install Python Package for Development

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Install the orderedstructs package in development mode after cloning the repository and setting up requirements.

```sh
$ cd <skiplist>
$ pip install -r requirements.txt
$ python setup.py develop
```

--------------------------------

### Python Skip List Constructor Examples

Source: https://github.com/paulross/skiplist/blob/master/docs/source/api.md

Shows how to instantiate a PySkipList object with different data types like integers, floats, and bytes.

```Python
import cSkipList

sl = cSkipList.PySkipList(int) # Python 3, for Python 2 use PySkipList(long)
sl = cSkipList.PySkipList(float)
sl = cSkipList.PySkipList(bytes) # In Python 2 PySkipList(str) also works
```

--------------------------------

### DOT file generation command for insert example

Source: https://github.com/paulross/skiplist/blob/master/docs/source/visualisations.md

Command to convert a DOT file into a PNG image for the skip list insertion example. This uses the GraphViz 'dot' utility.

```bash
dot -odoc_insert.png -Tpng doc_insert.dot
```

--------------------------------

### Python Skip List Example

Source: https://github.com/paulross/skiplist/blob/master/docs/source/api.md

Demonstrates basic operations like insertion, checking for existence, retrieving size, and accessing elements by index using the PySkipList class.

```Python
import cSkipList

sl = cSkipList.PySkipList(float)

sl.insert(42.0)
sl.insert(21.0)
sl.insert(84.0)

sl.has(42.0) # True
sl.size()    # 3
sl.at(1)     # 42.0

sl.has(42.0) # True
sl.size()    # 3
sl.at(1)     # 42.0, raises IndexError if index out of range

sl.remove(21.0); # raises ValueError if value not present

sl.size()    # 2
sl.at(1)     # 84.0
```

--------------------------------

### Worst-Case Skip List Example

Source: https://github.com/paulross/skiplist/blob/master/docs/source/design.md

Demonstrates a mal-formed skip list structure that can lead to O(n) search complexity, degrading performance to that of a linear search.

```text
| 5 E |--| 8 0 |------------------------------------------------------->| NULL |
| 1 A |->| 1 B |--| 1 C |->| 1 D |->| 5 0 |---------------------------->| NULL |
| 1 A |->| 1 B |->| 1 C |->| 1 D |->| 1 E |->| 1 F |->| 1 G |->| 1 0 |->| NULL |
| HED |  |  A  |  |  B  |  |  C  |  |  D  |  |  E  |  |  F  |  |  G  |
```

--------------------------------

### C++ Skip List Usage Example

Source: https://github.com/paulross/skiplist/blob/master/docs/source/api.md

Demonstrates basic operations like insertion, checking for existence, retrieving size, accessing elements by index, and removing elements from a C++ skip list.

```cpp
#include "SkipList.h"

OrderedStructs::SkipList::HeadNode<double> sl;

sl.insert(42.0);
sl.insert(21.0);
sl.insert(84.0);

sl.has(42.0) // true
sl.size()    // 3
sl.at(1)     // 42.0, throws SkipList::IndexError if index out of range

sl.remove(21.0); // throws SkipList::ValueError if value not present

sl.size()    // 2
sl.at(1)     // 84.0
```

--------------------------------

### C++ Skip List Performance Test Output Example

Source: https://github.com/paulross/skiplist/blob/master/docs/source/performance.md

An example of the output from the C++ SkipList performance tests, showing PASS results for various tests and performance metrics like execution time in milliseconds and operations per second.

```text
                 test_very_simple_insert(): PASS
                                                     ...
                 test_roll_med_even_mean(): PASS
               perf_single_insert_remove(): 451.554 (ms) rate x.xe+06 /s
                                                    ...
            perf_roll_med_odd_index_wins(): vectors length:  1000000 window width: 524288 time: x.x (ms)
                            perf_size_of(): size_of(       1):      216 bytes ratio:      216 /sizeof(T):       x
                                                    ...
Final result: PASS
Exec time: x.x (s)
Bye, bye!
```

--------------------------------

### DOT file generation command for Python example

Source: https://github.com/paulross/skiplist/blob/master/docs/source/visualisations.md

Command to convert a DOT file generated from Python into a PNG image using the GraphViz 'dot' utility.

```bash
dot -odoc_simple_py.png -Tpng doc_simple_py.dot
```

--------------------------------

### Run Basic Python Tests

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Execute basic Python tests for the SkipList using pytest. Ensure 'pytest' and 'hypothesis' are installed. Navigate to the project root and run 'pytest tests/'.

```sh
cd <skiplist>
pytest tests/
```

--------------------------------

### PySkipList.at_seq(index, count)

Source: https://github.com/paulross/skiplist/blob/master/docs/source/api.md

Retrieves a sequence of values starting from a given index. Supports Pythonic negative indexing for the start index. Time complexity is O(count * log(n)).

```APIDOC
## `PySkipList.at_seq(index, count)`

### Description

This returns a tuple of `count` values starting at the given `index` which must be of type long. Negative values of the index are dealt with Pythonically. `count` must be positive. This tuple contains a copy of the data in the skip list. This will raise an `IndexError` if the `index` + `count` is >= size of the skip list. This is O(count * log(n)) for well formed skip lists.

### Parameters

#### Path Parameters
- **index** (long) - Required - The starting index for retrieving values.
- **count** (positive long) - Required - The number of values to retrieve.
```

--------------------------------

### Python API - PySkipList.at_seq

Source: https://github.com/paulross/skiplist/blob/master/docs/source/index.md

Retrieves a sequence of elements starting from a given index.

```APIDOC
## PySkipList.at_seq(index, count)

### Description
Retrieves a sequence of elements starting from a given index.

### Method
Not specified (likely a method call).

### Endpoint
Not applicable (Python API).

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
None.

### Request Example
```python
# Example usage:
# elements = skip_list.at_seq(start_index, num_elements)
```

### Response
#### Success Response
Returns a list of elements.

#### Response Example
None specified.
```

--------------------------------

### Create Seed Dictionary with C++ rand()

Source: https://github.com/paulross/skiplist/blob/master/docs/source/test_notes.md

Example of creating a SEED_DICT using C++'s rand() function exposed through Python bindings. This maps pseudo-random sequences to specific seeds for deterministic testing.

```python
SEED_DICT = {
    # ...
}
# ...
cSkipList.seed_rand()
cSkipList.toss_coin()
```

--------------------------------

### Python SkipList with Custom Objects

Source: https://github.com/paulross/skiplist/blob/master/README.md

Shows how to use a Python SkipList with user-defined objects, enabling custom sorting logic based on object attributes. The example defines a Person class with ordering based on last name and then first name.

```python
import functools
    
    @functools.total_ordering
    class Person:
        """Simple example of ordering based on last name/first name."""
        def __init__(self, first_name, last_name):
            self.first_name = first_name
            self.last_name = last_name
    
        def __eq__(self, other):
            try:
                return self.last_name == other.last_name and self.first_name == other.first_name
            except AttributeError:
                return NotImplemented

        def __lt__(self, other):
            try:
                return self.last_name < other.last_name or self.first_name < other.first_name
            except AttributeError:
                return NotImplemented
    
        def __str__(self):
            return '{}, {}'.format(self.last_name, self.first_name)

    import orderedstructs
    
    sl = orderedstructs.SkipList(object)

    sl.insert(Person('Peter', 'Pan'))
    sl.insert(Person('Alan', 'Pan'))
    assert sl.size() == 2
    assert str(sl.at(0)) == 'Pan, Alan' 
    assert str(sl.at(1)) == 'Pan, Peter'
```

--------------------------------

### Build Sphinx HTML Documentation

Source: https://github.com/paulross/skiplist/blob/master/docs/source/README.txt

Navigate to the docs directory and use 'make html' to build the Sphinx documentation.

```bash
cd <skiplist>/docs/
$ make html
```

--------------------------------

### Build All C++ and Python Tests

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Run all C++ and Python tests, and build all supported Python versions using the provided build script. Execute './build_all.sh' from the project root.

```sh
cd <skiplist>
./build_all.sh
```

--------------------------------

### Convert DOT Visualizations

Source: https://github.com/paulross/skiplist/blob/master/docs/source/README.txt

Navigate to the visualisations directory and run the dot_convert.py script to convert DOT files.

```bash
cd <skiplist>/docs/source/visualisations
python dot_convert.py
```

--------------------------------

### Build C++ Binary with CMake

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Build the C++ SkipList binary using CMake in release mode with parallel jobs. Navigate to the project root and use 'cmake --build'.

```sh
cd <skiplist>
cmake --build cmake-build-release --target SkipList -- -j 6
```

--------------------------------

### HeadNode::at (index, count, dest)

Source: https://github.com/paulross/skiplist/blob/master/docs/source/api.md

Loads a vector with a specified count of values starting from a given index. Throws an IndexError if the range is out of bounds. Complexity is O(count * log(n)).

```APIDOC
## HeadNode::at(size_t index, size_t count, std::vector<T> &dest) const

### Description
Loads a vector of type `T` with `count` values starting at the given `index`. Throws an `IndexError` if `index + count` is greater than or equal to the size of the skip list. The time complexity is O(count * log(n)) for well-formed skip lists.

### Method
`void HeadNode::at(size_t index, size_t count, std::vector<T> &dest) const;`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **index** (size_t) - Required - The starting zero-based index.
* **count** (size_t) - Required - The number of elements to load.
* **dest** (std::vector<T>&) - Required - The destination vector to load values into.
```

--------------------------------

### Run C++ Performance Tests (Release Build)

Source: https://github.com/paulross/skiplist/blob/master/docs/source/test_notes.md

Execute the C++ performance tests using a release build. Performance results are output to stdout and can be scraped for analysis.

```sh
$ cd src/cpp
$ make release
$ ./SkipList_R.exe
Running skip list tests...
                 test_very_simple_insert(): PASS
                      test_simple_insert(): PASS
             test_insert_and_remove_same(): PASS
             test_insert_remove_multiple(): PASS
                       test_ins_rem_rand(): PASS
              test_insert_n_numbers_same(): PASS
                                 test_at(): PASS
               perf_single_insert_remove(): 451.554 (ms) rate x.xe+06 /s
                                                    ...
            perf_roll_med_odd_index_wins(): vectors length:  1000000 window width: 524288 time: x.x (ms)
                            perf_size_of(): size_of(       1):      216 bytes ratio:      216 /sizeof(T):       x
...
                doc_insert_remove_repeat(): PASS
Final result: PASS
Exec time: 127.5 (s)
Bye, bye!
```

--------------------------------

### Get NumPy array data pointer

Source: https://github.com/paulross/skiplist/blob/master/docs/source/rolling_median.md

A utility function to retrieve the memory address of a NumPy array's data. This is useful for understanding memory management in shared memory operations.

```python
def np_data_pointer(a: np.ndarray) -> int:
    """The address of the actual data. 'data pointer' in np.info()."""
    return a.__array_interface__["data"][0]
```

--------------------------------

### Basic C++ SkipList Usage

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Demonstrates basic insertion, checking for elements, size, and retrieval by index in a C++ SkipList. Assumes C++17 compiler and correct include paths.

```cpp
#include "SkipList.h"

// Declare with any type that has sane comparison.
OrderedStructs::SkipList::HeadNode<double> sl;

sl.insert(42.0);
sl.insert(21.0);
sl.insert(84.0);

sl.has(42.0) // true
sl.size()    // 3
sl.at(1)     // 42.0, throws OrderedStructs::SkipList::IndexError if index out of range

sl.remove(21.0); // throws OrderedStructs::SkipList::ValueError if value not present

sl.size()    // 2
sl.at(1)     // 84.0
```

--------------------------------

### Skip List Growth Visualization in C++

Source: https://github.com/paulross/skiplist/blob/master/docs/source/visualisations.md

Creates multiple DOT file snapshots to visualize how a skip list grows as elements are inserted. This is useful for observing the dynamic changes in the skip list structure.

```cpp
#include "SkipList.h"

void doc_insert() {
    OrderedStructs::SkipList::HeadNode<int> sl;

    // Write out the empty head node
    sl.dotFile(std::cout);
    // Now insert a value and add the current representation to the DOT file
    for (int i = 0; i < 8; ++i) {
        sl.insert(i);
        sl.dotFile(std::cout);
    }
    // Finalise the dot file containing the snapshots.
    // This updates the internal references.
    sl.dotFileFinalise(std::cout);
}
```

--------------------------------

### Python SkipList with Custom Objects (Default Order)

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Shows how to use a Python SkipList with user-defined objects, sorting based on last name then first name. Requires functools.total_ordering.

```python
import functools

import orderedstructs

@functools.total_ordering
class Person:
    """Simple example of ordering based on last name/first name."""
    def __init__(self, first_name, last_name):
        self.first_name = first_name
        self.last_name = last_name

    def __eq__(self, other):
        try:
            return self.last_name == other.last_name \
                and self.first_name == other.first_name
        except AttributeError:
            return NotImplemented

    def __lt__(self, other):
        try:
            return self.last_name < other.last_name \
                or self.first_name < other.first_name
        except AttributeError:
            return NotImplemented

    def __str__(self):
        return '{}, {}'.format(self.last_name, self.first_name)

sl = orderedstructs.SkipList(object)

sl.insert(Person('Peter', 'Pan'))
sl.insert(Person('Alan', 'Pan'))
assert sl.size() == 2
assert str(sl.at(0)) == 'Pan, Alan'
assert str(sl.at(1)) == 'Pan, Peter'
```

--------------------------------

### Import necessary libraries for shared memory multiprocessing

Source: https://github.com/paulross/skiplist/blob/master/docs/source/rolling_median.md

Imports modules for multiprocessing, shared memory, typing, NumPy, and the orderedstructs package. This setup is required for the shared memory rolling median implementation.

```python
import multiprocessing
# Python 3.8+, need to be specific about importing this.
from multiprocessing import shared_memory
import typing

import numpy as np

import orderedstructs
```

--------------------------------

### Set GCC Environment Variable for Development

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Set the USING_GCC environment variable before running setup.py develop if using GCC to resolve warnings.

```sh
$ USING_GCC=1 python setup.py develop
```

--------------------------------

### Run C++ Release Tests

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Execute all C++ functional and performance tests in release mode. Navigate to the C++ source directory and run 'make release' followed by the executable.

```sh
cd <skiplist>/src/cpp
make release
./SkipList_R.exe
```

--------------------------------

### Simple Skip List Snapshot in C++

Source: https://github.com/paulross/skiplist/blob/master/docs/source/visualisations.md

Generates a single DOT file snapshot of a skip list after inserting several elements. Use this to visualize the final state of a skip list.

```cpp
#include "SkipList.h"

void doc_insert_simple() {
    OrderedStructs::SkipList::HeadNode<int> sl;

    sl.insert(42);
    sl.insert(84);
    sl.insert(21);
    sl.insert(100);
    sl.insert(12);

    sl.dotFile(std::cout);
    sl.dotFileFinalise(std::cout);
}
```

--------------------------------

### Sphinx Build Command

Source: https://github.com/paulross/skiplist/blob/master/docs/source/README.txt

The underlying command executed by 'make html' to build the Sphinx documentation.

```bash
sphinx-build -b html -d build/doctrees   source build/html
```

--------------------------------

### Simple Skip List Snapshot in Python

Source: https://github.com/paulross/skiplist/blob/master/docs/source/visualisations.md

Generates a DOT file representation of a Python skip list instance. This is useful for visualizing the structure of the skip list from Python code.

```python
import cSkipList

sl = cSkipList.PySkipList(float)

sl.insert(42.0)
sl.insert(21.0)
sl.insert(84.0)

dot_bytes = sl.dot_file()

with open('doc_simple_py.dot', 'w') as dot_file:
    dot_file.write(dot_bytes.decode('ascii'))
```

--------------------------------

### C++ SkipList Basic Usage

Source: https://github.com/paulross/skiplist/blob/master/README.md

Demonstrates basic insertion, checking for elements, size retrieval, and accessing elements by index in a C++ SkipList. Handles potential errors like index out of range or value not present during removal.

```cpp
#include "SkipList.h"
        
    // Declare with any type that has sane comparison.
    OrderedStructs::SkipList::HeadNode<double> sl;
    
    sl.insert(42.0);
    sl.insert(21.0);
    sl.insert(84.0);
    
    sl.has(42.0) // true
    sl.size()    // 3
    sl.at(1)     // 42.0, throws OrderedStructs::SkipList::IndexError if index out of range

    sl.remove(21.0); // throws OrderedStructs::SkipList::ValueError if value not present
    
    sl.size()    // 2
    sl.at(1)     // 84.0
```

--------------------------------

### Run C++ Tests with CMake

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Execute the C++ SkipList tests after building with CMake. Run the binary located in the 'cmake-build-release' directory.

```sh
cd <skiplist>
./cmake-build-release/SkipList
```

--------------------------------

### PySkipList Constructor

Source: https://github.com/paulross/skiplist/blob/master/docs/source/api.md

Initializes a new PySkipList instance. The constructor requires a Python type to define the data type stored within the skip list.

```APIDOC
## `cSkipList.PySkipList(type)`

### Description

Initializes a new PySkipList instance. The constructor requires a Python type to define the data type stored within the skip list.

### Parameters

#### Path Parameters
- **type** (type) - Required - The Python type for the skip list elements (e.g., int, float, bytes).
```

--------------------------------

### Python SkipList with Custom Objects (Reverse Order)

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Demonstrates reverse ordering for Python SkipList with custom objects by providing a comparison function to the constructor.

```python
# As above

sl = orderedstructs.SkipList(object, lambda x, y: y < x)

sl.insert(Person('Peter', 'Pan'))
sl.insert(Person('Alan', 'Pan'))
assert sl.size() == 2
assert str(sl.at(0)) == 'Pan, Peter'
assert str(sl.at(1)) == 'Pan, Alan'
```

--------------------------------

### Run C++ Thread-Safe Release Tests

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Execute all C++ functional and performance tests for a thread-safe SkipList. Build with 'make release CXXFLAGS=-DSKIPLIST_THREAD_SUPPORT'.

```sh
cd <skiplist>/src/cpp
make release CXXFLAGS=-DSKIPLIST_THREAD_SUPPORT
./SkipList_R.exe
```

--------------------------------

### PySkipList.dot_file()

Source: https://github.com/paulross/skiplist/blob/master/docs/source/api.md

Returns a DOT file representation of the skip list's current state as a bytes object. Requires a specific macro to be defined.

```APIDOC
## PySkipList.dot_file()

### Description
Returns a representation of the current state of the skip list as a bytes object that represents a DOT file. This method requires the macro `INCLUDE_METHODS_THAT_USE_STREAMS` to be defined.

### Method
N/A (Python method)

### Endpoint
N/A (Python method)

### Parameters
None

### Request Example
N/A (Python method)

### Response
#### Success Response
- **dot_file_content** (bytes) - A bytes object representing the DOT file content of the skip list.
```

--------------------------------

### Basic Python SkipList Usage

Source: https://github.com/paulross/skiplist/blob/master/docs/source/introduction.md

Demonstrates basic insertion, checking for elements, size, and retrieval by index in a Python SkipList. Supports float, long, bytes, and object types.

```python
import orderedstructs

# Declare with a type. Supported types are long/float/bytes/object.
sl = orderedstructs.SkipList(float)

sl.insert(42.0)
sl.insert(21.0)
sl.insert(84.0)

sl.has(42.0) # True
sl.size()    # 3
sl.at(1)     # 42.0, raises IndexError if index out of range

sl.remove(21.0) # raises ValueError if value not present

sl.size()    # 2
sl.at(1)     # 84.0
```

--------------------------------

### Generate GNUPlot Files

Source: https://github.com/paulross/skiplist/blob/master/docs/source/README.txt

Navigate to the plots directory and execute the make_plots.sh script to create GNUPlot files.

```bash
cd <skiplist>/docs/source/plots
./make_plots.sh
```

--------------------------------

### C++ Skip List Performance Test Execution

Source: https://github.com/paulross/skiplist/blob/master/docs/source/performance.md

This shell command sequence builds the C++ SkipList release version and executes its performance tests. Ensure you are in the 'src/cpp' directory before running.

```sh
cd src/cpp
make release
./SkipList_R.exe
```

--------------------------------

### Python SkipList Basic Usage

Source: https://github.com/paulross/skiplist/blob/master/README.md

Demonstrates basic insertion, checking for elements, size retrieval, and accessing elements by index in a Python SkipList with float elements. Handles potential errors like index out of range or value not present during removal.

```python
import orderedstructs
    
    # Declare with a type. Supported types are long/float/bytes/object.
    sl = orderedstructs.SkipList(float)
    
    sl.insert(42.0)
    sl.insert(21.0)
    sl.insert(84.0)
    
    sl.has(42.0) # True
    sl.size()    # 3
    sl.at(1)     # 42.0

    sl.has(42.0) # True
    sl.size()    # 3
    sl.at(1)     # 42.0, raises IndexError if index out of range

    sl.remove(21.0); # raises ValueError if value not present
    
    sl.size()    # 2
    sl.at(1)     # 84.0
```

--------------------------------

### HeadNode::dotFile(std::ostream &os) const

Source: https://github.com/paulross/skiplist/blob/master/docs/source/api.md

Writes a subgraph representation of the skip list's current state to the provided output stream in DOT file format. Requires the INCLUDE_METHODS_THAT_USE_STREAMS macro.

```APIDOC
## HeadNode::dotFile(std::ostream &os) const

### Description
Writes a representation of the current state of the skip is as a fragment of a DOT file to the stream `os` as a `subgraph`. The first call writes the preamble and subgraph; subsequent calls may produce undefined DOT format if not used correctly.

### Method
CONST

### Endpoint
N/A

### Parameters
#### Path Parameters
- **os** (std::ostream &) - Required - The output stream to write the DOT representation to.

### Request Example
```cpp
#include "SkipList.h"

OrderedStructs::SkipList::HeadNode<double> sl;
// ... insertions ...
sl.dotFile(std::cout);
```

### Response
#### Success Response (void)
- Writes DOT file fragment to the provided stream.
```

--------------------------------

### C++ Thread-Safe SkipList Usage

Source: https://github.com/paulross/skiplist/blob/master/README.md

Illustrates how to use a C++ SkipList across multiple threads for concurrent insertion, removal, and reading operations. Requires the SKIPLIST_THREAD_SUPPORT macro to be set during compilation.

```cpp
#include <thread>
#include <vector>

    #include "SkipList.h"

    void do_something(OrderedStructs::SkipList::HeadNode<double> *pSkipList) {
        // Insert/remove items into *pSkipList
        // Read items inserted by other threads.
    }

    OrderedStructs::SkipList::HeadNode<double> sl;
    std::vector<std::thread> threads;

    for (size_t i = 0; i < thread_count; ++i) {
        threads.push_back(std::thread(do_something, &sl));
    }
    for (auto &t: threads) {
        t.join();
    }
    // The SkipList now contains the totality of the thread actions.
```

--------------------------------

### C++ API - HeadNode::at (index)

Source: https://github.com/paulross/skiplist/blob/master/docs/source/index.md

Retrieves an element at a specific index.

```APIDOC
## HeadNode::at(size_t index) const

### Description
Retrieves an element at a specific index.

### Method
Not specified (likely a member function call).

### Endpoint
Not applicable (C++ API).

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
None.

### Request Example
```cpp
// Example usage:
// T element = headNode.at(index);
```

### Response
#### Success Response
Returns the element at the specified index.

#### Response Example
None specified.
```