On 11/5/18 12:39 PM, Tom Honermann wrote:
This patch adds documentation for new -fchar8_t and -fno-char8_t options.
gcc/ChangeLog:
2018-11-04 Tom Honermann <t...@honermann.net>
* doc/invoke.texi (-fchar8_t): Document new option.
My comments are all about nitpicky formatting things.
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 57491f1033c..cd3a2a715db 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -206,7 +206,7 @@ in the following sections.
@item C++ Language Options
@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
@gccoptlist{-fabi-version=@var{n} -fno-access-control @gol
--faligned-new=@var{n} -fargs-in-order=@var{n} -fcheck-new @gol
+-faligned-new=@var{n} -fargs-in-order=@var{n} -fchar8_t -fcheck-new @gol
Please consistently use 2 spaces (not just 1) to separate options on the
same line in a @gccoptlist environment.
-fconstexpr-depth=@var{n} -fconstexpr-loop-limit=@var{n} @gol
-fno-elide-constructors @gol
-fno-enforce-eh-specs @gol
@@ -2432,6 +2432,53 @@ but few users will need to override the default of
This flag is enabled by default for @option{-std=c++17}.
+@item -fchar8_t
+@itemx -fno-char8_t
+@opindex fchar8_t
+@opindex fno-char8_t
+Enable support for the P0482 proposal including the addition of a
+new @code{char8_t} fundamental type, changes to the types of UTF-8
+string and character literals, new signatures for user defined
+literals, and new specializations of standard library class templates
+@code{std::numeric_limits<char8_t>}, @code{std::char_traits<char8_t>},
+and @code{std::hash<char8_t>}.
+
+This option enables functions to be overloaded for ordinary and UTF-8
+strings:
+
+@smallexample
+int f(const char *); // #1
+int f(const char8_t *); // #2
+int v1 = f("text"); // Calls #1
+int v2 = f(u8"text"); // Calls #2
+@end smallexample
+
+and introduces new signatures for user defined literals:
@noindent immediately before the continued sentence of the paragraph
before the example.
Also please hyphenate "user-defined" here.
+
+@smallexample
+int operator""_udl1(char8_t);
+int v3 = u8'x'_udl1;
+int operator""_udl2(const char8_t*, std::size_t);
+int v4 = u8"text"_udl2;
+template<typename T, T...> int operator""_udl3();
+int v5 = u8"text"_udl3;
+@end smallexample
+
+The change to the types of UTF-8 string and character literals introduces
+incompatibilities with ISO C++11 and later standards. For example, the
+following code is well-formed under ISO C++11, but is ill-formed when
+@option{-fchar8_t} is specified.
+
+@smallexample
+char ca[] = u8"text"; // error: char-array initialized from wide string
+const char *cp = u8"text"; // error: invalid conversion from 'const char8_t*'
to 'const char*'
+int f(const char*);
+auto v = f(u8"text"); // error: invalid conversion from 'const char8_t*'
to 'const char*'
+std::string s1@{u8"text"@}; // error: no matching function for call to
'std::basic_string<char>::basic_string()'
+using namespace std::literals;
+std::string s2 = u8"text"s; // error: conversion from 'basic_string<char8_t>' to
non-scalar type 'basic_string<char>' requested
+@end smallexample
The formatting of this code example is way too wide to fit on the page
of the printed/PDF manual. I suggest putting the comments on separate
lines from the code and breaking them across multiple lines where
necessary. If you format the example for <80 columns it will probably
fit, although you should check the PDF if at all possible.
+
@item -fcheck-new
@opindex fcheck-new
Check that the pointer returned by @code{operator new} is non-null
-Sandra
