{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The Array-Backed List\n",
    "\n",
    "## Agenda\n",
    "\n",
    "1. The List **Abstract Data Type** (ADT)\n",
    "2. A List **Data Structure**\n",
    "3. Our List API\n",
    "4. Getting started: how to store our data?\n",
    "5. Built-in `list` as array\n",
    "6. The `ArrayList` data structure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. The List **Abstract Data Type** (ADT)\n",
    "\n",
    "An **abstract data type (ADT)** defines a *conceptual model* for how data may be stored and accessed.\n",
    "\n",
    "A **list ADT** is a data container where:\n",
    "\n",
    "- values are ordered in a *sequence*\n",
    "- each value has at most one preceding and one succeeding value\n",
    "- a given value may appear more than once in a list\n",
    "\n",
    "Other common ADTs (some of which we'll explore later) include:\n",
    "\n",
    "- Stacks\n",
    "- Queues\n",
    "- Priority Queues\n",
    "- Maps\n",
    "- Graphs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. A List **Data Structure**\n",
    "\n",
    "A **list data structure** is a *concrete implementation* of the list ADT in some programming language, which, in addition to adhering to the basic premises of the ADT, will also typically support operations that:\n",
    "\n",
    "- access values in the list by their position (index)\n",
    "- append and insert new values into the list\n",
    "- remove values from the list\n",
    "\n",
    "The implementation of any data structure will generally rely on simpler, constituent data types (e.g., \"primitive\" types offered by the language), the choice of which may affect the runtime complexities of said operations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. The List API\n",
    "\n",
    "The operations we'll be building into our list data structures will be based on the [common](https://docs.python.org/3.6/library/stdtypes.html#common-sequence-operations) and [mutable](https://docs.python.org/3.6/library/stdtypes.html#mutable-sequence-types) sequence operations defined by the Python library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class List:        \n",
    "    ### subscript-based access ###\n",
    "    \n",
    "    def __getitem__(self, idx):\n",
    "        \"\"\"Implements `x = self[idx]`\"\"\"\n",
    "        pass\n",
    "\n",
    "    def __setitem__(self, idx, value):\n",
    "        \"\"\"Implements `self[idx] = x`\"\"\"\n",
    "        pass\n",
    "\n",
    "    def __delitem__(self, idx):\n",
    "        \"\"\"Implements `del self[idx]`\"\"\"\n",
    "        pass\n",
    "    \n",
    "    ### stringification ###\n",
    "            \n",
    "    def __repr__(self):\n",
    "        \"\"\"Supports inspection\"\"\"\n",
    "        return '[]'\n",
    "    \n",
    "    def __str__(self):\n",
    "        \"\"\"Implements `str(self)`\"\"\"\n",
    "        return '[]'\n",
    "\n",
    "    ### single-element manipulation ###\n",
    "    \n",
    "    def append(self, value):\n",
    "        pass\n",
    "    \n",
    "    def insert(self, idx, value):\n",
    "        pass\n",
    "    \n",
    "    def pop(self, idx=-1):\n",
    "        pass\n",
    "    \n",
    "    def remove(self, value):\n",
    "        pass\n",
    "    \n",
    "    ### predicates (T/F queries) ###\n",
    "    \n",
    "    def __eq__(self, other):\n",
    "        \"\"\"Implements `self == other`\"\"\"\n",
    "        return True\n",
    "\n",
    "    def __contains__(self, value):\n",
    "        \"\"\"Implements `val in self`\"\"\"\n",
    "        return True\n",
    "    \n",
    "    ### queries ###\n",
    "    \n",
    "    def __len__(self):\n",
    "        \"\"\"Implements `len(self)`\"\"\"\n",
    "        return len(self.data)\n",
    "    \n",
    "    def min(self):\n",
    "        pass\n",
    "    \n",
    "    def max(self):\n",
    "        pass\n",
    "    \n",
    "    def index(self, value, i, j):\n",
    "        pass\n",
    "    \n",
    "    def count(self, value):\n",
    "        pass\n",
    "\n",
    "    ### bulk operations ###\n",
    "\n",
    "    def __add__(self, other):\n",
    "        \"\"\"Implements `self + other_array_list`\"\"\"\n",
    "        return self\n",
    "    \n",
    "    def clear(self):\n",
    "        pass\n",
    "    \n",
    "    def copy(self):\n",
    "        pass\n",
    "\n",
    "    def extend(self, other):\n",
    "        pass\n",
    "\n",
    "    ### iteration ###\n",
    "    \n",
    "    def __iter__(self):\n",
    "        \"\"\"Supports iteration (via `iter(self)`)\"\"\"\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Getting started: how to store our data?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "class List:\n",
    "    def append(self, value):\n",
    "        pass\n",
    "    \n",
    "    def __getitem__(self, idx):\n",
    "        \"\"\"Implements `x = self[idx]`\"\"\"\n",
    "        pass\n",
    "\n",
    "    def __setitem__(self, idx, value):\n",
    "        \"\"\"Implements `self[idx] = x`\"\"\"\n",
    "        pass\n",
    "    \n",
    "    def __repr__(self):\n",
    "        \"\"\"Supports inspection\"\"\"\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Built-in `list` as array\n",
    "\n",
    "To use the built-in list as though it were a primitive array, we will constrain ourselves to just the following APIs on a given list `lst`:\n",
    "\n",
    "1. `lst[i]` for getting and setting values at an *existing, positive* index `i`\n",
    "2. `len(lst)` to obtain the number of slots\n",
    "3. `lst.append(None)` to grow the list by *one slot at a time*\n",
    "4. `del lst[len(lst)-1]` to delete the last slot in a list"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. The `ArrayList` data structure"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class ArrayList:\n",
    "    def __init__(self):\n",
    "        self.data = []\n",
    "\n",
    "    def append(self, value):\n",
    "        pass\n",
    "\n",
    "    def __getitem__(self, idx):\n",
    "        \"\"\"Implements `x = self[idx]`\"\"\"\n",
    "        assert(isinstance(idx, int))\n",
    "        pass\n",
    "\n",
    "    def __setitem__(self, idx, value):\n",
    "        \"\"\"Implements `self[idx] = x`\"\"\"\n",
    "        assert(isinstance(idx, int))\n",
    "        pass\n",
    "\n",
    "    def __delitem__(self, idx):\n",
    "        \"\"\"Implements `del self[idx]`\"\"\"\n",
    "        assert(isinstance(idx, int))\n",
    "        pass\n",
    "    \n",
    "    def __len__(self):\n",
    "        \"\"\"Implements `len(self)`\"\"\"\n",
    "        pass\n",
    "    \n",
    "    def __repr__(self):\n",
    "        \"\"\"Supports inspection\"\"\"\n",
    "        pass"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}