Endian Conversion Functions

Boost , ,

Introduction

Заголовокboost/endian/conversion.hppобеспечивает функции разворота и преобразования байтового порядка, которые преобразуют объекты встроенных целочисленных типов между нативным, большим или маленьким эндиановым байтовым заказом. Поддерживаются также определенные пользователем типы.

Reference

При необходимости выполняются функции<inline>.<>Для компиляторов C++03<noexcept>не используется. Эмуляция расширенного перечня используется для того, чтобы библиотека по-прежнему работала для компиляторов, которые не поддерживают расширенные перечни.

Definitions

Эндианностьотносится к упорядочению байтов внутри внутренних или внешних целых чисел и других арифметических данных. Самый значимый байт первым называетсябольшим эндианомупорядочением. Наименее значимый байт первым называетсямалым эндианомупорядочением. Возможны другие заказы, а некоторые архитектуры процессоров поддерживают как большой, так и маленький заказ.

[править]Примечание:Имена происходят отсатирического романа Джонатана Свифта.Путешествия Гулливера, где соперничающие царства открывали свои яйца в мягком варе на разных концах. Википедия имеет обширное описаниеЭндианности.— конец примечания

Стандартные интегральные типы (C++std 3.9.1) за исключением<bool>в совокупности называютсяэндианными типами.

Header <boost/endian/conversion.hpp> Synopsis

#define BOOST_ENDIAN_INTRINSIC_MSG \
   "message describing presence or absence of intrinsics"
namespace boost
{
namespace endian
{
  enum class order
  {
    native = see below,
    big    = see below,
    little = see below,
   };
  int8_t   endian_reverse(int8_t x) noexcept;
  int16_t  endian_reverse(int16_t x) noexcept;
  int32_t  endian_reverse(int32_t x) noexcept;
  int64_t  endian_reverse(int64_t x) noexcept;
  uint8_t  endian_reverse(uint8_t x) noexcept;
  uint16_t endian_reverse(uint16_t x) noexcept;
  uint32_t endian_reverse(uint32_t x) noexcept;
  uint64_t endian_reverse(uint64_t x) noexcept;
  template <class EndianReversible>
    EndianReversible big_to_native(EndianReversible x) noexcept;
  template <class EndianReversible>
    EndianReversible native_to_big(EndianReversible x) noexcept;
  template <class EndianReversible>
    EndianReversible little_to_native(EndianReversible x) noexcept;
  template <class EndianReversible>
    EndianReversible native_to_little(EndianReversible x) noexcept;
  template <order O1, order O2, class EndianReversible>
    EndianReversible conditional_reverse(EndianReversible x) noexcept;
  template <class EndianReversible>
    EndianReversible conditional_reverse(EndianReversible x,
      order order1, order order2) noexcept;
      
  template <class EndianReversible>
    void endian_reverse_inplace(EndianReversible& x) noexcept;
  template <class EndianReversibleInplace>
    void big_to_native_inplace(EndianReversibleInplace& x) noexcept;
  template <class EndianReversibleInplace>
    void native_to_big_inplace(EndianReversibleInplace& x) noexcept;
  template <class EndianReversibleInplace>
    void little_to_native_inplace(EndianReversibleInplace& x) noexcept;
  template <class EndianReversibleInplace>
    void native_to_little_inplace(EndianReversibleInplace& x) noexcept;
  template <order O1, order O2, class EndianReversibleInplace>
    void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept; 
  template <class EndianReversibleInplace>
   void conditional_reverse_inplace(EndianReversibleInplace& x,
     order order1, order order2) noexcept;
} // namespace endian
} // namespace boost

Величины<order::little>и<order::big>не равны между собой.

Стоимость<order::native>составляет:

• равнымorder::big, если среда исполнения является большой эндианной, в противном случае
• order::littleесли среда исполнения мало эндианна, в противном случае
• Неравенствоorder::littleиorder::big.

Requirements

Template argument requirements

Определения шаблонов в заголовке<boost/endian/conversion.hpp>относятся к различным названным требованиям, детали которых изложены в таблицах в этом подразделе. В этих таблицах<T>является объектом или эталонным типом, поставляемым программой C++, инстанцирующей шаблон;<x>является значением типа (возможно<const>)<T>;<mlx>является изменяемым значением типа<T>.

Примечание:Поскольку существует шаблон функций для<endian_reverse_inplace>, который вызывает<endian_reverse>, только<endian_reverse>требуется для определенного пользователем типа для удовлетворения требований<EndianReversibleInplace>. Хотя определенные пользователем типы не требуются для предоставления функции<endian_reverse_inplace>, это может повысить эффективность. —end note

Customization points for user-defined types (UDTs)

В этом подразделе описаны требования к реализации библиотеки Endian'.

Шаблоны функций библиотеки и No 39, требующие< EndianReversible>, должны выполнять разворот эндианности, если это необходимо, сделав неквалифицированный вызов<endian_reverse()>.

Шаблоны функций библиотеки и No 39, требующие< EndianReversibleInplace>, должны выполнять разворот эндианности, если это необходимо, сделав неквалифицированный вызов<endian_reverse_inplace()>.

См.<example/udt_conversion_example.cpp>для примера определяемого пользователем типа.

Functions

int8_t   endian_reverse(int8_t x) noexcept;
int16_t  endian_reverse(int16_t x) noexcept;
int32_t  endian_reverse(int32_t x) noexcept;
int64_t  endian_reverse(int64_t x) noexcept;
uint8_t  endian_reverse(uint8_t x) noexcept;
uint16_t endian_reverse(uint16_t x) noexcept;
uint32_t endian_reverse(uint32_t x) noexcept;
uint64_t endian_reverse(uint64_t x) noexcept;

