RPCS3/llvm-mirror
1
0
Fork 0
mirror of https://github.com/RPCS3/llvm-mirror.git synced 2024-12-02 00:16:25 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[doc]Update String Error documentation in Programmer Manual

Browse Source 
A while back, createStringError was added to provide easier construction
of StringError instances, especially with formatting options. Prior to
this patch, that the documentation only mentions the standard method of
using it. Since createStringError is slightly shorter to type, and also
provides the formatting options, this patch updates the Programmer's
Manual to use the new function in its examples, and to mention the
printf formatting options. It also fixes a small typo in one of the
examples and removes the unnecessary make_error_code call.

llvm-svn: 352846
This commit is contained in:
James Henderson 2019-02-01 10:02:42 +00:00
parent e193494258
commit 2f544e718b
1 changed files with 14 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/ProgrammersManual.rst
View File

@ -656,19 +656,21 @@ taken is to report them to the user so that the user can attempt to fix the
environment. In this case representing the error as a string makes perfect
sense. LLVM provides the ``StringError`` class for this purpose. It takes two
arguments: A string error message, and an equivalent ``std::error_code`` for
interoperability:
interoperability. It also provides a ``createStringError`` function to simplify
common usage of this class:
.. code-block:: c++
make_error<StringError>("Bad executable",
make_error_code(errc::executable_format_error"));
// These two lines of code are equivalent:
make_error<StringError>("Bad executable", errc::executable_format_error);
createStringError(errc::executable_format_error, "Bad executable");
If you're certain that the error you're building will never need to be converted
to a ``std::error_code`` you can use the ``inconvertibleErrorCode()`` function:
.. code-block:: c++
make_error<StringError>("Bad executable", inconvertibleErrorCode());
createStringError(inconvertibleErrorCode(), "Bad executable");
This should be done only after careful consideration. If any attempt is made to
convert this error to a ``std::error_code`` it will trigger immediate program
@ -677,6 +679,14 @@ interoperability you should look for an existing ``std::error_code`` that you
can convert to, and even (as painful as it is) consider introducing a new one as
a stopgap measure.
``createStringError`` can take ``printf`` style format specifiers to provide a
formatted message:
.. code-block:: c++
createStringError(errc::executable_format_error,
"Bad executable: %s", FileName);
Interoperability with std::error_code and ErrorOr
"""""""""""""""""""""""""""""""""""""""""""""""""