Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/io/println"

From cppreference.com
< cpp‎ | io
m (wording)
m (+links to (3,4)
 
(11 intermediate revisions by 5 users not shown)
Line 4: Line 4:
 
{{dcl begin}}
 
{{dcl begin}}
 
{{dcl header|print}}
 
{{dcl header|print}}
−
{{dcl|num=1|since=c++23|1=
+
{{dcl|num=1|since=c++23|
 
template< class... Args >
 
template< class... Args >
−
  void println( std::FILE* stream,
+
void println( std::format_string<Args...> fmt, Args&&... args );
−
                std::format_string<Args...> fmt, Args&&... args );
+
 
}}
 
}}
−
{{dcl|num=2|since=c++23|1=
+
{{dcl|num=2|since=c++23|
 
template< class... Args >
 
template< class... Args >
−
  void println( std::format_string<Args...> fmt, Args&&... args );
+
void println( std::FILE* stream,
 +
              std::format_string<Args...> fmt, Args&&... args );
 +
}}
 +
{{dcla|num=3|since=c++26|
 +
void println();
 +
}}
 +
{{dcl|num=4|since=c++26|
 +
void println( std::FILE* stream );
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
  
−
Format {{tt|args}} according to the format string {{tt|fmt}} with appended {{c|'\n'}} (which means each output ends with new-line), and print the result to a stream.
+
Format {{c|args}} according to the format string {{c|fmt}} with appended {{c|'\n'}} (which means that each output ends with a new-line), and print the result to a stream.
  
−
@1@ Equivalent to:
+
@1@ Equivalent to {{c|std::println(stdout, fmt, std::forward<Args>(args)...)}}.
−
{{source|std::print(stream, "{}\n", std::format(fmt, std::forward<Args>(args)...));}}
+
  
−
@2@ same as {{v|1}} when {{c|stream}} is equal to the standard C output stream {{lc|stdout}}, i.e.
+
@2@ Equivalent to {{c multi|std::print(stream, std::runtime_format(std::string(fmt.get()) + '\n'),|          std::forward<Args>(args)...)}}.
−
{{source|std::println(stdout, fmt, std::forward<Args>(args)...);}}
+
  
−
The behavior is undefined if {{c|std::formatter<Ti, char>}} does not model {{tt<!--lconcept-->|std::formattable}} for any {{tt|Ti}} in {{tt|Args}} (as required by {{c|std::make_format_args}}).
+
@3@ Equivalent to {{c|std::println(stdout)}}.
 +
 
 +
@4@ Equivalent to {{c|std::print(stream, "\n")}}.
 +
 
 +
The behavior is undefined if {{c|std::formatter<Ti, char>}} does not meet the {{named req|BasicFormatter}} requirements for any {{tt|Ti}} in {{tt|Args}} (as required by {{c|std::make_format_args}}).
  
 
===Parameters===
 
===Parameters===
Line 31: Line 39:
 
{{par|args...|arguments to be formatted}}
 
{{par|args...|arguments to be formatted}}
 
{{par end}}
 
{{par end}}
−
 
−
===Return value===
 
−
(none)
 
  
 
===Exceptions===
 
===Exceptions===
Line 39: Line 44:
  
 
===Notes===
 
===Notes===
−
{{ftm begin|std=1|value=1}}
+
Although overloads {{vl|3,4}} are added in C++26, all known implementations make them available in C++23 mode.
−
{{ftm|std=C++23|value=202207L|__cpp_lib_print}}
+
 
−
{{ftm|std=C++23|value=202207L|__cpp_lib_format}}
+
{{ftm begin|std=1|value=1|comment=1}}
 +
{{ftm|__cpp_lib_print|Formatted output|value=202207L|std=C++23|rowspan=2}}
 +
{{ftm|-|Formatted output with stream locking|value=202403L|std=C++26|dr=23}}
 +
{{ftm|__cpp_lib_format|Exposing {{lc|std::basic_format_string}}|value=202207L|std=C++23}}
 
{{ftm end}}
 
{{ftm end}}
  
Line 52: Line 60:
 
{
 
{
 
     // Each call to std::println ends with new-line
 
     // Each call to std::println ends with new-line
−
     std::println("Please");
+
     std::println("Please"); // overload (1)
−
     std::println("enter");
+
     std::println("enter"); // (1)
−
 
+
   
 
     std::print("pass");
 
     std::print("pass");
 
     std::print("word");
 
     std::print("word");
−
 
+
   
−
     std::println(""); // same effect as std::print("\n");
+
     std::println(); // (3); valid since C++26; same effect as std::print("\n");  
 
}
 
}
 
|output=
 
|output=
Line 64: Line 72:
 
enter
 
enter
 
password
 
password
 +
 +
<nowiki/>
 
}}
 
}}
  

Latest revision as of 20:46, 17 May 2024

 
C++
 
Input/output library
 
Print functions
Print functions
(C++23)
println
(C++23)
(C++23)(C++23)
(C++23)(C++23)
 
Defined in header <print>
template< class... Args >
void println( std::format_string<Args...> fmt, Args&&... args );
 (1) (since C++23)
template< class... Args >

void println( std::FILE* stream,

              std::format_string<Args...> fmt, Args&&... args );
 (2) (since C++23)
void println();
 (3) (since C++26)
void println( std::FILE* stream );
 (4) (since C++26)

Format args according to the format string fmt with appended '\n' (which means that each output ends with a new-line), and print the result to a stream.

1) Equivalent to std::println(stdout, fmt, std::forward<Args>(args)...).
2) Equivalent to std::print(stream, std::runtime_format(std::string(fmt.get()) + '\n'),
           std::forward<Args>(args)...).
