1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> 4<section id="safe_numerics.composition_with_other_libraries"> 5 <title>Composition with Other Libraries</title> 6 7 <?dbhtml stop-chunking?> 8 9 <para>For many years, Boost has included a library to represent and operate 10 on <ulink url="http://www.boost.org/doc/libs/1_64_0/libs/rational/">rational 11 numbers</ulink>. Its well crafted, has good documentation and is well 12 maintained. Using the rational library is as easy as construction an 13 instance with the expression <code>rational r(n, d)</code> where n and d are 14 integers of the same type. From then on it can be used pretty much as any 15 other number. Reading the documentation with safe integers in mind one 16 finds<blockquote> 17 <para>Limited-precision integer types [such as <code>int</code>] may 18 raise issues with the range sizes of their allowable negative values and 19 positive values. If the negative range is larger, then the 20 extremely-negative numbers will not have an additive inverse in the 21 positive range, making them unusable as denominator values since they 22 cannot be normalized to positive values (unless the user is lucky enough 23 that the input components are not relatively prime 24 pre-normalization).</para> 25 </blockquote>Which hints of trouble. Examination of the code reveals which 26 suggest that care has been taken implement operations so as to avoid 27 overflows, catch divide by zero, etc. But the code itself doesn't seem to 28 consistently implement this idea. So we make a small demo program: 29 <programlisting><xi:include href="../../example/example15.cpp" parse="text" 30 xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>which 31 produces the following output<screen>r = 1/2 32q = -1/2 33r * q = -1/4 34c = 1/2147483647 35d = 1/2 36c * d = 1/-2 37c = 1/2147483647 38d = 1/2 39c * d = multiplication overflow: positive overflow error 40</screen></para> 41 42 <para>The <ulink 43 url="http://www.boost.org/doc/libs/1_64_0/libs/rational/">rational library 44 documentation</ulink> is quite specific as to the <ulink 45 url="http://www.boost.org/doc/libs/1_64_0/libs/rational/rational.html#Integer%20Type%20Requirements">type 46 requirements</ulink> placed on the underlying type. Turns out the our <link 47 linkend="safe_numerics.integer">own definition of an integer type</link> 48 fulfills (actually surpasses) these requirements. So we have reason to hope 49 that we can use <code>safe<int></code> as the underlying type to 50 create what we might call a "<code>safe_rational</code>". This we have done 51 in the above example where we demonstrate how to compose the rational 52 library with the safe numerics library in order to create what amounts to a 53 safe_rational library - all without writing a line of code! Still, things 54 are not perfect. Since the <ulink 55 url="http://www.boost.org/doc/libs/1_64_0/libs/rational/">rational numbers 56 library</ulink> implements its own checking for divide by zero by throwing 57 an exception, the safe numerics code for handling this - included exception 58 policy will not be respected. To summarize:<itemizedlist> 59 <listitem> 60 <para>In some cases safe types can be used as template parameters to 61 other types to inject the concept of "no erroneous results" into the 62 target type.</para> 63 </listitem> 64 65 <listitem> 66 <para>Such composition is not guaranteed to work. The target type must 67 be reviewed in some detail.</para> 68 </listitem> 69 </itemizedlist></para> 70</section> 71