1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
3"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
4<section id="safe_numerics.safe_literal">
5  <title>safe_signed_literal&lt;Value, PP , EP&gt; and
6  safe_unsigned_literal&lt;Value, PP, EP&gt;</title>
7
8  <?dbhtml stop-chunking?>
9
10  <section>
11    <title>Description</title>
12
13    <para>A safe type which holds a literal value. This is required to be able
14    to initialize other safe types in such a way that an exception code is not
15    generated. It is also useful when creating constexpr versions of safe
16    types. It contains one immutable value known at compile time and hence can
17    be used in any constexpr expression.</para>
18  </section>
19
20  <section>
21    <title>Model of</title>
22
23    <para><link linkend="safe_numerics.numeric">Integer</link></para>
24
25    <para><link
26    linkend="safe_numerics.safe_numeric_concept">SafeNumeric</link></para>
27
28    <para>This type inherits all the notation, associated types and template
29    parameters and valid expressions of <link
30    linkend="safe_numerics.safe_numeric_concept">SafeNumeric</link> types. The
31    following specify additional features of this type.</para>
32  </section>
33
34  <section>
35    <title>Associated Types</title>
36
37    <informaltable>
38      <tgroup cols="2">
39        <colspec align="left" colwidth="1*"/>
40
41        <colspec align="left" colwidth="10*"/>
42
43        <tbody>
44          <row>
45            <entry><code>PP</code></entry>
46
47            <entry>A type which specifies the result type of an expression
48            using safe types.</entry>
49          </row>
50
51          <row>
52            <entry><code>EP</code></entry>
53
54            <entry>A type containing members which are called when a correct
55            result cannot be returned</entry>
56          </row>
57        </tbody>
58      </tgroup>
59    </informaltable>
60  </section>
61
62  <section>
63    <title>Template Parameters</title>
64
65    <informaltable>
66      <tgroup cols="3">
67        <colspec align="left" colwidth="1*"/>
68
69        <colspec align="left" colwidth="1*"/>
70
71        <colspec align="left" colwidth="3*"/>
72
73        <thead>
74          <row>
75            <entry align="left">Parameter</entry>
76
77            <entry align="left">Type Requirements</entry>
78
79            <entry>Description</entry>
80          </row>
81        </thead>
82
83        <tbody>
84          <row>
85            <entry><code>Value</code></entry>
86
87            <entry><code><link
88            linkend="safe_numerics.numeric">Integer</link></code></entry>
89
90            <entry>value used to initialize the literal</entry>
91          </row>
92
93          <row>
94            <entry><code>PP</code></entry>
95
96            <entry><link linkend="safe_numerics.numeric"><link
97            linkend="safe_numerics.promotion_policy">PromotionPolicy&lt;PP&gt;</link></link></entry>
98
99            <entry><para>Optional promotion policy. Default value is
100            <code>void</code></para></entry>
101          </row>
102
103          <row>
104            <entry><code>EP</code></entry>
105
106            <entry><link linkend="safe_numerics.numeric"><link
107            linkend="safe_numerics.exception_policy">Exception
108            Policy&lt;EP&gt;</link></link></entry>
109
110            <entry><para>Optional exception policy. Default value is
111            <code>void</code></para></entry>
112          </row>
113        </tbody>
114      </tgroup>
115    </informaltable>
116  </section>
117
118  <section>
119    <title>Inherited Valid Expressions</title>
120
121    <para>safe literal types are immutable. Hence they only inherit those
122    valid expressions which don't change the value. <emphasis>This excludes
123    assignment, increment, and decrement and all unary operators except unary
124    -, + and ~</emphasis>. Other than that, they can be used anywhere a <link
125    linkend="safe_numerics.safe_numeric_concept">SafeNumeric</link> type can
126    be used. Note that the default promotion and exception policies are void.
127    This is usually convenient since when a safe literal is used in a binary
128    operation, this will inherit the policies of the other type. On the other
129    hand, this can be inconvenient when operands of a binary expression are
130    both safe literals. This will fail to compile since there are no
131    designated promotion and exception policies. The way to address this to
132    assign specific policies as in this example.</para>
133
134    <para><programlisting>template&lt;typename T&gt;
135using compile_time_value = safe_signed_literal&lt;T&gt;;
136
137constexpr compile_time_value&lt;1000&gt; x;
138constexpr compile_time_value&lt;0&gt; y;
139
140// should compile and execute without problem
141
142std::cout &lt;&lt; x &lt;&lt; '\n';
143
144// all the following statements should fail to compile because there are
145// no promotion and exception policies specified.
146constexpr safe&lt;int&gt; z = x / y;
147</programlisting></para>
148  </section>
149
150  <section>
151    <title>Example of use</title>
152
153    <programlisting>#include &lt;boost/numeric/safe_numerics/safe_integer_literal.hpp&gt;
154
155constexpr boost::numeric::safe_signed_literal&lt;42&gt; x;
156</programlisting>
157  </section>
158
159  <section id="safe_numerics.safe_literal.make_safe_literal">
160    <title><code>make_safe_literal(n, PP, EP) </code></title>
161
162    <para>This is a macro which returns an instance of a safe literal type.
163    This instance will hold the value n. The type of the value returned will
164    be the smallest safe type which can hold the value <code>n</code>.</para>
165  </section>
166
167  <section>
168    <title>Header</title>
169
170    <para><ulink
171    url="../../include/boost/safe_numerics/safe_integer_literal.hpp">#include
172    &lt;boost/numeric/safe_numerics/safe_integer_literal.hpp&gt;</ulink></para>
173  </section>
174</section>
175