Explore functions

Now that you have started with procedures we can move on to explore functions. These are just like procedures, but return a value and can therefor be used in expressions. As with procedures, let’s build some small utilities that may be useful elsewhere, and create a test programs to explore how they work.

Tip

This is a great way to learn new things in programming. Building a small test program lets you play around with new ideas, tools, libraries, and approaches.

Read String

In our previous programs we have often needed to read text from the user in our terminal programs. The code would have looked something like this:

  // Read in a string and store it in name (a string variable)
  write("enter your name: ");
  name = read_line();

While it is only a couple of lines, we will want to make use of this in many places as we interact with the user. Creating a function to do this for us will save us effort in the long run, and will give us a nice little utility that we can make use of. To build this we need to think about the function in general.

What do we want it to do?

What information can we pass it so that it is usable in as many places as possible.

We could create a function to read in the user’s name, but we will also want to be able to read in other values. So we could add a parameter to the function, so that the caller can pass in the message they want shown. We can then return the value read by read_line so that the caller can store it where ever they want. This gives us the following as our specification for this function:

Function	Read String
Parameters	prompt: The message to show to the user
Returns	The string entered at the Terminal
Description	Displays a prompt, reads the string entered at the terminal, and returns this string to the caller. This can be used to read values from the user.

Specification for the read string function

Write the Code and Test

Let’s write the code for this now. Here is a good start at the test program:

#include "splashkit.h"

// Add read string code here

int main()
{
  string name;

  // Read in a string and store it in name
  name = read_string("enter your name: ");

  // Output the name
  write_line("Hello " + name);

  return 0;
}

• Code For Read String

  /**
   * Displays a prompt, reads the string entered at the terminal, and
   * returns this string to the caller. This can be used to read values
   * from the user.
   *
   * @param prompt The message to show to the user
   * @returns The string entered at the terminal
   */
  string read_string(string prompt)
  {
    write(prompt);
    return read_line();
  }

Read Integer

Looking at other terminal input in our programs we also have places where we want to read integer values from the user. For example, the following code was in our change calculator program. We can simplify this a little by using our read_string function, but we could further refine this by creating a read_integer function that performs this validation as well.

    write("Cost of item in cents: ");
    line = read_line();
    while ( ! is_integer(line) )
    {
      write_line("Please enter a whole number.");
      write("Cost of item in cents: ");
      line = read_line();
    }
    int cost_of_item = stoi(line);

The following table captures our specification for the read integer function. As with read string, we can accept a prompt parameter to allow this to be used in different situations.

Function	Read Integer
Parameters	prompt: The message to show to the user
Returns	The integer entered at the Terminal
Description	Displays a prompt, reads the string entered, safely converts this to an integer, and returns the value. This will display error messages when there is invalid input, and will ask the user to enter again.

Specification for the read integer function

We can test this out by extending our program to read in an integer. Have a go at coding the read integer function and test this out.

#include "splashkit.h"

using std::to_string;
using std::stoi;

// Add read string code here

// Add read integer code here

int main()
{
  string name;
  int age;

  // Read in a string and store it in name
  name = read_string("enter your name: ");

  // Output the name
  write_line("Hello " + name);

  // Read in an integer
  age = read_integer("what is your age: ");

  write_line("You entered " + to_string(age));

  return 0;
}

• Code For Read Integer

  /**
   * Read an integer from the user
   *
   * @param prompt the message to show the user
   * @returns the integer entered
   */
  int read_integer(string prompt)
  {
    string input = read_string(prompt);
    while (!is_integer(input))
    {
      write_line("Please enter a whole number.");
      input = read_string(prompt);
    }
    return stoi(input);
  }

Read Integer - with a range

Thinking about this further, we could also create a function that allows us to read an integer within a given range. For example, reading an integer between 1 and 10. This will be particularly useful when we create something like a menu where they need to choose one of the menu options.

Have a go at thinking about the specification for this, and then code this up and extend your test program to check that it works.

• Code For Read Integer Range

  I used the following to test out this function:

  #include "splashkit.h"
  
  using std::to_string;
  
  // Add read string code here
  
  // Add read integer code here
  
  // Add read integer code here with the range
  
  int main()
  {
    string name;
    int age, value;
  
    // Read in a string and store it in name
    name = read_string("enter your name: ");
  
    // Output the name
    write_line("Hello " + name);
  
    // Read in an integer
    age = read_integer("what is your age: ");
  
    write_line("You entered " + to_string(age));
  
    // Read in an integer within a range
    value = read_integer("Enter a value between 1 and 10: ", 1, 10);
    write_line("You entered " + to_string(value));
  
    return 0;
  }

  Here is the specification that I used for this function. I decided to overload read integer - providing two versions, one that can be called with just the prompt and another with the prompt and a range.

  Function	Read Integer
  Parameters	prompt: The message to show to the user
  	low: An integer representing the smallest value to return
  	high: An integer representing the largest value to return
  Returns	The integer entered at the Terminal - this will be between low and high (inclusive)
  Description	Displays a prompt, reads the string entered, safely converts this to an integer and ensure this is within the range indicated, and returns the value. This will display error messages when there is invalid input, and will ask the user to enter again.

  Specification for the read integer function that accepts a range

  The code for read integer with a range is shown below.

  /**
   * Read an integer from the user within a given range.
   *
   * @param prompt the message to show the user
   * @param low An integer representing the smallest value to return
   * @param high An integer representing the largest value to return
   * @returns the integer entered
   */
  int read_integer(string prompt, int low, int high)
  {
    int input = read_integer(prompt);
    while (input < low || input > high)
    {
      write_line("Please enter a value between " + to_string(low) + " " + to_string(high));
      input = read_integer(prompt);
    }
    return input;
  }

  Caution

  What happens when the programmer asks to read a value between 10 and 1 rather than between 1 and 10? Can you fix this bug?

Try testing this out by entering text instead of numbers, as well as entering values outside the requested range. Think about where these things are being checked, and what code is validating this data entry.

Test it out

See if you can create an equivalent set of function to read in double values. Remember to test out each of these as you add them. This will provide you with a useful set of functions to handle terminal a range of input scenarios.