3) Equivalent to std::println(stdout).
4) Equivalent to std::print(stream, "\n").

The behavior is undefined if std::formatter<Ti, char> does not meet the BasicFormatter requirements for any Ti in Args (as required by std::make_format_args).

Contents

[edit] Parameters

stream - output file stream to write to
fmt -
[edit]
an object that represents the format string. The format string consists of
  • ordinary characters (except { and }), which are copied unchanged to the output,
  • escape sequences {{ and }}, which are replaced with { and } respectively in the output, and
  • replacement fields.

Each replacement field has the following format:

{ arg-id (optional) } (1)
{ arg-id (optional) : format-spec } (2)
1) replacement field without a format specification
2) replacement field with a format specification
arg-id - specifies the index of the argument in args whose value is to be used for formatting; if it is omitted, the arguments are used in order.

The arg-id s in a format string must all be present or all be omitted. Mixing manual and automatic indexing is an error.

format-spec - the format specification defined by the std::formatter specialization for the corresponding argument. Cannot start with }.

(since C++23)
(since C++26)
  • For other formattable types, the format specification is determined by user-defined formatter specializations.
args... - arguments to be formatted

[edit] Exceptions

[edit] Notes

Although overloads (3,4) are added in C++26, all known implementations make them available in C++23 mode.

Feature-test macro Value Std Feature
__cpp_lib_print 202207L (C++23) Formatted output
202403L (C++26)
(DR23)		 Formatted output with stream locking
__cpp_lib_format 202207L (C++23) Exposing std::basic_format_string

[edit] Example

Run this code
#include <print>
 
int main()
{
    // Each call to std::println ends with new-line
    std::println("Please"); // overload (1)
    std::println("enter"); // (1)
 
    std::print("pass");
    std::print("word");
 
    std::println(); // (3); valid since C++26; same effect as std::print("\n"); 
}

Output: 

Please
enter
password
 

[edit] See also

(C++23)
 prints to stdout or a file stream using formatted representation of the arguments
(function template) [edit]
(C++23)
 outputs formatted representation of the arguments with appended '\n'
(function template) [edit]
(C++20)
 stores formatted representation of the arguments in a new string
(function template) [edit]
(C++11)
 prints formatted output to stdout, a file stream or a buffer
(function) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/io/println&oldid=171848"