{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Cursors"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The most basic element of this package is the `Cursor`.\n",
    "Roughly, a `Cursor` represents some data + a selection of it.\n",
    "\n",
    "Let's build our first `Cursor`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from byteparsing import Cursor"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cursor(data=b'Hello world!', begin=0, end=3, encoding='utf-8')\n"
     ]
    }
   ],
   "source": [
    "data = b\"Hello world!\"\n",
    "\n",
    "c = Cursor(data, begin=0, end=3)\n",
    "print(c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Cursor` is implemented as a `dataclass`.\n",
    "This means that it contains fields (particularly: `data`, `begin`, `end`, and `encoding`), and also methods.\n",
    "\n",
    "For instance, the method `content` returns the subsetted data (_i.e._: the `data` between `begin` and `end`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "b'Hel'"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "c.content # This method is decorated as a property, so parentheses are not needed"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The method `increment` returns a new cursor where `end` has been increased (by default, to `end + 1`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cursor(data=b'Hello world!', begin=0, end=3, encoding='utf-8')\n",
      "Cursor(data=b'Hello world!', begin=0, end=4, encoding='utf-8')\n"
     ]
    }
   ],
   "source": [
    "c = Cursor(data, begin=0, end=3)\n",
    "print(c)\n",
    "ci = c.increment()\n",
    "print(ci)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An interesting property of cursors is that they can be evaluated to a boolean. Particularly, a `Cursor` is `True` if and only if `end` is not at the end of the `data` string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "cT = Cursor(data, begin=0, end=0)\n",
    "cF = Cursor(data, begin=0, end=len(data))\n",
    "\n",
    "assert(cT)\n",
    "assert(not cF)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Wait a second. Why would we want a `Cursor` to be `True` or `False`? The reason is that it is very convenient for easily looping _\"to the end of the data\"_.\n",
    "\n",
    "See for instance the loop below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "b'H'\n",
      "b'He'\n",
      "b'Hel'\n",
      "b'Hell'\n",
      "b'Hello'\n",
      "b'Hello '\n",
      "b'Hello w'\n",
      "b'Hello wo'\n",
      "b'Hello wor'\n",
      "b'Hello worl'\n",
      "b'Hello world'\n",
      "b'Hello world!'\n"
     ]
    }
   ],
   "source": [
    "c = Cursor(data, begin=0, end=0)\n",
    "while c:\n",
    "    c = c.increment()\n",
    "    print(c.content)"
   ]
  }
 ],
 "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.7.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}