Aim for FiveComputer Science Principles

Unit 3 · Topic 3.14

3.14 Libraries

A software library is a collection of procedures someone else has already written and tested. This topic covers how libraries and APIs let you build complex programs quickly, and why reading the documentation is the key to using them.

Key terms

  • software library
  • API (application program interface)
  • documentation
  • reusing code

Libraries

A software library contains procedures you can use when writing new programs. Libraries exist for almost anything: drawing graphics, playing sounds, doing advanced math, reading maps or talking to a website.

Existing code can come from outside sources, like a published library, or from inside your own work, like a procedure you wrote for an earlier project.

Libraries make complex programs far simpler to create. Instead of figuring out how to draw a circle pixel by pixel, you call a drawing library's circle procedure and move on to the part that's actually new.

APIs and documentation

An API (application program interface) is the specification for how a library's procedures behave and how to use them: their names, the parameters each one takes, what it returns and what it does.

Documentation for an API explains all of that in words, often with examples. You need it to use a library correctly, because you usually never see the library's code. This is procedural abstraction again: you use the procedures by knowing what they do, not how.

Web APIs work the same way. A weather app might call a weather service's API with a city name and get back the forecast, without knowing how the service stores its data.

Good documentation is what makes a library usable by strangers. Without it, you'd have to read and understand the library's code yourself, which would cancel out most of the time you saved.

What to look for in documentation

When you pick a library procedure, check its documentation for:

  • Its name and what it does, in plain words.
  • Its parameters: how many, in what order, and what kind of value each one expects (a number, a string, a list).
  • What it returns, if anything, or what it changes.
  • Special cases: what happens with an empty list, a negative number or a missing value.

Reuse, with credit

If the procedure does exactly what you need, using it saves time and avoids bugs. If it's close but not quite right, you may be able to combine it with your own code, the same way you build new algorithms from existing ones (3.9).

For the Create task, code from a library, an API example or any other outside source must be acknowledged, and you must add new functionality of your own. Library procedures don't count as your student-developed procedure.

Worked examples

Try each one yourself first, then open the solution.

  1. Example 1

    Using a procedure from its documentation

    A math library's documentation says: roundTo(x, places) returns x rounded to the given number of decimal places. What does this display?prices ← [2.499, 10.126] FOR EACH p IN prices { DISPLAY(roundTo(p, 2)) }

    Show the solution
    1. Step 1: You don't need the library's code, only the documentation.
    2. Step 2: roundTo(2.499, 2): rounded to two decimal places, 2.499 becomes 2.50, which is the number 2.5.
    3. Step 3: roundTo(10.126, 2): 10.126 becomes 10.13.

    Answer: 2.5 10.13

  2. Example 2

    Why use a library?

    A student building a map app needs to find the distance between two points on Earth's surface. A free, well-documented geography library includes a distance procedure that does this. Give two reasons to use it rather than writing her own.

    Show the solution
    1. Step 1: It saves time: the formula is complicated, and the library already has it written.
    2. Step 2: It's already tested by many users, so it's less likely to have errors than brand-new code, and any bugs she does find are probably in her own new code.
    3. Step 3: She can focus on what's new about her app, as long as she reads the documentation to use it correctly and credits the library.

    Answer: It saves development time and is already tested, so the program is quicker to build and less likely to have errors.

Common mistakes

  • Saying an API is the library's code. It's the specification of how the procedures behave and how to call them; the documentation describes it.
  • Calling a library procedure without checking its documentation for the parameter order or what it returns.
  • Forgetting to acknowledge library or outside code in a Create task program.

On the exam

  • Questions may describe a library procedure in words and ask what a call returns, or which procedure fits a task. Trust the description given, and read it closely.
  • Expect questions on the benefits of libraries: less development time, already tested code, and simpler programs.

Connected topics

Videos

Check yourself

3 questions on 3.14 Libraries. Pick an answer to see if you got it, and why.

Question 1 of 3

A programmer wants to use a procedure from a weather library in her app. What should she rely on to learn what the procedure does, which arguments it needs and what it returns?

Question 2 of 3

A math library includes the procedure clamp(value, low, high). Its documentation says: returns low if value is less than low, returns high if value is greater than high, and otherwise returns value. What is displayed by the following statement? DISPLAY(clamp(15, 0, 10) + clamp(-3, 0, 10) + clamp(7, 0, 10))

Question 3 of 3

Which of the following is the best reason for a programmer to use procedures from a well-tested software library?

0 of 3 answered