Libraries: Study Guide (Computer Science Principles 3.14)

Nobody writes every part of a program from scratch. A mapping app does not invent the maths for distances, a game does not build its own sound engine, and a school project does not write its own code for reading a date. Programmers use libraries: collections of procedures that other people have already written and tested. This topic explains what a library and an API are, why documentation is essential, and how to choose and use existing code sensibly. The skill is practical: given a description of what a library procedure does, you must be able to use it correctly and predict what it returns.

Notation. The exam uses its own pseudocode, not a real programming language. The code in this pack is Marlbridge’s rendering of that reference notation, not a copy of the official sheet: ← is assignment, = tests equality, lists start at index 1, DISPLAY shows a value, and braces mark blocks. Use the Exam Reference Sheet from your teacher for the official wording.

Libraries, APIs and documentation

A software library contains procedures that may be used in creating new programs. Libraries simplify the task of creating complex programs: you call a ready-made procedure instead of building and testing it yourself.

Existing code can come from internal or external sources: a library supplied with the language or written by someone else (external), or code you or your team wrote earlier (internal, “previously written code”). Using it saves time and benefits from testing that has already been done.

An application program interface (API) is a specification of how the procedures in a library behave and how they can be used. It describes each procedure’s name, its parameters, what it returns, and any conditions that must hold. Documentation for an API or library is necessary to understand the behaviours it provides and how to use them. You cannot safely call a procedure whose behaviour you have not read: you do not see its code, only its description.

Notice how this follows from procedural abstraction (Topic 3.13). The library author hides how each procedure works; the API tells you what it does. Your program depends only on that promise.

An example API: NumberKit

The exam will describe any library it uses. To practise, here is a fictional library, NumberKit, invented by Marlbridge for this guide. Its documentation is:

Procedure	Parameters	Returns	Conditions
clamp(value, low, high)	three numbers	low if value < low; high if value > high; otherwise value	low ≤ high
largest(aList)	a list of numbers	the largest value in the list	list is not empty
average(aList)	a list of numbers	the mean of the values	list is not empty
repeatText(text, times)	a string and a whole number	the string joined to itself times times	times ≥ 1

Worked example 1: predicting results from documentation

Use only the NumberKit documentation above. Find what this program displays.

DISPLAY(clamp(15, 0, 10))
DISPLAY(clamp(-3, 0, 10))
DISPLAY(clamp(7, 0, 10))
DISPLAY(clamp(largest([4, 17, 9]) - 10, 0, 5))

Output: 10 0 7 5

Call	Working from the documentation	Returns
clamp(15, 0, 10)	15 > high (10), so return high	10
clamp(-3, 0, 10)	−3 < low (0), so return low	0
clamp(7, 0, 10)	between low and high, so return value	7
clamp(largest([4, 17, 9]) - 10, 0, 5)	largest returns 17; the argument is 17 − 10 = 7; 7 > high (5), so return high	5

Check. The last line shows that a call can be an argument to another call; the inner one runs first. Never assume more than the documentation promises: it does not say that clamp changes the original variable, so it returns a new value that you must store if you need it.

A real use: keeping a value in range. A volume control must stay between 0 and 10 whatever the user presses:

level ← 9
step ← 3
level ← clamp(level + step, 0, 10)
DISPLAY(level)

Output: 10

Without the library you would write the two-IF logic yourself and test it. With clamp the intent is clear in one line.

Worked example 2: reading the conditions in the documentation

The table says average(aList) needs a non-empty list. A program collects test marks and must show the class average. Some days no one sits the test, so the list is empty. If the program called average([]) it would break the documented condition, and the behaviour would be undefined (it could crash). A careful programmer protects the call:

marks ← [8, 6, 10, 4]
IF(LENGTH(marks) > 0)
{
  DISPLAY(average(marks))
}
ELSE
{
  DISPLAY("no marks")
}

Output: 7

marks ← []
IF(LENGTH(marks) > 0)
{
  DISPLAY(average(marks))
}
ELSE
{
  DISPLAY("no marks")
}

Output: no marks

Step 1. With four marks, LENGTH(marks) is 4, so the condition is true and average returns (8 + 6 + 10 + 4) / 4 = 28 / 4 = 7.

Step 2. With an empty list, LENGTH(marks) is 0, the condition is false and the message is displayed. The library procedure is never called with a list it cannot handle.

Step 3. Decide whether to use the library or write your own. Consider:

Question	Using average	Writing your own loop
Time to develop	One line	Several lines
Testing needed	Only your use of it	Whole procedure
Risk	Must respect the conditions	Must write correct code
Readability	Clear name	Needs reading the loop

For a routine task like an average, the library wins on time and clarity. If no library did exactly what you need, you would write your own procedure (Topic 3.13), or combine library procedures with your own code.

Choosing an appropriate library

When you need to add a feature, ask:

1. Does a library already do this? Dates, graphics, sound, statistics and file handling are all well served.
2. Does its API fit? Check the parameters, the return value and the conditions.
3. Can I trust and maintain it? Prefer widely used libraries with clear documentation. Check any usage terms, which you will meet again under legal and ethical concerns.
4. Is it more than I need? Pulling in a very large library for one tiny task can be wasteful.

Using libraries also changes how you test: you must still test your use of the library, including boundary cases and the documented conditions, even though you do not test the library’s internal code.

Common misconceptions

• “I need to see a library’s code to use it.” You need its documentation. The code is hidden behind the API.
• “A library procedure always works for any input.” Documentation lists conditions (such as a non-empty list). Breaking them can cause errors.
• “An API is a program.” An API is a specification of how to use a library’s procedures.
• “Using a library means my program needs no testing.” You must still test your use of it.
• “Existing code can only come from other people.” It can also be your own earlier code.
• “Libraries make programs faster by definition.” They make development faster and often more reliable; speed of running depends on the code.

Where this leads

Libraries are what make random numbers possible in Topic 3.15, where RANDOM(a, b) is a ready-made procedure you call without knowing how it generates values, and simulations in Topic 3.16 depend on such libraries.

Next steps: try the practice questions, skim the revision notes the night before, and tick off the topic checklist. The next topic is Topic 3.15, Random Values.