llvm.org GIT mirror llvm / 8456354
[docs] Simplify some language for Error/cantFail in the programmer's manual. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@301773 91177308-0d34-0410-b5e6-96231b3b80d8 Lang Hames 3 years ago
1 changed file(s) with 12 addition(s) and 13 deletion(s). Raw diff Collapse all Expand all
775775 Using cantFail to simplify safe callsites
776776 """""""""""""""""""""""""""""""""""""""""
777777
778 Some functions may only fail for a subset of their inputs. For such functions
779 call-sites using known-safe inputs can assume that the result will be a success
780 value.
778 Some functions may only fail for a subset of their inputs, so calls using known
779 safe inputs can be assumed to succeed.
781780
782781 The cantFail functions encapsulate this by wrapping an assertion that their
783782 argument is a success value and, in the case of Expected, unwrapping the
784 T value from the Expected argument:
785
786 .. code-block:: c++
787
788 Error mayFail(int X);
789 Expected mayFail2(int X);
783 T value:
784
785 .. code-block:: c++
786
787 Error onlyFailsForSomeXValues(int X);
788 Expected onlyFailsForSomeXValues2(int X);
790789
791790 void foo() {
792 cantFail(mayFail(KnownSafeValue));
793 int Y = cantFail(mayFail2(KnownSafeValue));
791 cantFail(onlyFailsForSomeXValues(KnownSafeValue));
792 int Y = cantFail(onlyFailsForSomeXValues2(KnownSafeValue));
794793 ...
795794 }
796795
800799 is success. In debug builds this will result in an assertion failure if an error
801800 is encountered. In release builds the behavior of cantFail for failure values is
802801 undefined. As such, care must be taken in the use of cantFail: clients must be
803 certain that a cantFail wrapped call really can not fail under any
804 circumstances.
802 certain that a cantFail wrapped call really can not fail with the given
803 arguments.
805804
806805 Use of the cantFail functions should be rare in library code, but they are
807806 likely to be of more use in tool and unit-test code where inputs and/or