C++ Usage

The C++ API is the native API for VXSDR radios; it is documented in detail in the API Reference section below. The API is intended to use modern C++ features (C++11 and later) where the are useful, and currently requires a compiler supporting the C++20 standard. However, only a few C++20 features are currently used, and the partial support offered by gcc since at least version 9.4 is sufficient.

The std::optional template class from C++17 is heavily used in the API to carry results from functions that usually return a value, but may rarely fail. For example, the get_rx_freq function returns a std::optional<double>.

For those who are unfamiliar with std::optional, it provides a uniform alternative to the use of a “flag” value to indicate an error return. For example, an old-fashioned C or C++ interface might use a negative result from get_rx_freq to indicate an error:

double freq = radio->get_rx_freq_old();
if (freq >= 0.0) {
    // use the result
    do_something(freq);
} else {
    // error occurred
}

One difficulty with this approach is that the appropriate “flag” value can be different for different functions, so each function needs to choose and document its error “flag” value.

The VXSDR API uses std::optional, which removes the need for a “flag” value, and works in the same way for all return types:

// returns a std::optional<double>
auto result = radio->get_rx_freq();
// all std::optionals evaluate to true if the function succeeds
if (result) {
    // use the result
    do_something(result.value());
} else {
    // error occurred
}

For those nostalgic for earlier idioms, it’s possible to use the value_or() member of std::optional to emulate the old style:

double freq = radio->get_rx_freq().value_or(-1.0);
if (freq >= 0.0) {
    // use the result
    do_something(freq);
} else {
    // error occurred
}

We recommend using the modern approach; std::optional is not perfect, but it does provide a uniform way of handling errors without worrying about keeping track of which “flag” value applies to each function.