Documentation/ConvertToHexDocumentation.ipynb

{
  "metadata": {
    "language_info": {
      "codemirror_mode": {
        "name": "python",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.8"
    },
    "kernelspec": {
      "name": "python",
      "display_name": "Python (Pyodide)",
      "language": "python"
    }
  },
  "nbformat_minor": 4,
  "nbformat": 4,
  "cells": [
    {
      "cell_type": "markdown",
      "source": "# ConvertToHex module's documentation\n***\nThis file is made to make sure that the user can understand how this whole program works by documenting each module and its functions, but also to assure ourselves that our code is readable enough to be understood even if months have passed since by.\n\n## Table of content\n1. [The main function](#The-main-function)\n2. [The two side functions](#convert_dec_to_hex-(n)-and-convert_bin_to_hex(n))\n3. [The different subfunctions](#The-different-subfunctions)",
      "metadata": {}
    },
    {
      "cell_type": "markdown",
      "source": "## The main function",
      "metadata": {}
    },
    {
      "cell_type": "code",
      "source": "def convert_to_hex (n, base):\n    if base == \"dec\":\n        return convert_dec_to_hex (n)\n    elif base == \"bin\":\n        return convert_bin_to_hex (n)\n    elif base == \"hex\":\n        return str (n)\n    else:\n        return \"ERROR : NOT A SUPPORTED BASE YET. IT FUNCTIONS ONLY FOR bin/dec/hex BASES ONLY\"",
      "metadata": {
        "trusted": true
      },
      "execution_count": 3,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": "This is the only function that should be used outside of this module.\n\nThe main function's name is pretty self-explanatory : it converts a given integer contained in a string into another base. To do so, `convert_to_hex` takes two arguments : `n`, the string containing the integer, and `base`, the string indicating `n`'s base.\n\nThis function first checks the argument `base` and returns the result of the adequate function : if the initial base is decimal, then it will return the result of `convert_dec_to_hex (n)`, for example. If the initial base is hexadecimal, just like the final base, we just return n converted to string, in case `n` wasn't passed as a string.\n\nIf the base is not identified or is not supported yet, we return an error. Although this shouldn't happen, since the `ParseInput.py` module checks the input's validity, we kept this. Otherwise the whole program would have crashed if the other module's control didn't work out.",
      "metadata": {}
    },
    {
      "cell_type": "markdown",
      "source": "## convert_dec_to_hex (n) and convert_bin_to_hex (b)",
      "metadata": {}
    },
    {
      "cell_type": "code",
      "source": "def convert_dec_to_hex (n):\n    converted_n = \"\"\n    is_negative = int (n) < 0\n    if is_negative:\n        n = n [1:]\n    while True:\n        result, remainder = divmod (int (n), 16)\n        converted_n += convert_remainder (remainder)\n        if result == 0:\n            break\n        n = result\n\n    converted_n = reverse_str (converted_n)\n    if is_negative:\n        converted_n = \"-\" + converted_n\n    return converted_n",
      "metadata": {},
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": "This is the key function of the module.\nIt takes a string argument n, assumes it is in decimal notation, and returns its hexadecimal form in a string.\n\nThis function is based on a very simple algorithm : we basically keep dividing n by 16 (that's why we update n to the result of this division) and we keep all remainders that we have converted into hexadecimal notation (using the created `convert_remainder` function. We continue dividing until the quotient of the division is equal to zero. In that case, we reverse the list of remainders we have gotten and we have now the result of our conversion. The remainders are conserved in the string called `converted_n`.\n\nIn case n appears to be a negative number contained in a string, we take out the minus sign during the algorithm, and then we put it back before returning it, as it logically should still be negative, despite its base.",
      "metadata": {}
    },
    {
      "cell_type": "code",
      "source": "def convert_bin_to_hex (b):\n    n = convert_to_dec (b, \"bin\")\n    return convert_dec_to_hex (n)",
      "metadata": {},
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": "This function takes a binary number contained in a string, and returns its hexadecimal notation.\n\nThe algorithm behind this function is relatively simple : we convert the binary number to decimal (using the `convert_to_dec` function coming from the `ConvertToDec.py` module we have imported, cf its documentation), then we use the previous function that converts decimal numbers to hexadecimal numbers. As such, the return type of this function is string as well.",
      "metadata": {}
    },
    {
      "cell_type": "markdown",
      "source": "## The different subfunctions",
      "metadata": {}
    },
    {
      "cell_type": "code",
      "source": "def convert_remainder (remainder):\n    higher_coefs = {\n        10 : \"a\",\n        11 : \"b\",\n        12 : \"c\",\n        13 : \"d\",\n        14 : \"e\",\n        15 : \"f\",\n    }\n    if remainder < 10:\n        return str (remainder)\n    else:\n        return higher_coefs [remainder]",
      "metadata": {},
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": "This is a function taking an integer called `remainder` and returns a string.\n\nThis function is used when converting the remainders to the hexadecimal notation (0123456789abcdef).\nIf the remainder happens to be inferior to ten, we can return it as it is. Provided it isn't, we use the remainder as a key in a dictionary containing the coefficients with their corresponding letters (10 for a, 11 for b, 12 for c, etc.), which then returns the value paired with that key-remainder in that same dictionary (cf data structures in python).\nWe chose to use a dictionary rather than a mountain of `elif`s, since it is:\n* cleaner ;\n* shorter ;\n* easier to read ;\n* simpler.\n\nThis function can also be used as for help to developpers needing to convert a remainder that could be higher than our hexadecimal base, as we can expand a dictionary as we wish, instead of creating another `elif` statement with its own block, with its own lines of code. The dictionary here really helps us, and simplifies the task by a lot.",
      "metadata": {}
    },
    {
      "cell_type": "code",
      "source": "def reverse_str (s):\n    return s [::-1]",
      "metadata": {},
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": "This function takes a string argument and returns its reversed string.\n\nIt is only used once, in the `convert_dec_to_hex (n)` function, but it improves readibility - which should not be ignored! -. The string is reversed using a slicing method that can be used for lists as well as for strings. The syntax for python's slicing method is `[start_index_included : end_index_excluded : step]` using only integers. Since we want to use the whole string, we do not need to specify the start and the end index, that's why we can leave it blank, as Python understands that we want to use the whole string. The step is what interests us. The default step (right-to-left reading) is 1. So to read from left-to-right, it logically should be -1. As such, we have sliced the string correctly, returned it in its reversed form.",
      "metadata": {}
    },
    {
      "cell_type": "code",
      "source": "",
      "metadata": {},
      "execution_count": null,
      "outputs": []
    }
  ]
}