Endian RFC

Doc. no.: | D0803R1
Date: | 2017-11-10
Reply to: | Beman Dawes <bdawes at acm dot org>
Audience: | Library Evolution

# Endian Library Request for Comments (R1)

## Abstract

The Boost Endian library manipulates the endianness 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.

## Introduction

The Boost Endian documentation (www.boost.org/libs/endian/doc) provides an overview and detailed technical specifications for the conversion functions, arithmetic types, and buffer types.

A separate discussion covers choosing between the three approaches provided by the library.

For those not interested in plowing through the entire documentation, the Overall FAQ, Conversion FAQ, Arithmetic FAQ, and Buffers FAQ answer a lot of question likely to arise during standardization.

## Motivation for standardization

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.

- 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.
- Surprisingly difficult to write and test yourself in a portable yet efficient (i.e. using intrinsics) way.
- Explicit requests for standardization from Boost Endian users.
- The Boost library is existing practice with years of both implementation and end-user experience.
- 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.

## Motivation for standardizing only the conversion functions

- KISS; Providing three different solutions to the same problem space regularly confuses to Boost users and makes endianness solutions harder to teach.
- The conversion functions are what end users would need to build their own higher level abstractions.
- The safe use patterns for the conversion functions are already familiar to users of platform specific C endian conversion functions.
- The Boost buffer and arithmetic types are specified and implemented in terms of the conversion functions, so are easy to add later if desired.

## Impact on the standard library

Endianness conversion functions would be pure additions to the standard library and would break no existing user code (modulo the usual namespace `std` caveats).

## Proposed wording

The Boost Endian reference documentation for Conversion follows the standard library's Method of description [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.

## Revision history

R1: Limits proposal to the conversion functions. KISS.

R0: Considers adding all three endianness approaches to the standard library.

## Question for the Library Evolution Group

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?

## Target?

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.

## Acknowledgements

The original design for the arithmetic classes was developed by Darin Adler based on work by Mark Borgerding. The Boost documentation acknowledges 45+ other people.