Возврат:<x>, с обратным порядком составляющих его байтов.

Замечания:Тип<x>соответствует<EndianReversible>требованиям.

[править]Примечание:Рост. Библиотека Endian не обеспечивает перегрузки для типов стандартных библиотек C++.— конец примечания

template <class EndianReversible>
EndianReversible big_to_native(EndianReversible x) noexcept;

Возвращение:<conditional_reverse<order::big, order::native>(x)>.

template <class EndianReversible>
EndianReversible native_to_big(EndianReversible x) noexcept; 

Возвращение:<conditional_reverse<order::native, order::big>(x)>.

template <class EndianReversible>
EndianReversible little_to_native(EndianReversible x) noexcept; 

Возвращение:<conditional_reverse<order::little, order::native>(x)>.

template <class EndianReversible>
EndianReversible native_to_little(EndianReversible x) noexcept; 

Возвращение:<conditional_reverse<order::native, order::little>(x)>.

template <order O1, order O2, class EndianReversible>
EndianReversible conditional_reverse(EndianReversible x) noexcept; 

Возвращается:<x>, если<O1 == O2,>иначе<endian_reverse(x)>.

Замечания:Должен ли<x>или<endian_reverse(x)>быть возвращен, определяется в момент составления.

template <class EndianReversible>
EndianReversible conditional_reverse(EndianReversible x,
      order order1, order order2) noexcept; 

Возвращение:<order1 == order2 ? x : endian_reverse(x)>.

template <class EndianReversible>
void endian_reverse_inplace(EndianReversible& x) noexcept; 

Эффекты:<x><= endian_reverse(x)>.

template <class EndianReversibleInplace>
void big_to_native_inplace(EndianReversibleInplace& x) noexcept; 

Эффекты:<conditional_reverse_inplace<order::big, order::native>(x)>.

template <class EndianReversibleInplace>
void native_to_big_inplace(EndianReversibleInplace& x) noexcept; 

Эффекты:<conditional_reverse_inplace<order::native, order::big>(x)>.

template <class EndianReversibleInplace>
void little_to_native_inplace(EndianReversibleInplace& x) noexcept; 

Эффекты:<conditional_reverse_inplace<order::little, order::native>(x)>.

template <class EndianReversibleInplace>
void native_to_little_inplace(EndianReversibleInplace& x) noexcept; 

Эффекты:<conditional_reverse_inplace<order::native, order::little>(x)>.

template <order O1, order O2, class EndianReversibleInplace>
void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept; 

Эффекты:Нет, если<O1 == O2,>иначе<endian_reverse_inplace(x)>.

Замечания:Какой эффект применяется, определяется во время компиляции.

template <class EndianReversibleInplace>
void conditional_reverse_inplace(EndianReversibleInplace& x,
     order order1, order order2) noexcept; 

Эффекты:Если<order1 == order2>, то<endian_reverse_inplace(x)>.

FAQ

См. домашнюю страницуEndianFAQ для FAQ в библиотеке.

Почему обеспечиваются функции возврата значений и модификации на месте?

Возвращение результата по значению является стандартной идиомой C и C++ для функций, которые вычисляют значение из аргумента. Функции Modify-in-place обеспечивают более чистый код во многих реальных эндиальных вариантах использования и более эффективны для определенных пользователем типов, которые имеют такие элементы, как данные строк, которые не нуждаются в обращении. Таким образом, обе формы предоставляются.

Почему поддерживаются целые числа точной длины 8, 16, 32 и 64 бита, а не встроенные char, short, int, long, long long и т. д.

Основной вариант использования, переносные файлы или сетевые данные, нуждается в этих стандартных размерах. Использование различных типов платформы значительно ограничивает переносимость как программ, так и данных.

Почему бы не использовать имена Linux (htobe16, htole16, be16toh, le16toh и т.д.)

Эти названия нестандартны и различаются даже между POSIX-подобными операционными системами. Библиотека C++ TS собиралась использовать эти имена, но обнаружила, что они иногда реализовывались как макросы. Поскольку макросы не уважают правила определения и пространства имен, их использование будет очень подвержено ошибкам.

Acknowledgements

Томас Пуверле сыграл важную роль в выявлении и формулировании необходимости поддержки эндианного преобразования как отдельного от эндиановых целых типов. Фил Эндекотт предложил форму возвращающих стоимость подписей. Висенте Ботет и другие рецензенты предложили поддерживать определенные типы пользователей. Общий подход реализации обратного шаблона с использованием std::reverse, предложенный Матиасом Гаунардом. Портативный подход к реализации для 16, 32 и 64-разрядных целых чисел, предложенный Тимофеем, с избеганием неопределенного поведения, предложенного Джованни Пьеро Дереттой, и дальнейшим усовершенствованием, предложенным Пири Яколой. Подход к внедрению встроенных систем для 16, 32 и 64-битных целых чисел, предложенный несколькими рецензентами, и Дэвидом Стоуном, который предоставил свою лицензированную макрос-реализацию Boost, которая стала отправной точкой для<boost/endian/detail/intrinsic.hpp>. Пьер Тальбот предоставил<int8_t endian_reverse()>и замаскировал<endian_reverse_inplace()>реализации.

Последний пересмотр:14 октября 201514 October, 2015[ORIG_END] -->

© Copyright Beman Dawes, 2011, 2013

Распространяется в соответствии с Лицензией на программное обеспечение Boost, версия 1.0. См.www.boost.org/ LICENSE_1_0.txt

Статья Endian Conversion Functions раздела может быть полезна для разработчиков на c++ и boost.

:: Главная :: ::