cppdraft_translate/cppdraft/print/fun.md

[print.fun]

# 31 Input/output library [[input.output]](./#input.output)

## 31.7 Formatting and manipulators [[iostream.format]](iostream.format#print.fun)

### 31.7.10 Print functions [print.fun]

[🔗](#lib:print)

`template<class... Args>
  void print(format_string<Args...> fmt, Args&&... args);
`

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7716)

*Effects*: Equivalent to:print(stdout, fmt, std::forward<Args>(args)...);

[🔗](#lib:print_)

`template<class... Args>
  void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
`

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7731)

*Effects*: Let locksafe be(enable_nonlocking_formatter_optimization<remove_cvref_t<Args>> && ...)[.](#2.sentence-1)

If the ordinary literal encoding ([[lex.charset]](lex.charset "5.3.1 Character sets")) is UTF-8, equivalent to:locksafe ? vprint_unicode(stream, fmt.str, make_format_args(args...)): vprint_unicode_buffered(stream, fmt.str, make_format_args(args...));

Otherwise, equivalent to:locksafe ? vprint_nonunicode(stream, fmt.str, make_format_args(args...)): vprint_nonunicode_buffered(stream, fmt.str, make_format_args(args...));

[🔗](#lib:println)

`template<class... Args>
  void println(format_string<Args...> fmt, Args&&... args);
`

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7756)

*Effects*: Equivalent to:println(stdout, fmt, std::forward<Args>(args)...);

[🔗](#lib:println_)

`void println();
`

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7770)

*Effects*: Equivalent to:println(stdout);

[🔗](#lib:println__)

`template<class... Args>
  void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
`

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7785)

*Effects*: Equivalent to:print(stream, runtime_format(string(fmt.get()) + '\n'), std::forward<Args>(args)...);

[🔗](#lib:println___)

`void println(FILE* stream);
`

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7799)

*Effects*: Equivalent to:print(stream, "\n");

[🔗](#lib:vprint_unicode)

`void vprint_unicode(string_view fmt, format_args args);
`

[7](#7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7813)

*Effects*: Equivalent to:vprint_unicode(stdout, fmt, args);

[🔗](#lib:vprint_unicode_buffered)

`void vprint_unicode_buffered(FILE* stream, string_view fmt, format_args args);
`

[8](#8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7827)

*Effects*: Equivalent to:string out = vformat(fmt, args);
vprint_unicode(stream, "{}", make_format_args(out));

[🔗](#lib:vprint_unicode_)

`void vprint_unicode(FILE* stream, string_view fmt, format_args args);
`

[9](#9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7842)

*Preconditions*: stream is a valid pointer to an output C stream[.](#9.sentence-1)

[10](#10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7846)

*Effects*: Locks stream[.](#10.sentence-1)

Let out denote the character representation of
formatting arguments provided by args formatted according to specifications given in fmt[.](#10.sentence-2)

- [(10.1)](#10.1)

  If stream refers to a terminal that
is capable of displaying Unicode only via a native Unicode API,
flushes stream and then
writes out to the terminal using the native Unicode API;
if out contains invalid code units,the behavior is undefined[.](#10.1.sentence-1)
  Then establishes an observable checkpoint ([[intro.abstract]](intro.abstract "4.1.2 Abstract machine"))[.](#10.1.sentence-2)

- [(10.2)](#10.2)

  Otherwise writes out to stream unchanged[.](#10.2.sentence-1)

Unconditionally unlocks stream on function exit[.](#10.sentence-3)

See also: ISO/IEC 9899:2024, 7.21.2[.](#10.sentence-4)

[*Note [1](#note-1)*:

On Windows the native Unicode API is WriteConsoleW andstream referring to a terminal means thatGetConsoleMode(_get_osfhandle(_fileno(stream)), ...) returns nonzero[.](#10.sentence-5)

— *end note*]

[11](#11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7876)

*Throws*: Any exception thrown by the call to vformat ([[format.err.report]](format.err.report "28.5.3 Error reporting"))[.](#11.sentence-1)

system_error if writing to the terminal or stream fails[.](#11.sentence-2)

May throw bad_alloc[.](#11.sentence-3)

[12](#12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7882)

*Recommended practice*: If invoking the native Unicode API requires transcoding,
implementations should substitute invalid code units
with U+fffd replacement character per
the Unicode Standard, Chapter 3.9 U+fffd Substitution in Conversion[.](#12.sentence-1)

[🔗](#lib:vprint_nonunicode)

`void vprint_nonunicode(string_view fmt, format_args args);
`

[13](#13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7896)

*Effects*: Equivalent to:vprint_nonunicode(stdout, fmt, args);

[🔗](#lib:vprint_nonunicode_buffered)

`void vprint_nonunicode_buffered(FILE* stream, string_view fmt, format_args args);
`

[14](#14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7910)

*Effects*: Equivalent to:string out = vformat(fmt, args);
vprint_nonunicode("{}", make_format_args(out));

[🔗](#lib:vprint_nonunicode_)

`void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
`

[15](#15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7925)

*Preconditions*: stream is a valid pointer to an output C stream[.](#15.sentence-1)

[16](#16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7929)

*Effects*: While holding the lock on stream,
writes the character representation of
formatting arguments provided by args formatted according to specifications given in fmt to stream[.](#16.sentence-1)

[17](#17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L7936)

*Throws*: Any exception thrown by the call to vformat ([[format.err.report]](format.err.report "28.5.3 Error reporting"))[.](#17.sentence-1)

system_error if writing to stream fails[.](#17.sentence-2)

May throw bad_alloc[.](#17.sentence-3)