mirror of
https://github.com/boostorg/endian.git
synced 2026-07-05 16:10:56 +02:00
Beman
140 lines
6.2 KiB
HTML
140 lines
6.2 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
|
<meta name="ProgId" content="FrontPage.Editor.Document">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<style>
|
|
body
|
|
{
|
|
font-family: arial, sans-serif;
|
|
max-width: 6.75in;
|
|
margin: 0px auto;
|
|
font-size: 85%;
|
|
}
|
|
ins {background-color: #CCFFCC; text-decoration: none;}
|
|
del {background-color: #FFCACA; text-decoration: none;}
|
|
pre {background-color: #D7EEFF; font-size: 95%; font-family: "courier new", courier, serif;}
|
|
code {font-family: "courier new", courier, serif;}
|
|
table {font-size: 90%;}
|
|
</style>
|
|
<title>Endian RFC</title>
|
|
</head>
|
|
|
|
<body>
|
|
<table>
|
|
<tr>
|
|
<td align="left">Doc. no.:</td>
|
|
<td align="left">D0803R1</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left">Date:</td>
|
|
<td align="left">
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y-%m-%d" startspan -->2017-11-10<!--webbot bot="Timestamp" endspan i-checksum="12111" --></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left">Reply to:</td>
|
|
<td align="left">Beman Dawes <bdawes at acm dot org>
|
|
</tr>
|
|
<tr>
|
|
<td align="left">Audience:</td>
|
|
<td align="left">Library Evolution</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
|
|
<h1 align="center">Endian Library Request for Comments (R1)</h1>
|
|
|
|
|
|
<h2>Abstract</h2>
|
|
<p>The Boost Endian library manipulates the
|
|
<a href="https://en.wikipedia.org/wiki/Endianness">endianness</a> of integers
|
|
and user-defined types. It provides three approaches to dealing with endianness:
|
|
conversion functions, buffer classes, and arithmetic classes. Each approach
|
|
has use cases where it is preferred by users over the other approaches, but
|
|
adding all three approaches to the standard library would likely be too much of
|
|
a good thing. The purpose of
|
|
this RFC is to determine interest in adding the Boost conversion functions alone to
|
|
the C++ standard library or a library TS.</p>
|
|
<h2>Introduction</h2>
|
|
<p>The Boost Endian documentation (<a href="https://www.boost.org/libs/endian/doc/index.html">www.boost.org/libs/endian/doc</a>)
|
|
provides an <a href="https://www.boost.org/libs/endian/doc/index.html">overview</a>
|
|
and detailed technical specifications for the
|
|
<a href="https://www.boost.org/libs/endian/doc/conversion.html">conversion
|
|
functions</a>, <a href="https://www.boost.org/libs/endian/doc/arithmetic.html">
|
|
arithmetic types</a>, and
|
|
<a href="https://www.boost.org/libs/endian/doc/buffers.html">buffer types</a>.
|
|
</p>
|
|
<p>A separate discussion covers
|
|
<a href="https://www.boost.org/libs/endian/doc/choosing_approach.html">choosing
|
|
between the three approaches</a> provided by the library.</p>
|
|
<p>For those not interested in plowing through the entire documentation, the
|
|
<a href="https://www.boost.org/libs/endian/doc/index.html#FAQ">Overall FAQ</a>,
|
|
<a href="https://www.boost.org/libs/endian/doc/conversion.html#FAQ">Conversion
|
|
FAQ</a>, <a href="https://www.boost.org/libs/endian/doc/arithmetic.html#FAQ">
|
|
Arithmetic FAQ</a>, and
|
|
<a href="https://www.boost.org/libs/endian/doc/buffers.html#FAQ">Buffers FAQ</a>
|
|
answer a lot of question likely to arise during standardization.</p>
|
|
<h2>Motivation for standardization</h2>
|
|
Lack of any one de facto standard endianness capability in either C or
|
|
C++. While most platforms provides some way to handle endianness in C, the
|
|
mechanism varies from platform to platform.<ul>
|
|
<li>Commonly used C endian handling functions are extremely error prone. While
|
|
the Boost Endian conversion functions have some of the same problems, the buffer and
|
|
arithmetic classes do not.</li>
|
|
<li>Surprisingly difficult to write and test yourself in a portable yet
|
|
efficient (i.e. using intrinsics) way. </li>
|
|
<li>Explicit requests for standardization from Boost Endian users.</li>
|
|
<li>The Boost library is existing practice with years of both implementation
|
|
and end-user experience.</li>
|
|
<li>The committee has already started to standardize endian conversion
|
|
functions once, but had to pull the proposal at the last minute because of
|
|
name clashes with widely used macros.</li>
|
|
</ul>
|
|
<h2>Motivation for standardizing only the conversion functions</h2>
|
|
<ul>
|
|
<li>KISS; Providing three different solutions to the same problem space
|
|
regularly confuses to Boost users and makes endianness solutions harder to
|
|
teach.</li>
|
|
<li>The conversion functions are what end users would need to build their own
|
|
higher level abstractions.</li>
|
|
<li>The safe use patterns for the conversion functions are already familiar to
|
|
users of platform specific C endian conversion functions.</li>
|
|
<li>The Boost buffer and arithmetic types are specified and implemented in
|
|
terms of the conversion functions, so are easy to add later if desired.</li>
|
|
</ul>
|
|
<h2>Impact on the standard library</h2>
|
|
<p>Endianness conversion functions would be pure additions to the
|
|
standard library and would break no existing user code (modulo the usual
|
|
namespace <code>std</code> caveats).</p>
|
|
<h2>Proposed wording</h2>
|
|
<p>The Boost Endian reference documentation for
|
|
<a href="https://www.boost.org/libs/endian/doc/conversion.html#Reference">
|
|
Conversion</a> follows the standard library's <i>Method of description</i>
|
|
[description], so provides a fairly close approximation of what proposed wording
|
|
would look like. Actual proposed wording will be provided in a proposal document
|
|
if the library is of interest to the committee. Names will need
|
|
the usual review.</p>
|
|
<h2>Revision history</h2>
|
|
<p>R1: Limits proposal to the conversion functions. KISS.</p>
|
|
<p>R0: Considers adding all three endianness approaches to the standard library.</p>
|
|
<h2>Question for the Library Evolution Group</h2>
|
|
Assuming a fully-worded and reviewed proposal to add a
|
|
standardized version of the Boost Endian conversion functions to the standard
|
|
library or a library TS, how would you likely vote for it?<h2>Target?</h2>
|
|
<p>It is premature to discuss whether to target a TS or the IS. We need to have
|
|
an acceptable proposal in hand and see where we are in the release cycle before
|
|
deciding on the target. </p>
|
|
<h2>Acknowledgements</h2>
|
|
<p>The original design for the arithmetic classes was developed by Darin Adler
|
|
based on work by Mark Borgerding. The Boost documentation acknowledges
|
|
<a href="https://www.boost.org/libs/endian/doc/index.html#Acknowledgements">45+
|
|
other people</a>.</p>
|
|
<hr>
|
|
<p> </p>
|
|
|
|
|
|
</body>
|
|
|
|
</html> |