API Reference

API Reference

Steppable has an API in C++ and Python. This document briefly describes how to use the API.

C++ API

You may use the API by adding a new component.

To add a new feature, a:

1. Add a directory called src/origin/a in the Steppable directory, with at least three files:

   • a.cpp - The main file. The main function should be present, as it is the entry point of the executable.
   • aReport.cpp - The report file to show the results.
   • aReport.hpp - A header that contains optional definition.

Note

The origin is the class where the component should belong to. Currently, there are three classes:

• base - Base conversion tools.
• calc - Including arithmetic, trigonometry and more. Excluding calculus and symbolic math.
• calculus - Calculus functions, including integrals and derivatives. Decide carefully the origin of your component.

Important

• Only the above-mentioned three files will be added to CMake.
• Do not omit the report files, even if the program does not produce step-by-step output. You should either leave it blank, or add a comment saying that the file is not used.

2. Make sure to document the code. Please use Doxygen to document this project.

3. Add an entry to CMakeLists.txt at the root of the repository.

   set(COMPONENTS
       calc::add
       ...
       origin::a # Replace with yours
   )

Using the Header Files

You may include the Steppable header files. They are:

• argParse.hpp - Argument parsing for executable files.
• colors.hpp - Printing with colors, or with custom formats.
• constants.hpp - Constants, e.g., $\pi$, $\displaystyle\frac{\pi}2$.
• exceptions.hpp - Exceptions to throw in case of error.
• fn/calc.hpp - Basic arithmetic.
• fn/calculus.hpp - Calculus functions.
• fn/root.hpp - types used by root.
• types/result.hpp - Types representing a result.
• format.hpp - String formatting.
• fraction.hpp - Fractions in Steppable.
• logging.hpp - Log file creation and management.
• number.hpp - Numbers in Steppable.
• output.hpp - Console logging utilities.
• platform.hpp - Platform-specific functions.
• rounding.hpp - Round off numbers.
• symbols.hpp - Mathematical symbols.
• testing.hpp - Unit testing utilities.
• util.hpp - Useful utilities for string manipulation, numbers, etc.

Using the Namespaces

The symbols are sometimes inside namespaces. They are:

• namespace steppable::__internals::arithmetic - Arithmetic functions.
• namespace steppable::__internals::calculus - Calculus functions.
• namespace steppable::__internals::format - Text formatting.
• namespace steppable::__internals::logging - Log file creation and management.
• namespace steppable::__internals::numUtils - Number manipulation utilities.
• namespace steppable::__internals::stringUtils - String manipulation utilities.
• namespace steppable::__internals::symbols - Mathematical symbols.
• namespace steppable::__internals::utils - Utility functions.
• namespace steppable::exceptions - Exceptions.
• namespace steppable::output - Console logging utilities.
• namespace steppable::testing - Unit testing utilities.
• namespace steppable - Root namespace. Public Methods are here.

Tip

The __internals part of the namespace does not indicate that you cannot use it in public code. Instead, it means that the functions in the namespace should not be called directly from any user interface, in production code. For example, steppable::__internals::add should only be called by other components, but the user cannot directly interact with it (if STP_BUILD_COMPONENT_EXECUTABLE is turned off).

Using the Library

In namespace steppable, there are two classes, and one enum.

• class Number - Steppable number. It can be added, subtracted, multiplied, divided, etc. For more information, see the documentation for this.
• class Fraction - Steppable fraction. It also supports multiply arithmetic operators. For more information, see the documentation for this.
• enum RoundingMode - Specifies how the result should be rounded.

In namespace steppable::__internals::arithmetic, there is one class and several methods.

• struct QuotientRemainder - A struct representing the result and remainder from a division operation. For more information, see the documentation for this.
• For the other methods, refer to the documentation.

Python API

The Python library is created using nanobind. You need to create the library on the same platform and using the same version of Python.

You may import the library as follows:

>>> import steppyble

Available Classes

There are three available classes.

• class Number - Steppable number. It can be added, subtracted, multiplied, divided, etc. Operators are overloaded, same as in C++.
• class Fraction - Steppable fraction. It also supports multiply arithmetic operators. Operators are overloaded, same as in C++.
• enum RoundingMode - Specifies how the result should be rounded.