AutosarC++17_10-A8.4.4

Multiple output values from a function should be returned as a struct or tuple

Required inputs: IR

Rationale

Returning multiple values from a function using a struct or tuple clearly states output parameters and allows to avoid confusion of passing them as a reference in a function call. Returning a struct or tuple will not have an additional overhead for compilers that support return-value-optimization.

In C++14, a returned tuple can be conveniently processed using std::tie at the call site, which will put the tuple elements directly into existing local variables. In C++17, structured bindings allow to initialize local variables directly from members or elements of a returned struct or tuple.

Note: For return types representing an abstraction, a struct should be preferred over a generic tuple.

Note: This rule applies equally to std::pair, which is a special kind of tuple for exactly two elements.

Example
// $Id: A8-4-4.cpp 289816 2017-10-06 11:19:42Z michal.szczepankiewicz $

#include <tuple>

// Non-compliant, remainder returned as the output parameter
int Divide1(int dividend, int divisor, int &remainder) {
  remainder = dividend % divisor;
  return dividend / divisor;
}

// Compliant, both quotient and remainder returned as a tuple
std::tuple<int, int> Divide2(int dividend, int divisor) {
  return std::make_tuple(dividend / divisor, dividend % divisor);
}

// Compliant since C++17, return tuple using list-initialization
// std::tuple<int, int> Divide3(int dividend, int divisor)
//{
//       return { dividend / divisor, dividend % divisor };
//}

int main() {
  int quotient, remainder;
  std::tie(quotient, remainder) = Divide2(26, 5); // store in local variables
  // auto [quotient, remainder] = Divide3(26, 5); // since C++17, by
  // structured bindings
  return 0;
}
See Also
  • C++ Core Guidelines [10]: F.21: To return multiple ”out” values, prefer returning a tuple or struct.

Possible Messages

Key

Text

Severity

Disabled

output_parameter

Use return value instead of output parameter.

None

False

Options

allow_in_out_parameters

allow_in_out_parameters : bool = False

Whether parameters used as in-out parameters rather than purely output parameters should be allowed.
 

allow_modifying_calls

allow_modifying_calls : bool = True

Whether a function may call a function on a parameter that modifies it, without regarding it as a violation here.
 

allow_move_parameters

allow_move_parameters : bool = True

Whether a move parameter (a rvalue reference) may be written to without triggering a violation.

Note: move-constructors and move-assignments are allowed in either case.

 

allow_this_modification

allow_this_modification : bool = True

Whether a function may call a member-function on a parameter that modifies this, that is the internal parameter state (allow_modifying_calls must be false if this is set to false).
 

exclude_constructors

exclude_constructors : bool = True

Whether not to report parameters on constructors.
 

exclude_operators

exclude_operators : bool = False

Whether not to report parameters on operator functions.

Note: if set to true, this also sets exclude_shift_operators to true.

 

exclude_shift_operators

exclude_shift_operators : bool = False

Whether not to report parameters on shift operator functions (operator<<(), operator<<=(), operator>>(), and operator>>=()).
 

only_report_multiple_output_parameters

only_report_multiple_output_parameters : bool = True

Whether to only report output-parameters, if a function has more than one or also returns a value.
 

record_field_modification_threshold

record_field_modification_threshold : int = 0

A percentage of how many record fields may be modified, before the record pointer is considered an output parameter:

0 : every field modification counts as an output parameter
100: the record pointer is only regarded an output parameter if all field are modified