<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
  <head>
    <meta content="text/html;charset=UTF-8" http-equiv="Content-Type">
    <title>Hexadecimal floating literals for C++</title>
    <style type="text/css">
      html { margin: 0; padding: 0; color: black; background-color: white; }
      body { padding: 2em; font-size: medium; font-family: "DejaVu Serif", serif; line-height: 150%; }
      code { font-family: "DejaVu Sans Mono", monospace; color: #006; }

      h1, h2, h3 { margin: 1.5em 0 .75em 0; line-height: 125%; }

      div.code { white-space: pre-line; font-family: "DejaVu Sans Mono", monospace;
                 border: thin solid #E0E0E0; background-color: #F8F8F8; padding: 1em;
                 border-radius: 4px; }

      div.strictpre { white-space: pre; }

      sup, sub { line-height: 0; }

      .docinfo { float: right }
      .docinfo p { margin: 0; text-align:right; }
      .docinfo address { font-style: normal; }

      .quote { display: inline-block; clear: both; margin-left: 1ex;
                 border: thin solid #E0E0E0; background-color: #F8F8F8; padding: 1ex; }

      .modify { border-left: thick solid #999; border-right: thick solid #999; padding: 0 1em; }
      .comment { color: #456; }

      ins { color: #090; }
      del { color: #A00; }
      ins code, del code { color: inherit; }

      input#hide:checked ~ * del { display: none; }
    </style>
  </head>
  <body>
    <div class="docinfo">
      <p>ISO/IEC JTC1 SC22 WG21 P00245r0</p>
      <p>Date: 2016-02-09</p>
      <p>To: EWG, CWG</p>
      <address>Thomas K&ouml;ppe &lt;<a href="mailto:tkoeppe@google.com">tkoeppe@google.com</a>&gt;</address>
    </div>

    <h1>Hexadecimal floating literals for C++</h1>

    <!-- fgrep -e "<h2 id=" hexfloat.html | sed -e 's/.*id="\(.*\)">\(.*\)<\/h2>/<li><a href="#\1">\2<\/a><\/li>/g' -->
    <h2>Contents</h2>
    <ol>
      <li><a href="#summary">Summary</a></li>
      <li><a href="#impact">Impact</a></li>
      <li><a href="#wording">Proposed wording</a></li>
      <li><a href="#libio">An iostreams issue</a></li>
      <li><a href="#existing">Existing practice and implementation experience</a></li>
    </ol>

    <h2 id="summary">Summary</h2>

    <p>There is a base-2 scientific notation for floating point values: <code>0x3.ABCp-10</code>.
      The significand is given in hexadecimal, and the exponent is given in decimal and interpreted
      with respect to base 2. This notation is convenient for certain uses. For example, the smallest
      normal IEEE-754 single precision value is readily written as <code>0x1.0p-126</code>. More
      generally, this notation can be used when an exact object representation is desired (and the
      floating point implementation uses a base-2 or base-2<sup><em>n</em></sup> representation).</p>
    <p>The standard library outputs this representation via the <code>hexfloat</code> manipulator
      for ostreams, and via the <code>a</code>/<code>A</code> conversion specifiers in
      <code>printf</code>. Similarly,
      formatted input works because <code>strtod</code> recognises this representation (and
      the semantics of formatted istream input operations and <code>scanf</code> are defined in
      terms of <code>strtod</code>, but see below for a detail). We should also allow this
      representation as a literal in the core language.</p>
    <p>Note that the C language which is referenced by the C++ standard also allows this literal
      syntax.</p>

    <h2 id="impact">Impact</h2>

    <p>This is a core language extension that adds a new numeric literal syntax. The proposed
      syntax is ill-formed in the current working draft. Note that non-standard user-defined
      literals must start with an underscore, and the standard library does not define a UDL
      operator named <code>p</code> or <code>P</code>.</p>

    <h2 id="wording">Proposed wording</h2>

    <input id="hide" type="checkbox"><label for="hide">hide deleted text</label>

    <p>In section [lex.fcon] (2.13.4 in the working draft), change
      the grammar as follows (cf. C11 6.4.4.2/1).</p>

    <div class="modify" style="white-space: pre"><!--
--><em>floating-literal</em>:
&nbsp;&nbsp;<ins><em>decimal-floating-literal</em></ins>
&nbsp;&nbsp;<ins><em>hexadecimal-floating-literal</em></ins>

<ins><em>decimal-floating-literal</em>:</ins>
&nbsp;&nbsp;<em>fractional-constant</em> <em>exponent-part</em><sub>opt</sub> <em>floating-suffix</em><sub>opt</sub>
&nbsp;&nbsp;<em>digit-sequence</em> <em>exponent-part</em> <em>floating-suffix</em><sub>opt</sub>

<ins><em>hexadecimal-floating-literal</em>:</ins>
&nbsp;&nbsp;<ins><em>hexadecimal-prefix</em> <em>hexadecimal-fractional-constant</em> <em>binary-exponent-part</em> <em>floating-suffix</em><sub>opt</sub></ins>
&nbsp;&nbsp;<ins><em>hexadecimal-prefix</em> <em>hexadecimal-digit-sequence</em> <em>binary-exponent-part</em> <em>floating-suffix</em><sub>opt</sub></ins>

<em>fractional-constant</em>:
&nbsp;&nbsp;<em>digit-sequence</em><sub>opt</sub> <code>.</code> <em>digit-sequence</em>
&nbsp;&nbsp;<em>digit-sequence</em> <code>.</code>

<ins><em>hexadecimal-fraction-constant</em>:</ins>
&nbsp;&nbsp;<ins><em>hexadecimal-digit-sequence</em><sub>opt</sub> <code>.</code> <em>hexadecimal-digit-sequence</em></ins>
&nbsp;&nbsp;<ins><em>hexadecimal-digit-sequence</em> <code>.</code></ins>

<em>exponent-part</em>:
&nbsp;&nbsp;<code>e</code> <em>sign</em><sub>opt</sub> <em>digit-sequence</em>
&nbsp;&nbsp;<code>E</code> <em>sign</em><sub>opt</sub> <em>digit-sequence</em>

<ins><em>binary-exponent-part</em>:</ins>
&nbsp;&nbsp;<ins><code>p</code> <em>sign</em><sub>opt</sub> <em>digit-sequence</em></ins>
&nbsp;&nbsp;<ins><code>P</code> <em>sign</em><sub>opt</sub> <em>digit-sequence</em></ins>

<em>sign</em>: one of
&nbsp;&nbsp;<code>+ -</code>

<em>digit-sequence</em>:
&nbsp;&nbsp;<em>digit</em>
&nbsp;&nbsp;<em>digit-sequence</em> '<sub>opt</sub> <em>digit</em>

<ins><em>hexadecimal-digit-sequence</em>:</ins>
&nbsp;&nbsp;<ins><em>hexadecimal-digit</em></ins>
&nbsp;&nbsp;<ins><em>hexadecimal-digit-sequence</em> '<sub>opt</sub> <em>hexadecimal-digit</em></ins>

<ins><em>hexadecimal-prefix</em>: one of</ins>
&nbsp;&nbsp;<ins><code>0x 0X</code></ins>

<em>floating-suffix</em>: one of
&nbsp;&nbsp;<code>f l F L</code></div>

    <p>Change the subsequent paragraph 1 in the following way:</p>

    <div class="modify">
      A floating literal consists of an integer part, a
      <del>decimal</del><ins>radix</ins> point, a fraction part, an

      <del><code>e</code> or <code>E</code>,</del>
      <ins><code>e</code>, <code>E</code>, <code>p</code> or <code>P</code>,</ins>

      an optionally
      signed integer exponent, and an optional type suffix. The integer and
      fraction parts both consist of <ins>either</ins>
      a sequence of decimal (base ten) digits

      <del>.</del><ins>, or they include the <em>hexadecimal-prefix</em>
      and consist of a sequence of hexadecimal (base sixteen) digits.
      The literal is a <em>decimal floating literal</em> in the former case and
      a <em>hexadecimal floating literal</em> in the latter case.</ins>

      Optional separating single quotes in a
      <em>digit-sequence</em> <ins>or <em>hexadecimal-digit-sequence</em></ins>
      are ignored when determining its value.
      [Example. The literals <code>1.602'176'565e-19</code> and <code>1.602176565e-19</code>
      have the same value.]

      Either the integer part or the fraction part (not both) can be
      omitted<del>; either</del><ins>. Either</ins>
      the <del>decimal</del><ins>radix</ins> point or the
      letter <code>e</code> <del>(or <code>E</code> )</del><ins>or <code>E</code></ins>
      and the exponent (not both) can be omitted <ins>from a decimal floating literal</ins>.
      <ins>The radix point (but not the exponent) can be omitted from a hexadecimal floating literal.</ins>

      The integer part, the optional <del>decimal</del><ins>radix</ins> point and the optional
      fraction part form the <em><del>significant</del><ins>significand</ins> part</em> of the
      floating literal.

      <del>The</del><ins>In a decimal floating literal, the</ins> exponent, if present,
      indicates the power of 10 by which the <del>significant</del><ins>significand</ins>
      part is to be scaled.

      <ins>In a hexadecimal floating literal, the exponent indicates the power of 2 by
      which the significand part is to be scaled.</ins>

      If the scaled value is in
      the range of representable values for its type, the result is the scaled
      value if representable, else the larger or smaller representable value
      nearest the scaled value, chosen in an implementation-defined manner.
      The type of a floating literal is <code>double</code>
      unless explicitly specified by a suffix. The suffixes <code>f</code> and
      <code>F</code> specify <code>float</code>, the suffixes <code>l</code> and
      <code>L</code> specify <code>long double</code>. If the scaled value is not
      in the range of representable values for its type, the program is ill-formed.
    </div>

    <p><em>Drafting note.</em> We changed &ldquo;significant&rdquo; to &ldquo;significand&rdquo;
      and &ldquo;decimal point&rdquo; to &ldquo;radix point&rdquo;.</p>

    <p>Also change the grammar in section [lex.ext] (2.13.8):</p>
    <div class="modify" style="white-space: pre"><!--
--><em>user-defined-floating-literal</em>:
&nbsp;&nbsp;<em>fractional-constant</em> <em>exponent-part</em><sub>opt</sub> <em>ud-suffix</em>
&nbsp;&nbsp;<em>digit-sequence</em> <em>exponent-part</em> <em>ud-suffix</em>
&nbsp;&nbsp;<ins><em>hexadecimal-prefix</em> <em>hexadecimal-fractional-constant</em> <em>binary-exponent-part</em> <em>ud-suffix</em></ins>
&nbsp;&nbsp;<ins><em>hexadecimal-prefix</em> <em>hexadecimal-digit-sequence</em> <em>binary-exponent-part</em> <em>ud-suffix</em></ins></div>

    <h2 id="libio">An iostreams issue</h2>

    <p>Although the library rules in [facet.num.get.members] say that formatted floating
      point input uses the conversion rules of <code>strtod</code> etc., the section also
      restricts the set of characters permissible for floating point parsing to
      <code>"0123456789abcdefxABCDEFX+-"</code>, which is missing the values <code>p</code>
      and <code>P</code>. Should the present proposal succeed, we plan to either create a new
      library proposal, or revisit <a href="http://wg21.link/lwg2381">LWG issue 2381</a>
      to add support for parsing hexadecimal floating point literals to the standard library.</p>

    <h2 id="existing">Existing practice and implementation experience</h2>

    <p>Hexadecimal float literals are already supported as a vendor extension by several
      compilers: Clang, EDG, Embarcadero, GCC. Formatted input via iostreams is supported
      by libc++.</p>

  </body>
</html>
