# C++ named requirements: FormattedOutputFunction

> C++ Atlas: `cppatlas.com/w/cpp/named_req/FormattedOutputFunction` | Source: https://en.cppreference.com/w/cpp/named_req/FormattedOutputFunction | Domain: Named Requirements | Standards: C++14, C++17, C++23

A FormattedOutputFunction is a stream output function that performs the following:

## Official Specification Summary (cppreference)

### Requirements

A *FormattedOutputFunction* is a stream output function that performs the following:

- Constructs an object of type `basic_ostream::sentry` with automatic storage duration, which performs the following:

  - if `eofbit` or `badbit` are set on the output stream, sets the `failbit` as well, and if exceptions on `failbit` are enabled in this output stream's exception mask (`(exceptions() & failbit) != 0`), throws `ios_base::failure`.
  - flushes the tie()'d output stream, if applicable.

- Checks the status of the sentry by calling `sentry::operator bool()`, which is equivalent to `basic_ios::good`.
- If the sentry returned `false` or sentry's constructor threw an exception, no output takes place.
- If the sentry returned `true`, attempts to perform the desired output by inserting the characters into the output stream as if by calling `rdbuf()->sputc()`. Other public members of `std::basic_ostream` may also be used, but virtual members of `rdbuf()` except `overflow()`, `xsputn()` and `sync()` will never be called.

  - If the output could not be generated, sets `failbit`. If exceptions on `failbit` are enabled in this stream's exception mask (`(exceptions() & failbit) != 0`), throws `ios_base::failure`.
  - if an exception is thrown during output, sets `badbit` in the output stream. If exceptions on `badbit` are enabled in this stream's exception mask (`(exceptions() & badbit) != 0`), the exception is also rethrown.
  - If no exception was thrown, returns `*this`.

- In any event, whether terminating by exception or returning, the sentry's destructor is called before leaving this function.

### Padding

Formatted output functions determine padding according to `std::num_put::do_put()` stage 3. (until C++14)

(since C++14):

If a formatted output function of a stream `os` determines padding, it does so as follows.

Given a `CharT` character sequence `seq` where `CharT` is the character container type of `os`, if the length of `seq` is less than `os.width()`, then enough copies of `os.fill()` are added to this sequence as necessary to pad to a width of `os.width()` characters.

If `(os.flags() & std::ios_base::adjustfield) == std::ios_base::left` is `true`, the fill characters are placed after the character sequence; otherwise, they are placed before the character sequence.

### Standard library

The following standard library functions are *FormattedOutputFunction*s.

- `basic_ostream::operator<<(std::basic_ostream&, int / long / double / void* / bool)`
- `operator<<(std::basic_ostream&, char)`
- `operator<<(std::basic_ostream&, char*)`
- `operator<<(std::basic_ostream&, const std::bitset&)`
- `operator<<(std::basic_ostream&, const std::basic_string&)`
- `operator<<`, when called on the return value of `std::put_money`

(since C++17):

- `operator<<(std::basic_ostream&, std::basic_string_view)`

(since C++23):

- `print(std::ostream&, std::format_string<Args...>, Args&&...)`,
- `println(std::ostream&, std::format_string<Args...>, Args&&...)`,
- `vprint_unicode(std::ostream&, std::string_view, std::format_args)`,
- `vprint_nonunicode(std::ostream&, std::string_view, std::format_args)`,

  except that (given `os` is an output stream object):

  - any exception thrown by the call to `std::vformat` is propagated without regard to the value of `os.exceptions()` and without turning on `ios_base::badbit` in the error state of `os`;
  - if inserting into `os` fails, calls `os.setstate(ios_base::badbit)` (which may throw `ios_base::failure`).

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 160 | C++98 | the process of determining whether the exception caught is rethrown mentioned a non-existing function `exception()` | corrected to `exceptions()` |
| LWG 165 | C++98 | the only virtual member allowed to be called on `rdbuf()` was `overflow()` | also allowed `xsputn()` and `sync()` |

---
Attribution: content from https://en.cppreference.com/w/cpp/named_req/FormattedOutputFunction (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.