Recap
- A software library contains procedures that can be used in new programs.
- An API is a specification of how the library’s procedures behave and are used.
- Documentation is necessary: the library code is usually hidden.
- Existing code can be internal (your earlier code) or external (a library).
- Libraries simplify complex programs, saving development time and testing.
- Always check the conditions in the documentation (for example “list not empty”).
Key relationships
| Term | Meaning | Example |
|---|---|---|
| Library | Collection of reusable procedures | NumberKit (fictional) |
| API | Specification of how to use them | clamp(value, low, high) returns … |
| Documentation | Description you read to use the API | Parameters, return value, conditions |
| Internal code | Your own earlier code | A grade procedure from last project |
| External code | Written by others | A graphics library |
| Condition | What must hold when calling | list is not empty |
Assumptions
- Questions give you the documentation; use only what it says.
- Library procedures are correct if used as documented.
- Calls inside calls are evaluated from the inside out.
Method for using a library procedure
- Read the documentation: name, parameters, return value, conditions.
- Check that your arguments meet the conditions (guard with an IF if needed).
- Store or use the returned value; the original data is not changed unless stated.
- Test your call with typical, boundary and special inputs.
Mistakes to avoid
- Assuming a procedure does more than the documentation says.
- Ignoring a documented condition.
- Forgetting to store the returned value.
- Believing the API is the code itself.
- Skipping testing because the library is “trusted”.
Worked mini-example
DISPLAY(clamp(-8, 0, 100))
DISPLAY(clamp(250, 0, 100))
DISPLAY(clamp(40, 0, 100))Output: 0 100 40
The first value is below low, so low (0) is returned; the second is above high, so high (100) is returned; the third lies between them and is returned unchanged.
Quick self-check
- What does an API tell you?
- Why might
average([])be unsafe, according to the NumberKit documentation? - Give one benefit of using a library.
Answers
- How the library’s procedures behave and how to use them: parameters, return values and conditions.
- The documentation says the list must not be empty, so an empty list breaks the condition.
- Any one: saves development time; reduces testing; simplifies complex programs.
Where marks are won and lost
Questions describe a library or give a short API listing and ask what a call returns, or which library procedure would solve a stated problem. Others ask why documentation is needed or what benefit a library gives. Use only the information given, respect stated conditions, and evaluate inner calls first. In the Create task, you may use code from a library but must identify code that is not your own in your written responses and show what you personally developed.
Back to the full study guide for worked examples and explanations.