03-built-in-functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "dc4bdc06",
   "metadata": {},
   "source": [
    "# Built-in Functions and Help"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13900cc7-2e14-4c4d-836d-a4b7c21c0355",
   "metadata": {},
   "source": [
    "## Use comments to add documentation to programs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb82acaf-b5a8-4d82-96cb-cf493f7d3fda",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# This sentence isn't executed by Python.\n",
    "adjustment = 0.5   # Neither is this - anything after '#' is ignored."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "35e2819a-9781-4e26-85f5-9df2fe9d86b7",
   "metadata": {},
   "source": [
    "## A function may take zero or more arguments.\n",
    "\n",
    "- We have seen some functions already — now let’s take a closer look.\n",
    "- An argument is a value passed into a function.\n",
    "- `len` takes exactly one.\n",
    "- `int`, `str`, and `float` create a new value from an existing one.\n",
    "- `print` takes zero or more.\n",
    "- `print` with no arguments prints a blank line.\n",
    "  - Must always use parentheses, even if they’re empty, so that Python knows a function is being called."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e4ef16ec-66e9-4355-a196-38fc2d587f70",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print('before')\n",
    "print()\n",
    "print('after')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92a8197d-b793-475a-8b81-a91cb89f0951",
   "metadata": {},
   "source": [
    "## Every function returns something.\n",
    "\n",
    "- Every function call produces some result.\n",
    "- If the function doesn’t have a useful result to return, it usually returns the special value `None`. `None` is a Python object that stands in anytime there is no value."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e1d3fb5-c31c-4538-aa08-891643ab1162",
   "metadata": {},
   "source": [
    "## Commonly-used built-in functions include `max`, `min`, and `round`.\n",
    "\n",
    "- Use `max` to find the largest value of one or more values.\n",
    "- Use `min` to find the smallest.\n",
    "- Both work on character strings as well as numbers.\n",
    "  - “Larger” and “smaller” use (0-9, A-Z, a-z) to compare letters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fca6e0ad-78b4-4d25-9e28-5b9b9f9b0843",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(max(1, 2, 3))\n",
    "print(min('a', 'A', '0'))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f1ec40f0-0010-4bca-9c3b-4c6079c5e50d",
   "metadata": {},
   "source": [
    "## Functions may only work for certain (combinations of) arguments.\n",
    "\n",
    "- `max` and `min` must be given at least one argument.\n",
    "  - “Largest of the empty set” is a meaningless question.\n",
    "- And they must be given things that can meaningfully be compared."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9a86a6a4-5010-4157-b387-0ba62784a725",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(max(1, 'a'))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d2f631e-3cca-41fc-ba7d-398276248e24",
   "metadata": {},
   "source": [
    "## Functions may have default values for some arguments.\n",
    "\n",
    "- `round` will round off a floating-point number.\n",
    "- By default, rounds to zero decimal places."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e80f480-83fb-4ad4-9b92-a14512941aaa",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "round(3.712)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "375412fe-3875-4293-8806-9843d1fc09b1",
   "metadata": {},
   "source": [
    "- We can specify the number of decimal places we want."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b2df524a-f139-4690-9f49-a9160ece0124",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "round(3.712, 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e916a0b4-8974-4b10-81f6-8c58da6cf9ac",
   "metadata": {},
   "source": [
    "## Functions attached to objects are called methods.\n",
    "\n",
    "- Functions can take another form that will be common when working with `pandas`.\n",
    "- Methods have parentheses like functions, but come after the variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "abf3839a-af5e-48d2-8e9b-093d3fec1013",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "my_string = 'Hello world!'  # creation of a string object \n",
    "print(len(my_string))       # the len function takes a string as an argument and returns the length of the string\n",
    "print(my_string.swapcase()) # calling the swapcase method on the my_string object"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "752d3b92-5167-4fb8-8587-5d5c28cf2a46",
   "metadata": {},
   "source": [
    "You might even see them chained together. They operate left to right."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9cfc53cf-aa6c-4028-ae44-9717aa9a744f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(my_string.isupper())          # Not all the letters are uppercase\n",
    "print(my_string.upper())            # This capitalizes all the letters\n",
    "print(my_string.upper().isupper())  # Now all the letters are uppercase"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c501ff88-dbb0-4f20-a941-9069a624a608",
   "metadata": {},
   "source": [
    "## Use the built-in function `help` to get help for a function.\n",
    "\n",
    "- Every built-in function has online documentation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c599c532-2348-425c-852b-65345b6ea00e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "help(round)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36193a3c-1112-481d-9798-989f2a68553c",
   "metadata": {},
   "source": [
    "## The Jupyter Notebook has two ways to get help.\n",
    "\n",
    "1. Place the cursor near where the function is invoked in a cell (i.e., the function name or its parameters),\n",
    "   - Hold down <kbd>Shift</kbd>, and press <kbd>Tab</kbd>.\n",
    "   - Do this several times to expand the information returned.\n",
    "2. Type the function name in a cell with a question mark after it. Then run the cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "362f95b6-9aaf-4243-8836-b4cc8c0a6d58",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "help?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0e2ebf20-18b1-4f6f-8e04-130666045b76",
   "metadata": {},
   "source": [
    "## Python reports a syntax error when it can’t understand the source of a program.\n",
    "\n",
    "Won’t even try to run the program if it can’t be parsed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6b4c3367-54d8-420c-999e-5790f3866c9c",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Forgot to close the quote marks around the string.\n",
    "name = 'Feng"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e9a3059-e245-4293-bb73-8f54be726c4f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# An extra '=' in the assignment.\n",
    "age = = 52"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fef9d180-e3d7-42f8-83e5-6338f6ef1be3",
   "metadata": {},
   "source": [
    "Look more closely at the error message:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "da237e2a-e51b-49fe-ab40-ac5424ae4df1",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(\"hello world\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81c7a7a7-9b8c-429a-add1-5504646d82b1",
   "metadata": {},
   "source": [
    "- The message indicates a problem on first line of the input (“line 1”).\n",
    "- Next is the problematic line of code, indicating the problem with a ^ pointer."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "03c0d586-c0f0-4f6b-92ac-b2bbb3437d55",
   "metadata": {},
   "source": [
    "## Python reports a runtime error when something goes wrong while a program is executing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ee6a6483-b3d5-4f65-a3cb-b77dfd432c9a",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "age = 53\n",
    "remaining = 100 - aege # mis-spelled 'age'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c5b819ee-b38d-4c41-9af2-793820e64f53",
   "metadata": {},
   "source": [
    "## Key Points\n",
    "\n",
    "- **Use comments to add documentation to programs.**\n",
    "- **A function may take zero or more arguments.**\n",
    "- **Commonly-used built-in functions include `max`, `min`, and `round`.**\n",
    "- **Functions may only work for certain (combinations of) arguments.**\n",
    "- **Functions may have default values for some arguments.**\n",
    "- **Use the built-in function `help` to get help for a function.**\n",
    "- **The Jupyter Notebook has two ways to get help.**\n",
    "- **Every function returns something.**\n",
    "- **Python reports a syntax error when it can’t understand the source of a program.**\n",
    "- **Python reports a runtime error when something goes wrong while a program is executing.**\n",
    "- **Fix syntax errors by reading the source code, and runtime errors by tracing the program’s execution.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d209e602-1d90-414e-8917-d18f9c5adb37",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}