29/// * <a href="#bsla_unreachable-example-1-indicating-that-a-statement-is-intended-to-be-unreachable"> Example 1: Indicating That a Statement is Intended to be Unreachable </a>
30///
31/// # Purpose {#bsla_unreachable-purpose}
32/// Provide a compiler-hint macro to indicate unreachable code.
33///
34/// # Macros {#bsla_unreachable-macros}
35///
36/// - BSLA_UNREACHABLE: indicate that a statement is intended to be not reached
37/// - BSLA_UNREACHABLE_IS_ACTIVE: defined if `BSLA_UNREACHABLE` is active
51/// This macro will, when used and followed by a semicolon, create a
52/// statement that emits no code, but that is indicated to be unreachable,
53/// causing compilers, where supported, to issue warnings if there is
54/// actually a way that the statement can be reached. Note that the
55/// behavior is undefined if control actually reaches a `BSLA_UNREACHABLE`
56/// statement.
57///
58/// `BSLA_UNREACHABLE_IS_ACTIVE`:
59/// The macro `BSLA_UNREACHABLE_IS_ACTIVE` is defined if `BSLA_UNREACHABLE`
60/// expands to something with the desired effect; otherwise
61/// `BSLA_UNREACHABLE_IS_ACTIVE` is not defined and `BSLA_UNREACHABLE`
62/// expands to nothing.
63///
64/// ## Usage {#bsla_unreachable-usage}
65///
66///
67/// This section illustrates intended use of this component.
68///
69/// ### Example 1: Indicating That a Statement is Intended to be Unreachable {#bsla_unreachable-example-1-indicating-that-a-statement-is-intended-to-be-unreachable}
70///
71///
72/// First, we define a function, `directoriesInPath`, that counts the number of
73/// directories in the `PATH` environment variable. If `PATH` is not set, the
74/// program dumps core by calling `BSLS_ASSERT_OPT`:
75/// @code
76/// int directoriesInPath()
77/// {
78/// const char *path = ::getenv("PATH");
79/// if (path) {
80/// int ret = 1;
81/// for (; *path; ++path) {
82/// ret += ':' == *path;
83/// }
84/// return ret; // RETURN
85/// }
86///
87/// BSLS_ASSERT_OPT(false && "$PATH not set");
88/// }
89/// @endcode
90/// Then, we observe a compile error because the compiler expects the
91/// `BSLA_ASSERT_OPT` to return and the function to run off the end and return
92/// `void`, while the function is declared to return `int`.
93/// @code
94/// .../bsla_unreachable.t.cpp(141) : error C4715: 'directoriesInPath': not all
95/// control paths return a value
96/// @endcode
97/// Now, we put a `BSLA_UNREACHABLE` statement after the `BSLS_ASSERT_OPT`,
98/// which tells the compiler that that point in the code is unreachable:
99/// @code
100/// int directoriesInPath()
101/// {
102/// const char *path = ::getenv("PATH");
103/// if (path) {
104/// int ret = 1;
105/// for (; *path; ++path) {
106/// ret += ':' == *path;
107/// }
108/// return ret; // RETURN
109/// }
110///
111/// BSLS_ASSERT_OPT(false && "$PATH not set");
112///
113/// BSLA_UNREACHABLE;
114/// }
115/// @endcode
116/// Finally, we observe that the compiler error is silenced and the build is
117/// successful.
118/// @}
119/** @} */
120/** @} */
121
122/** @addtogroup bsl
123 * @{
124 */
125/** @addtogroup bsla
126 * @{
127 */
128/** @addtogroup bsla_unreachable
129 * @{
130 */
131
132#include <bsls_platform.h>
133
134// =============================
135// Checks for Pre-Defined macros
136// =============================
137
138#if defined(BSLA_UNREACHABLE)
139#error BSLA_UNREACHABLE is already defined!
140#endif
141
142#if defined(BSLA_UNREACHABLE_IS_ACTIVE)
143#error BSLA_UNREACHABLE_IS_ACTIVE is already defined!
1.9.8