sec-function.ptx

<?xml version="1.0" encoding="UTF-8"?>

<!--*****************************************
This is part of Basic Programming
Copyright (C) 2024
Phạm Công Vinh
See the file COPYING for copying conditions.
******************************************-->

<section xml:id="sec-function" xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Functions</title>

  <objectives>
    <ul>
      <li>Learn about functions and how to use them.</li>
    </ul>
  </objectives>
  
  <p>
    Again we are met with a familiar concept in mathematics<mdash /><term>functions</term>, which also play a big role in programming.
  </p>

  <p>
    Suppose we have 100 mathematical expressions:

    <md>
      <mrow>1^2 + 2 \cdot 1 + 1</mrow>
      <mrow>2^2 + 2 \cdot 2 + 1</mrow>
      <mrow>\vdots</mrow>
      <mrow>100^2 + 2 \cdot 100 + 1</mrow>
    </md>

    We realize they are all quadratics; therefore, we can shorten our representation using a function as follows:

    <md>
      <mrow>f(x) = x^2 + 2 \cdot x + 1</mrow>
      <mrow></mrow>
      <mrow>f(1)</mrow>
      <mrow>f(2)</mrow>
      <mrow>\vdots</mrow>
      <mrow>f(100)</mrow>
    </md>
  </p>

  <p>
    That is also the essence of <term>functions</term> in programming.
  </p>

  <definition xml:id="def-function">
    <idx><h>Definitions</h><h>of functions</h></idx>
    <statement>
      <p>
        A <term>function</term> is a reusable block of code designed to perform a specific task.
      </p>
      <p>
        A function can accept zero, one, or more <term>inputs</term>, which are also called <term>parameters</term>.
      </p>
      <p>
        A function can return zero, one, or more <term>outputs</term>, which are also called <term>return values</term>.
      </p>
      <p>
        To <term>declare</term> a function is to create a new one.
      </p>
      <p>
        To <term>call</term> a function is to use an existing one.
      </p>
    </statement>
  </definition>

  <note>
    <idx><h>Notes</h><h>on using functions</h></idx> 
    <p>
      In this section, we will not go into function declaration. Instead, we'll focus on using functions that are built-in or provided by libraries.
    </p>
    <p>
      To read more about function declaration, refer to <xref ref="sec-declare-function" text="type-local"/>.
    </p>
  </note>

  <technology xml:id="syntax-call-function">
    <title>Calling a function</title>
    <idx><h>Syntax</h><h>of calling functions</h></idx>
    <p>
      <em>Depending on how a function is declared</em>, we have two ways to call it: <me>{\color{blue} \text{function's name}} \, \text{(input 1, input 2, ...)}</me> or <me>\text{input 1} . \! {\color{blue} \text{function's name}} \, \text{(input 2, input 3, ...)}</me>
    </p>
  </technology>
  
  <p>
    A familiar example is the function <c>print()</c>, which can be called anywhere and with any number of inputs. It then shows them in the terminal.
  </p>

  <sage language="python">
    <input>
      print(5) 
      print()
      print(2, -2)
      print(1, "Hello World!", 5.5)
    </input>
  </sage>
  <problem>
    <pre>
      5
      
      2 -2
      1 Hello World! 5.5
    </pre>
  </problem>
  <investigation>
    <idx><h>Code examples</h><h>function print()</h></idx>
    <idx><h>Functions</h><h>print()</h></idx>
    <p></p>
    <p>
      Line 1: We call the function <c>print()</c> with one input <c>5</c>.
    </p>
    <p>
      Line 2: We provide no inputs, so <c>print()</c> outputs an empty line into the terminal.
    </p>
    <p>
      Line 3: We give it two integer inputs <c>2</c> and <c>-2</c>.
    </p>
    <p>
      Line 4: We give it multiple inputs of different data types.
    </p>
  </investigation>

  <p>
    Another example is <c>len()</c>, which accepts exactly one input that is a data structure, and it returns the number of elements.
  </p>

  <aside>
    <title>Try It Out</title>
    
    <p>
      Does <c>len()</c> work with a string?
    </p> 
  </aside>

  <sage language="python">
    <input>
      arr = [1, 2, 3, 4]
      print(len(arr))
    </input>
  </sage>
  <problem>
    <pre>
      4
    </pre>
  </problem>
  <investigation>
    <idx><h>Code examples</h><h>function len()</h></idx>
    <idx><h>Functions</h><h>len()</h></idx>
    <p>
      The function <c>len()</c> receives one input and returns the number of elements.
    </p>
  </investigation>
  
  <p>
    So, <c>len()</c> has more specifications than <c>print()</c>. You have to call it with exactly one input, which must be a data structure. The following examples will return errors:
  </p>

  <aside>
    <title>Try It Out</title>
    
    <p>
      Can you fix this example?
    </p>
  </aside>

  <sage language="python">
    <input>
      arr1 = [1, 2, 3]
      arr2 = [4, 5, 6]
      print(len(arr1, arr2))
    </input>
  </sage>
  <problem>
    <pre>
      TypeError
      Cell In [1], line 3

      ...

      TypeError: len() takes exactly one argument (2 given)
    </pre>
  </problem>
  <investigation>
    <idx><h>Code examples</h><h>function len()</h></idx>
    <idx><h>Functions</h><h>len()</h></idx>
    <p></p>
    <p>The function <c>len()</c> accepts exactly one input, but two parameters were given.</p>
  </investigation>

  <p>
    Another example:
  </p>

  <sage language="python">
    <input>
      a = 5
      print(len(a))
    </input>
  </sage>
  <problem>
    <pre>
      TypeError
      Cell In [1], line 2

      ...

      TypeError: object of type 'int' has no len()
    </pre>
  </problem>
  <investigation>
    <idx><h>Code examples</h><h>function len()</h></idx>
    <idx><h>Functions</h><h>len()</h></idx>
    <p></p>
    <p>
      The input of <c>len()</c> must be a data structure, but we are calling it with an <c>int</c>.
    </p>
  </investigation>

  <p>
    Our final example is <c>upper()</c>, which follows the second <xref ref="syntax-call-function" text="custom">syntax</xref> for calling a function. In this case, <q>input 1</q> must be a string. And the function returns a new string with every character in uppercase.
  </p>

  <aside>
    <title>Try It Out</title>
    
    <p>
      Guess the function that turns a string to all lowercase.   
    </p>
  </aside>

  <sage language="python">
    <input>
      s = "Hello friend!" 

      print(s.upper())
    </input>
  </sage>
  <problem>
    <pre>
      HELLO FRIEND!
    </pre>
  </problem>
  <investigation>
    <idx><h>Code examples</h><h>function upper()</h></idx>
    <idx><h>Functions</h><h>upper()</h></idx>
    <p>The function <c>upper()</c> returns a new all-caps string.</p>
  </investigation>
 
  <p>
    The following produces an error:
  </p>

  <sage language="python">
    <input>
      a = 5 
      print(a.upper())
    </input>
  </sage>
  <problem>
    <pre>
      AttributeError
      Cell In [1], line 2

      ...

      AttributeError: 'int' object has no attribute 'upper'
    </pre>
  </problem>
  <investigation>
    <idx><h>Code examples</h><h>function upper()</h></idx>
    <idx><h>Functions</h><h>upper()</h></idx>
    <p></p>
    <p>
      The function <c>upper()</c> accepts exactly one input of type <c>str</c>, but we are giving it an <c>int</c>.
    </p>
  </investigation>

  <p>
    <cd>
    </cd>
  </p>

  <exploration>
    <title>Basic Programming <mdash /> Part 10: Functions</title>
    <idx><h>Videos</h><h>part 10</h></idx>
  
    <p>
      Coming soon.
    </p>
    
    <video youtubeplaylist="PLBLdRr-v59vwnKvmvLtcgmAnsb2K1Ta_M" />
    
  </exploration>

</section>