libs/endian/doc/html/endian.html

   1 <!DOCTYPE html>
   2 <html lang="en">
   3 <head>
   4 <meta charset="UTF-8">
   5 <!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
   6 <meta name="viewport" content="width=device-width, initial-scale=1.0">
   7 <meta name="generator" content="Asciidoctor 1.5.8">
   8 <meta name="author" content="Beman Dawes">
   9 <title>Boost.Endian: The Boost Endian Library</title>
  10 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
  11 <style>
  12 /* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
  13 /* Uncomment @import statement below to use as custom stylesheet */
  14 /*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
  15 article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
  16 audio,canvas,video{display:inline-block}
  17 audio:not([controls]){display:none;height:0}
  18 script{display:none!important}
  19 html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
  20 a{background:transparent}
  21 a:focus{outline:thin dotted}
  22 a:active,a:hover{outline:0}
  23 h1{font-size:2em;margin:.67em 0}
  24 abbr[title]{border-bottom:1px dotted}
  25 b,strong{font-weight:bold}
  26 dfn{font-style:italic}
  27 hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
  28 mark{background:#ff0;color:#000}
  29 code,kbd,pre,samp{font-family:monospace;font-size:1em}
  30 pre{white-space:pre-wrap}
  31 q{quotes:"\201C" "\201D" "\2018" "\2019"}
  32 small{font-size:80%}
  33 sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
  34 sup{top:-.5em}
  35 sub{bottom:-.25em}
  36 img{border:0}
  37 svg:not(:root){overflow:hidden}
  38 figure{margin:0}
  39 fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
  40 legend{border:0;padding:0}
  41 button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
  42 button,input{line-height:normal}
  43 button,select{text-transform:none}
  44 button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
  45 button[disabled],html input[disabled]{cursor:default}
  46 input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
  47 button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
  48 textarea{overflow:auto;vertical-align:top}
  49 table{border-collapse:collapse;border-spacing:0}
  50 *,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
  51 html,body{font-size:100%}
  52 body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
  53 a:hover{cursor:pointer}
  54 img,object,embed{max-width:100%;height:auto}
  55 object,embed{height:100%}
  56 img{-ms-interpolation-mode:bicubic}
  57 .left{float:left!important}
  58 .right{float:right!important}
  59 .text-left{text-align:left!important}
  60 .text-right{text-align:right!important}
  61 .text-center{text-align:center!important}
  62 .text-justify{text-align:justify!important}
  63 .hide{display:none}
  64 img,object,svg{display:inline-block;vertical-align:middle}
  65 textarea{height:auto;min-height:50px}
  66 select{width:100%}
  67 .center{margin-left:auto;margin-right:auto}
  68 .stretch{width:100%}
  69 .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
  70 div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
  71 a{color:#2156a5;text-decoration:underline;line-height:inherit}
  72 a:hover,a:focus{color:#1d4b8f}
  73 a img{border:none}
  74 p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
  75 p aside{font-size:.875em;line-height:1.35;font-style:italic}
  76 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
  77 h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
  78 h1{font-size:2.125em}
  79 h2{font-size:1.6875em}
  80 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
  81 h4,h5{font-size:1.125em}
  82 h6{font-size:1em}
  83 hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
  84 em,i{font-style:italic;line-height:inherit}
  85 strong,b{font-weight:bold;line-height:inherit}
  86 small{font-size:60%;line-height:inherit}
  87 code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
  88 ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
  89 ul,ol{margin-left:1.5em}
  90 ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
  91 ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
  92 ul.square{list-style-type:square}
  93 ul.circle{list-style-type:circle}
  94 ul.disc{list-style-type:disc}
  95 ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
  96 dl dt{margin-bottom:.3125em;font-weight:bold}
  97 dl dd{margin-bottom:1.25em}
  98 abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
  99 abbr{text-transform:none}
 100 blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
 101 blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
 102 blockquote cite::before{content:"\2014 \0020"}
 103 blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
 104 blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
 105 @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
 106 h1{font-size:2.75em}
 107 h2{font-size:2.3125em}
 108 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
 109 h4{font-size:1.4375em}}
 110 table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
 111 table thead,table tfoot{background:#f7f8f7}
 112 table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
 113 table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
 114 table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
 115 table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
 116 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
 117 h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
 118 .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
 119 .clearfix::after,.float-group::after{clear:both}
 120 *:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
 121 *:not(pre)>code.nobreak{word-wrap:normal}
 122 *:not(pre)>code.nowrap{white-space:nowrap}
 123 pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
 124 em em{font-style:normal}
 125 strong strong{font-weight:400}
 126 .keyseq{color:rgba(51,51,51,.8)}
 127 kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
 128 .keyseq kbd:first-child{margin-left:0}
 129 .keyseq kbd:last-child{margin-right:0}
 130 .menuseq,.menuref{color:#000}
 131 .menuseq b:not(.caret),.menuref{font-weight:inherit}
 132 .menuseq{word-spacing:-.02em}
 133 .menuseq b.caret{font-size:1.25em;line-height:.8}
 134 .menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
 135 b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
 136 b.button::before{content:"[";padding:0 3px 0 2px}
 137 b.button::after{content:"]";padding:0 2px 0 3px}
 138 p a>code:hover{color:rgba(0,0,0,.9)}
 139 #header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
 140 #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
 141 #header::after,#content::after,#footnotes::after,#footer::after{clear:both}
 142 #content{margin-top:1.25em}
 143 #content::before{content:none}
 144 #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
 145 #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
 146 #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
 147 #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
 148 #header .details span:first-child{margin-left:-.125em}
 149 #header .details span.email a{color:rgba(0,0,0,.85)}
 150 #header .details br{display:none}
 151 #header .details br+span::before{content:"\00a0\2013\00a0"}
 152 #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
 153 #header .details br+span#revremark::before{content:"\00a0|\00a0"}
 154 #header #revnumber{text-transform:capitalize}
 155 #header #revnumber::after{content:"\00a0"}
 156 #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
 157 #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
 158 #toc>ul{margin-left:.125em}
 159 #toc ul.sectlevel0>li>a{font-style:italic}
 160 #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
 161 #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
 162 #toc li{line-height:1.3334;margin-top:.3334em}
 163 #toc a{text-decoration:none}
 164 #toc a:active{text-decoration:underline}
 165 #toctitle{color:#7a2518;font-size:1.2em}
 166 @media screen and (min-width:768px){#toctitle{font-size:1.375em}
 167 body.toc2{padding-left:15em;padding-right:0}
 168 #toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
 169 #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
 170 #toc.toc2>ul{font-size:.9em;margin-bottom:0}
 171 #toc.toc2 ul ul{margin-left:0;padding-left:1em}
 172 #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
 173 body.toc2.toc-right{padding-left:0;padding-right:15em}
 174 body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
 175 @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
 176 #toc.toc2{width:20em}
 177 #toc.toc2 #toctitle{font-size:1.375em}
 178 #toc.toc2>ul{font-size:.95em}
 179 #toc.toc2 ul ul{padding-left:1.25em}
 180 body.toc2.toc-right{padding-left:0;padding-right:20em}}
 181 #content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
 182 #content #toc>:first-child{margin-top:0}
 183 #content #toc>:last-child{margin-bottom:0}
 184 #footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
 185 #footer-text{color:rgba(255,255,255,.8);line-height:1.44}
 186 #content{margin-bottom:.625em}
 187 .sect1{padding-bottom:.625em}
 188 @media screen and (min-width:768px){#content{margin-bottom:1.25em}
 189 .sect1{padding-bottom:1.25em}}
 190 .sect1:last-child{padding-bottom:0}
 191 .sect1+.sect1{border-top:1px solid #e7e7e9}
 192 #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
 193 #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
 194 #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
 195 #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
 196 #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
 197 .audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
 198 .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
 199 table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
 200 .paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
 201 table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
 202 .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
 203 .admonitionblock>table td.icon{text-align:center;width:80px}
 204 .admonitionblock>table td.icon img{max-width:none}
 205 .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
 206 .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
 207 .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
 208 .exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
 209 .exampleblock>.content>:first-child{margin-top:0}
 210 .exampleblock>.content>:last-child{margin-bottom:0}
 211 .sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
 212 .sidebarblock>:first-child{margin-top:0}
 213 .sidebarblock>:last-child{margin-bottom:0}
 214 .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
 215 .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
 216 .literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
 217 .sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
 218 .literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
 219 @media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}
 220 @media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}
 221 .literalblock pre.nowrap,.literalblock pre.nowrap pre,.listingblock pre.nowrap,.listingblock pre.nowrap pre{white-space:pre;word-wrap:normal}
 222 .literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
 223 .listingblock pre.highlightjs{padding:0}
 224 .listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
 225 .listingblock pre.prettyprint{border-width:0}
 226 .listingblock>.content{position:relative}
 227 .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}
 228 .listingblock:hover code[data-lang]::before{display:block}
 229 .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999}
 230 .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
 231 table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
 232 table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}
 233 table.pyhltable td.code{padding-left:.75em;padding-right:0}
 234 pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #dddddf}
 235 pre.pygments .lineno{display:inline-block;margin-right:.25em}
 236 table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
 237 .quoteblock{margin:0 1em 1.25em 1.5em;display:table}
 238 .quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
 239 .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
 240 .quoteblock blockquote{margin:0;padding:0;border:0}
 241 .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
 242 .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
 243 .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
 244 .verseblock{margin:0 1em 1.25em}
 245 .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
 246 .verseblock pre strong{font-weight:400}
 247 .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
 248 .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
 249 .quoteblock .attribution br,.verseblock .attribution br{display:none}
 250 .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
 251 .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
 252 .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
 253 .quoteblock.abstract{margin:0 1em 1.25em;display:block}
 254 .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
 255 .quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
 256 .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
 257 .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
 258 table.tableblock{max-width:100%;border-collapse:separate}
 259 p.tableblock:last-child{margin-bottom:0}
 260 td.tableblock>.content{margin-bottom:-1.25em}
 261 table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
 262 table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
 263 table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
 264 table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
 265 table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
 266 table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
 267 table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
 268 table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
 269 table.frame-all{border-width:1px}
 270 table.frame-sides{border-width:0 1px}
 271 table.frame-topbot,table.frame-ends{border-width:1px 0}
 272 table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7}
 273 table.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none}
 274 th.halign-left,td.halign-left{text-align:left}
 275 th.halign-right,td.halign-right{text-align:right}
 276 th.halign-center,td.halign-center{text-align:center}
 277 th.valign-top,td.valign-top{vertical-align:top}
 278 th.valign-bottom,td.valign-bottom{vertical-align:bottom}
 279 th.valign-middle,td.valign-middle{vertical-align:middle}
 280 table thead th,table tfoot th{font-weight:bold}
 281 tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
 282 tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
 283 p.tableblock>code:only-child{background:none;padding:0}
 284 p.tableblock{font-size:1em}
 285 td>div.verse{white-space:pre}
 286 ol{margin-left:1.75em}
 287 ul li ol{margin-left:1.5em}
 288 dl dd{margin-left:1.125em}
 289 dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
 290 ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
 291 ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
 292 ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
 293 ul.unstyled,ol.unstyled{margin-left:0}
 294 ul.checklist{margin-left:.625em}
 295 ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
 296 ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
 297 ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
 298 ul.inline>li{margin-left:1.25em}
 299 .unstyled dl dt{font-weight:400;font-style:normal}
 300 ol.arabic{list-style-type:decimal}
 301 ol.decimal{list-style-type:decimal-leading-zero}
 302 ol.loweralpha{list-style-type:lower-alpha}
 303 ol.upperalpha{list-style-type:upper-alpha}
 304 ol.lowerroman{list-style-type:lower-roman}
 305 ol.upperroman{list-style-type:upper-roman}
 306 ol.lowergreek{list-style-type:lower-greek}
 307 .hdlist>table,.colist>table{border:0;background:none}
 308 .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
 309 td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
 310 td.hdlist1{font-weight:bold;padding-bottom:1.25em}
 311 .literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
 312 .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
 313 .colist td:not([class]):first-child img{max-width:none}
 314 .colist td:not([class]):last-child{padding:.25em 0}
 315 .thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
 316 .imageblock.left{margin:.25em .625em 1.25em 0}
 317 .imageblock.right{margin:.25em 0 1.25em .625em}
 318 .imageblock>.title{margin-bottom:0}
 319 .imageblock.thumb,.imageblock.th{border-width:6px}
 320 .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
 321 .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
 322 .image.left{margin-right:.625em}
 323 .image.right{margin-left:.625em}
 324 a.image{text-decoration:none;display:inline-block}
 325 a.image object{pointer-events:none}
 326 sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
 327 sup.footnote a,sup.footnoteref a{text-decoration:none}
 328 sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
 329 #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
 330 #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
 331 #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
 332 #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
 333 #footnotes .footnote:last-of-type{margin-bottom:0}
 334 #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
 335 .gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
 336 .gist .file-data>table td.line-data{width:99%}
 337 div.unbreakable{page-break-inside:avoid}
 338 .big{font-size:larger}
 339 .small{font-size:smaller}
 340 .underline{text-decoration:underline}
 341 .overline{text-decoration:overline}
 342 .line-through{text-decoration:line-through}
 343 .aqua{color:#00bfbf}
 344 .aqua-background{background-color:#00fafa}
 345 .black{color:#000}
 346 .black-background{background-color:#000}
 347 .blue{color:#0000bf}
 348 .blue-background{background-color:#0000fa}
 349 .fuchsia{color:#bf00bf}
 350 .fuchsia-background{background-color:#fa00fa}
 351 .gray{color:#606060}
 352 .gray-background{background-color:#7d7d7d}
 353 .green{color:#006000}
 354 .green-background{background-color:#007d00}
 355 .lime{color:#00bf00}
 356 .lime-background{background-color:#00fa00}
 357 .maroon{color:#600000}
 358 .maroon-background{background-color:#7d0000}
 359 .navy{color:#000060}
 360 .navy-background{background-color:#00007d}
 361 .olive{color:#606000}
 362 .olive-background{background-color:#7d7d00}
 363 .purple{color:#600060}
 364 .purple-background{background-color:#7d007d}
 365 .red{color:#bf0000}
 366 .red-background{background-color:#fa0000}
 367 .silver{color:#909090}
 368 .silver-background{background-color:#bcbcbc}
 369 .teal{color:#006060}
 370 .teal-background{background-color:#007d7d}
 371 .white{color:#bfbfbf}
 372 .white-background{background-color:#fafafa}
 373 .yellow{color:#bfbf00}
 374 .yellow-background{background-color:#fafa00}
 375 span.icon>.fa{cursor:default}
 376 a span.icon>.fa{cursor:inherit}
 377 .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
 378 .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
 379 .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
 380 .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
 381 .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
 382 .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
 383 .conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
 384 .conum[data-value] *{color:#fff!important}
 385 .conum[data-value]+b{display:none}
 386 .conum[data-value]::after{content:attr(data-value)}
 387 pre .conum[data-value]{position:relative;top:-.125em}
 388 b.conum *{color:inherit!important}
 389 .conum:not([data-value]):empty{display:none}
 390 dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
 391 h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
 392 p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
 393 p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
 394 p{margin-bottom:1.25rem}
 395 .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
 396 .exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
 397 .print-only{display:none!important}
 398 @page{margin:1.25cm .75cm}
 399 @media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
 400 html{font-size:80%}
 401 a{color:inherit!important;text-decoration:underline!important}
 402 a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
 403 a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
 404 abbr[title]::after{content:" (" attr(title) ")"}
 405 pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
 406 thead{display:table-header-group}
 407 svg{max-width:100%}
 408 p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
 409 h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
 410 #toc,.sidebarblock,.exampleblock>.content{background:none!important}
 411 #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
 412 body.book #header{text-align:center}
 413 body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
 414 body.book #header .details{border:0!important;display:block;padding:0!important}
 415 body.book #header .details span:first-child{margin-left:0!important}
 416 body.book #header .details br{display:block}
 417 body.book #header .details br+span::before{content:none!important}
 418 body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
 419 body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
 420 .listingblock code[data-lang]::before{display:block}
 421 #footer{padding:0 .9375em}
 422 .hide-on-print{display:none!important}
 423 .print-only{display:block!important}
 424 .hide-for-print{display:none!important}
 425 .show-for-print{display:inherit!important}}
 426 @media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
 427 .sect1{padding:0!important}
 428 .sect1+.sect1{border:0}
 429 #footer{background:none}
 430 #footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
 431 @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
 432 </style>
 433 </head>
 434 <body class="article toc2 toc-left">
 435 <div id="header">
 436 <h1>Boost.Endian: The Boost Endian Library</h1>
 437 <div class="details">
 438 <span id="author" class="author">Beman Dawes</span><br>
 439 </div>
 440 <div id="toc" class="toc2">
 441 <div id="toctitle">Table of Contents</div>
 442 <ul class="sectlevel1">
 443 <li><a href="#overview">Overview</a>
 444 <ul class="sectlevel2">
 445 <li><a href="#overview_abstract">Abstract</a></li>
 446 <li><a href="#overview_endianness">Introduction to endianness</a></li>
 447 <li><a href="#overview_introduction">Introduction to the Boost.Endian library</a></li>
 448 <li><a href="#overview_choosing_between_conversion_functions_buffer_types_and_arithmetic_types">Choosing between conversion functions, buffer types, and arithmetic types</a></li>
 449 <li><a href="#overview_intrinsics">Built-in support for Intrinsics</a></li>
 450 <li><a href="#overview_performance">Performance</a></li>
 451 <li><a href="#overview_faq">Overall FAQ</a></li>
 452 <li><a href="#overview_history">History</a></li>
 453 <li><a href="#overview_compatibility_with_interim_releases">Compatibility with interim releases</a></li>
 454 <li><a href="#overview_cpp03_support">C&#43;&#43;03 support for C&#43;&#43;11 features</a></li>
 455 <li><a href="#overview_future_directions">Future directions</a></li>
 456 <li><a href="#overview_acknowledgements">Acknowledgements</a></li>
 457 </ul>
 458 </li>
 459 <li><a href="#changelog">Revision History</a>
 460 <ul class="sectlevel2">
 461 <li><a href="#overview_changes_in_1_72_0">Changes in 1.72.0</a></li>
 462 <li><a href="#overview_changes_in_1_71_0">Changes in 1.71.0</a></li>
 463 </ul>
 464 </li>
 465 <li><a href="#conversion">Endian Conversion Functions</a>
 466 <ul class="sectlevel2">
 467 <li><a href="#conversion_introduction">Introduction</a></li>
 468 <li><a href="#conversion_reference">Reference</a></li>
 469 <li><a href="#conversion_faq">FAQ</a></li>
 470 <li><a href="#conversion_acknowledgements">Acknowledgements</a></li>
 471 </ul>
 472 </li>
 473 <li><a href="#buffers">Endian Buffer Types</a>
 474 <ul class="sectlevel2">
 475 <li><a href="#buffers_introduction">Introduction</a></li>
 476 <li><a href="#buffers_example">Example</a></li>
 477 <li><a href="#buffers_limitations">Limitations</a></li>
 478 <li><a href="#buffers_feature_set">Feature set</a></li>
 479 <li><a href="#buffers_enums_and_typedefs">Enums and typedefs</a></li>
 480 <li><a href="#buffers_class_template_endian_buffer">Class template <code>endian_buffer</code></a></li>
 481 <li><a href="#buffers_faq">FAQ</a></li>
 482 <li><a href="#buffers_design_considerations_for_boost_endian_buffers">Design considerations for Boost.Endian buffers</a></li>
 483 <li><a href="#buffers_c11">C&#43;&#43;11</a></li>
 484 <li><a href="#buffers_compilation">Compilation</a></li>
 485 </ul>
 486 </li>
 487 <li><a href="#arithmetic">Endian Arithmetic Types</a>
 488 <ul class="sectlevel2">
 489 <li><a href="#arithmetic_introduction">Introduction</a></li>
 490 <li><a href="#arithmetic_example">Example</a></li>
 491 <li><a href="#arithmetic_limitations">Limitations</a></li>
 492 <li><a href="#arithmetic_feature_set">Feature set</a></li>
 493 <li><a href="#arithmetic_enums_and_typedefs">Enums and typedefs</a></li>
 494 <li><a href="#arithmetic_class_template_endian_arithmetic">Class template <code>endian_arithmetic</code></a></li>
 495 <li><a href="#arithmetic_faq">FAQ</a></li>
 496 <li><a href="#arithmetic_design_considerations_for_boost_endian_types">Design considerations for Boost.Endian types</a></li>
 497 <li><a href="#arithmetic_experience">Experience</a></li>
 498 <li><a href="#arithmetic_motivating_use_cases">Motivating use cases</a></li>
 499 <li><a href="#arithmetic_c11">C&#43;&#43;11</a></li>
 500 <li><a href="#arithmetic_compilation">Compilation</a></li>
 501 <li><a href="#arithmetic_acknowledgements">Acknowledgements</a></li>
 502 </ul>
 503 </li>
 504 <li><a href="#choosing">Choosing Approach</a>
 505 <ul class="sectlevel2">
 506 <li><a href="#choosing_introduction">Introduction</a></li>
 507 <li><a href="#choosing_choosing_between_conversion_functions_buffer_types_and_arithmetic_types">Choosing between conversion functions, buffer types, and arithmetic types</a></li>
 508 </ul>
 509 </li>
 510 <li><a href="#appendix_mini_review_topics">Appendix A: Endian Mini-Review</a></li>
 511 <li><a href="#choosing_copyright_and_license">Appendix B: Copyright and License</a></li>
 512 </ul>
 513 </div>
 514 </div>
 515 <div id="content">
 516 <div class="sect1">
 517 <h2 id="overview">Overview</h2>
 518 <div class="sectionbody">
 519 <div class="sect2">
 520 <h3 id="overview_abstract">Abstract</h3>
 521 <div class="paragraph">
 522 <p>Boost.Endian provides facilities to manipulate the
 523 <a href="#overview_endianness">endianness</a> of integers and user-defined types.</p>
 524 </div>
 525 <div class="ulist">
 526 <ul>
 527 <li>
 528 <p>Three approaches to endianness are supported. Each has a long history of
 529 successful use, and each approach has use cases where it is preferred over the
 530 other approaches.</p>
 531 </li>
 532 <li>
 533 <p>Primary uses:</p>
 534 <div class="ulist">
 535 <ul>
 536 <li>
 537 <p>Data portability. The Endian library supports binary data exchange, via
 538 either external media or network transmission, regardless of platform
 539 endianness.</p>
 540 </li>
 541 <li>
 542 <p>Program portability. POSIX-based and Windows-based operating systems
 543 traditionally supply libraries with non-portable functions to perform endian
 544 conversion. There are at least four incompatible sets of functions in common
 545 use. The Endian library is portable across all C&#43;&#43; platforms.</p>
 546 </li>
 547 </ul>
 548 </div>
 549 </li>
 550 <li>
 551 <p>Secondary use: Minimizing data size via sizes and/or alignments not supported
 552 by the standard C&#43;&#43; integer types.</p>
 553 </li>
 554 </ul>
 555 </div>
 556 </div>
 557 <div class="sect2">
 558 <h3 id="overview_endianness">Introduction to endianness</h3>
 559 <div class="paragraph">
 560 <p>Consider the following code:</p>
 561 </div>
 562 <div class="listingblock">
 563 <div class="content">
 564 <pre class="highlight"><code>int16_t i = 0x0102;
 565 FILE * file = fopen("test.bin", "wb"); // binary file!
 566 fwrite(&amp;i, sizeof(int16_t), 1, file);
 567 fclose(file);</code></pre>
 568 </div>
 569 </div>
 570 <div class="paragraph">
 571 <p>On OS X, Linux, or Windows systems with an Intel CPU, a hex dump of the
 572 "test.bin" output file produces:</p>
 573 </div>
 574 <div class="listingblock">
 575 <div class="content">
 576 <pre class="highlight"><code>0201</code></pre>
 577 </div>
 578 </div>
 579 <div class="paragraph">
 580 <p>On OS X systems with a PowerPC CPU, or Solaris systems with a SPARC CPU, a hex
 581 dump of the "test.bin" output file produces:</p>
 582 </div>
 583 <div class="listingblock">
 584 <div class="content">
 585 <pre class="highlight"><code>0102</code></pre>
 586 </div>
 587 </div>
 588 <div class="paragraph">
 589 <p>What&#8217;s happening here is that Intel CPUs order the bytes of an integer with the
 590 least-significant byte first, while SPARC CPUs place the most-significant byte
 591 first. Some CPUs, such as the PowerPC, allow the operating system to choose
 592 which ordering applies.</p>
 593 </div>
 594 <div class="paragraph">
 595 <p>Most-significant-byte-first ordering is traditionally called "big endian"
 596 ordering and least-significant-byte-first is traditionally called
 597 "little-endian" ordering. The names are derived from
 598 <a href="http://en.wikipedia.org/wiki/Jonathan_Swift">Jonathan Swift</a>'s satirical novel
 599 <em><a href="http://en.wikipedia.org/wiki/Gulliver&#8217;s_Travels">Gulliver&#8217;s Travels</a></em>, where
 600 rival kingdoms opened their soft-boiled eggs at different ends.</p>
 601 </div>
 602 <div class="paragraph">
 603 <p>See Wikipedia&#8217;s <a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article for
 604 an extensive discussion of endianness.</p>
 605 </div>
 606 <div class="paragraph">
 607 <p>Programmers can usually ignore endianness, except when reading a core  dump on
 608 little-endian systems. But programmers  have to deal with endianness when
 609 exchanging binary integers and binary floating point values between computer
 610 systems with differing endianness, whether by physical file transfer or over a
 611 network. And programmers may also want to use the library when minimizing either
 612 internal or external data sizes is advantageous.</p>
 613 </div>
 614 </div>
 615 <div class="sect2">
 616 <h3 id="overview_introduction">Introduction to the Boost.Endian library</h3>
 617 <div class="paragraph">
 618 <p>Boost.Endian provides three different approaches to dealing with endianness. All
 619 three approaches support integers and user-define types (UDTs).</p>
 620 </div>
 621 <div class="paragraph">
 622 <p>Each approach has a long history of successful use, and each approach has use
 623 cases where it is preferred to the other approaches.</p>
 624 </div>
 625 <div class="dlist">
 626 <dl>
 627 <dt class="hdlist1"><a href="#conversion">Endian conversion functions</a></dt>
 628 <dd>
 629 <p>The application uses the built-in integer types to hold values, and calls the
 630 provided conversion functions to convert byte ordering as needed. Both mutating
 631 and non-mutating conversions are supplied, and each comes in unconditional and
 632 conditional variants.</p>
 633 </dd>
 634 <dt class="hdlist1"><a href="#buffers">Endian buffer types</a></dt>
 635 <dd>
 636 <p>The application uses the provided endian buffer types to hold values, and
 637 explicitly converts to and from the built-in integer types. Buffer sizes of 8,
 638 16, 24, 32, 40, 48, 56, and 64 bits (i.e. 1, 2, 3, 4, 5, 6, 7, and 8 bytes) are
 639 provided. Unaligned integer buffer types are provided for all sizes, and aligned
 640 buffer types are provided for 16, 32, and 64-bit sizes. The provided specific
 641 types are typedefs for a generic class template that may be used directly for
 642 less common use cases.</p>
 643 </dd>
 644 <dt class="hdlist1"><a href="#arithmetic">Endian arithmetic types</a></dt>
 645 <dd>
 646 <p>The application uses the provided endian arithmetic types, which supply the same
 647 operations as the built-in C&#43;&#43; arithmetic types. All conversions are implicit.
 648 Arithmetic sizes of 8, 16, 24, 32, 40, 48, 56, and 64 bits (i.e. 1, 2, 3, 4, 5,
 649 6, 7, and 8 bytes) are provided. Unaligned integer types are provided for all
 650 sizes and aligned arithmetic types are provided for 16, 32, and 64-bit sizes.
 651 The provided specific types are typedefs for a generic class template that may
 652 be used directly in generic code of for less common use cases.</p>
 653 </dd>
 654 </dl>
 655 </div>
 656 <div class="paragraph">
 657 <p>Boost Endian is a header-only library. C&#43;&#43;11 features affecting interfaces,
 658 such as <code>noexcept</code>, are  used only if available. See
 659 <a href="#overview_cpp03_support">C&#43;&#43;03 support for C&#43;&#43;11 features</a> for details.</p>
 660 </div>
 661 </div>
 662 <div class="sect2">
 663 <h3 id="overview_choosing_between_conversion_functions_buffer_types_and_arithmetic_types">Choosing between conversion functions, buffer types, and arithmetic types</h3>
 664 <div class="paragraph">
 665 <p>This section has been moved to its own <a href="#choosing">Choosing the Approach</a> page.</p>
 666 </div>
 667 </div>
 668 <div class="sect2">
 669 <h3 id="overview_intrinsics">Built-in support for Intrinsics</h3>
 670 <div class="paragraph">
 671 <p>Most compilers, including GCC, Clang, and Visual C&#43;&#43;, supply  built-in support
 672 for byte swapping intrinsics. The Endian library uses these intrinsics when
 673 available since they may result in smaller and faster generated code,
 674 particularly for optimized builds.</p>
 675 </div>
 676 <div class="paragraph">
 677 <p>Defining the macro <code>BOOST_ENDIAN_NO_INTRINSICS</code> will suppress use of the
 678 intrinsics. This is useful when a compiler has no intrinsic support or fails to
 679 locate the appropriate header, perhaps because it is an older release or has
 680 very limited supporting libraries.</p>
 681 </div>
 682 <div class="paragraph">
 683 <p>The macro <code>BOOST_ENDIAN_INTRINSIC_MSG</code> is defined as either
 684 <code>"no byte swap intrinsics"</code> or a string describing the particular set of
 685 intrinsics being used. This is useful for eliminating missing intrinsics as a
 686 source of performance issues.</p>
 687 </div>
 688 </div>
 689 <div class="sect2">
 690 <h3 id="overview_performance">Performance</h3>
 691 <div class="paragraph">
 692 <p>Consider this problem:</p>
 693 </div>
 694 <div class="sect3">
 695 <h4 id="overview_example_1">Example 1</h4>
 696 <div class="paragraph">
 697 <p>Add 100 to a big endian value in a file, then write the result to a file</p>
 698 </div>
 699 <table class="tableblock frame-all grid-all stretch">
 700 <colgroup>
 701 <col style="width: 50%;">
 702 <col style="width: 50%;">
 703 </colgroup>
 704 <thead>
 705 <tr>
 706 <th class="tableblock halign-left valign-top">Endian arithmetic type approach</th>
 707 <th class="tableblock halign-left valign-top">Endian conversion function approach</th>
 708 </tr>
 709 </thead>
 710 <tbody>
 711 <tr>
 712 <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
 713 <div class="content">
 714 <pre>big_int32_at x;
 715
 716 ... read into x from a file ...
 717
 718
 719 x += 100;
 720
 721
 722 ... write x to a file ...</pre>
 723 </div>
 724 </div></div></td>
 725 <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
 726 <div class="content">
 727 <pre>int32_t x;
 728
 729 ... read into x from a file ...
 730
 731 big_to_native_inplace(x);
 732 x += 100;
 733 native_to_big_inplace(x);
 734
 735 ... write x to a file ...</pre>
 736 </div>
 737 </div></div></td>
 738 </tr>
 739 </tbody>
 740 </table>
 741 <div class="paragraph">
 742 <p><strong>There will be no performance difference between the two approaches in optimized
 743 builds, regardless of the native endianness of the machine.</strong> That&#8217;s because
 744 optimizing compilers will generate exactly the same code for each. That
 745 conclusion was confirmed by studying the generated assembly code for GCC and
 746 Visual C&#43;&#43;. Furthermore, time spent doing I/O will determine the speed of this
 747 application.</p>
 748 </div>
 749 <div class="paragraph">
 750 <p>Now consider a slightly different problem:</p>
 751 </div>
 752 </div>
 753 <div class="sect3">
 754 <h4 id="overview_example_2">Example 2</h4>
 755 <div class="paragraph">
 756 <p>Add a million values to a big endian value in a file, then write the result to a
 757 file</p>
 758 </div>
 759 <table class="tableblock frame-all grid-all stretch">
 760 <colgroup>
 761 <col style="width: 50%;">
 762 <col style="width: 50%;">
 763 </colgroup>
 764 <thead>
 765 <tr>
 766 <th class="tableblock halign-left valign-top">Endian arithmetic type approach</th>
 767 <th class="tableblock halign-left valign-top">Endian conversion function approach</th>
 768 </tr>
 769 </thead>
 770 <tbody>
 771 <tr>
 772 <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
 773 <div class="content">
 774 <pre>big_int32_at x;
 775
 776 ... read into x from a file ...
 777
 778
 779
 780 for (int32_t i = 0; i &lt; 1000000; ++i)
 781   x += i;
 782
 783
 784
 785 ... write x to a file ...</pre>
 786 </div>
 787 </div></div></td>
 788 <td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
 789 <div class="content">
 790 <pre>int32_t x;
 791
 792 ... read into x from a file ...
 793
 794 big_to_native_inplace(x);
 795
 796 for (int32_t i = 0; i &lt; 1000000; ++i)
 797   x += i;
 798
 799 native_to_big_inplace(x);
 800
 801 ... write x to a file ...</pre>
 802 </div>
 803 </div></div></td>
 804 </tr>
 805 </tbody>
 806 </table>
 807 <div class="paragraph">
 808 <p>With the Endian arithmetic approach, on little endian platforms an implicit
 809 conversion from and then back to big endian is done inside the loop. With the
 810 Endian conversion function approach, the user has ensured the conversions are
 811 done outside the loop, so the code may run more quickly on little endian
 812 platforms.</p>
 813 </div>
 814 </div>
 815 <div class="sect3">
 816 <h4 id="overview_timings">Timings</h4>
 817 <div class="paragraph">
 818 <p>These tests were run against release builds on a circa 2012 4-core little endian
 819 X64 Intel Core i5-3570K CPU @ 3.40GHz under Windows 7.</p>
 820 </div>
 821 <div class="admonitionblock caution">
 822 <table>
 823 <tr>
 824 <td class="icon">
 825 <div class="title">Caution</div>
 826 </td>
 827 <td class="content">
 828 The Windows CPU timer has very high granularity. Repeated runs of the
 829 same tests often yield considerably different results.
 830 </td>
 831 </tr>
 832 </table>
 833 </div>
 834 <div class="paragraph">
 835 <p>See <code>test/loop_time_test.cpp</code> for the actual code and <code>benchmark/Jamfile.v2</code> for
 836 the build setup.</p>
 837 </div>
 838 <div class="sect4">
 839 <h5 id="overview_gnu_c_version_4_8_2_on_linux_virtual_machine">GNU C++ version 4.8.2 on Linux virtual machine</h5>
 840 <div class="paragraph">
 841 <p>Iterations: 10'000'000'000, Intrinsics: <code>__builtin_bswap16</code>, etc.</p>
 842 </div>
 843 <table class="tableblock frame-all grid-all stretch">
 844 <colgroup>
 845 <col style="width: 33.3333%;">
 846 <col style="width: 33.3333%;">
 847 <col style="width: 33.3334%;">
 848 </colgroup>
 849 <thead>
 850 <tr>
 851 <th class="tableblock halign-left valign-top">Test Case</th>
 852 <th class="tableblock halign-left valign-top">Endian arithmetic type</th>
 853 <th class="tableblock halign-left valign-top">Endian conversion function</th>
 854 </tr>
 855 </thead>
 856 <tbody>
 857 <tr>
 858 <td class="tableblock halign-left valign-top"><p class="tableblock">16-bit aligned big endian</p></td>
 859 <td class="tableblock halign-left valign-top"><p class="tableblock">8.46 s</p></td>
 860 <td class="tableblock halign-left valign-top"><p class="tableblock">5.28 s</p></td>
 861 </tr>
 862 <tr>
 863 <td class="tableblock halign-left valign-top"><p class="tableblock">16-bit aligned little endian</p></td>
 864 <td class="tableblock halign-left valign-top"><p class="tableblock">5.28 s</p></td>
 865 <td class="tableblock halign-left valign-top"><p class="tableblock">5.22 s</p></td>
 866 </tr>
 867 <tr>
 868 <td class="tableblock halign-left valign-top"><p class="tableblock">32-bit aligned big endian</p></td>
 869 <td class="tableblock halign-left valign-top"><p class="tableblock">8.40 s</p></td>
 870 <td class="tableblock halign-left valign-top"><p class="tableblock">2.11 s</p></td>
 871 </tr>
 872 <tr>
 873 <td class="tableblock halign-left valign-top"><p class="tableblock">32-bit aligned little endian</p></td>
 874 <td class="tableblock halign-left valign-top"><p class="tableblock">2.11 s</p></td>
 875 <td class="tableblock halign-left valign-top"><p class="tableblock">2.10 s</p></td>
 876 </tr>
 877 <tr>
 878 <td class="tableblock halign-left valign-top"><p class="tableblock">64-bit aligned big endian</p></td>
 879 <td class="tableblock halign-left valign-top"><p class="tableblock">14.02 s</p></td>
 880 <td class="tableblock halign-left valign-top"><p class="tableblock">3.10 s</p></td>
 881 </tr>
 882 <tr>
 883 <td class="tableblock halign-left valign-top"><p class="tableblock">64-bit aligned little endian</p></td>
 884 <td class="tableblock halign-left valign-top"><p class="tableblock">3.00 s</p></td>
 885 <td class="tableblock halign-left valign-top"><p class="tableblock">3.03 s</p></td>
 886 </tr>
 887 </tbody>
 888 </table>
 889 </div>
 890 <div class="sect4">
 891 <h5 id="overview_microsoft_visual_c_version_14_0">Microsoft Visual C++ version 14.0</h5>
 892 <div class="paragraph">
 893 <p>Iterations: 10'000'000'000, Intrinsics: <code>&lt;cstdlib&gt;</code> <code>_byteswap_ushort</code>, etc.</p>
 894 </div>
 895 <table class="tableblock frame-all grid-all stretch">
 896 <colgroup>
 897 <col style="width: 33.3333%;">
 898 <col style="width: 33.3333%;">
 899 <col style="width: 33.3334%;">
 900 </colgroup>
 901 <thead>
 902 <tr>
 903 <th class="tableblock halign-left valign-top">Test Case</th>
 904 <th class="tableblock halign-left valign-top">Endian arithmetic type</th>
 905 <th class="tableblock halign-left valign-top">Endian conversion function</th>
 906 </tr>
 907 </thead>
 908 <tbody>
 909 <tr>
 910 <td class="tableblock halign-left valign-top"><p class="tableblock">16-bit aligned big endian</p></td>
 911 <td class="tableblock halign-left valign-top"><p class="tableblock">8.27 s</p></td>
 912 <td class="tableblock halign-left valign-top"><p class="tableblock">5.26 s</p></td>
 913 </tr>
 914 <tr>
 915 <td class="tableblock halign-left valign-top"><p class="tableblock">16-bit aligned little endian</p></td>
 916 <td class="tableblock halign-left valign-top"><p class="tableblock">5.29 s</p></td>
 917 <td class="tableblock halign-left valign-top"><p class="tableblock">5.32 s</p></td>
 918 </tr>
 919 <tr>
 920 <td class="tableblock halign-left valign-top"><p class="tableblock">32-bit aligned big endian</p></td>
 921 <td class="tableblock halign-left valign-top"><p class="tableblock">8.36 s</p></td>
 922 <td class="tableblock halign-left valign-top"><p class="tableblock">5.24 s</p></td>
 923 </tr>
 924 <tr>
 925 <td class="tableblock halign-left valign-top"><p class="tableblock">32-bit aligned little endian</p></td>
 926 <td class="tableblock halign-left valign-top"><p class="tableblock">5.24 s</p></td>
 927 <td class="tableblock halign-left valign-top"><p class="tableblock">5.24 s</p></td>
 928 </tr>
 929 <tr>
 930 <td class="tableblock halign-left valign-top"><p class="tableblock">64-bit aligned big endian</p></td>
 931 <td class="tableblock halign-left valign-top"><p class="tableblock">13.65 s</p></td>
 932 <td class="tableblock halign-left valign-top"><p class="tableblock">3.34 s</p></td>
 933 </tr>
 934 <tr>
 935 <td class="tableblock halign-left valign-top"><p class="tableblock">64-bit aligned little endian</p></td>
 936 <td class="tableblock halign-left valign-top"><p class="tableblock">3.35 s</p></td>
 937 <td class="tableblock halign-left valign-top"><p class="tableblock">2.73 s</p></td>
 938 </tr>
 939 </tbody>
 940 </table>
 941 </div>
 942 </div>
 943 </div>
 944 <div class="sect2">
 945 <h3 id="overview_faq">Overall FAQ</h3>
 946 <div class="dlist">
 947 <dl>
 948 <dt class="hdlist1">Is the implementation header only?</dt>
 949 <dd>
 950 <p>Yes.</p>
 951 </dd>
 952 <dt class="hdlist1">Are C&#43;&#43;03 compilers supported?</dt>
 953 <dd>
 954 <p>Yes.</p>
 955 </dd>
 956 <dt class="hdlist1">Does the implementation use compiler intrinsic built-in byte swapping?</dt>
 957 <dd>
 958 <p>Yes, if available. See <a href="#overview_intrinsics">Intrinsic built-in support</a>.</p>
 959 </dd>
 960 <dt class="hdlist1">Why bother with endianness?</dt>
 961 <dd>
 962 <p>Binary data portability is the primary use case.</p>
 963 </dd>
 964 <dt class="hdlist1">Does endianness have any uses outside of portable binary file or network I/O formats?</dt>
 965 <dd>
 966 <p>Using the unaligned integer types with a size tailored to the application&#8217;s
 967 needs is a minor secondary use that saves internal or external memory space. For
 968 example, using <code>big_int40_buf_t</code> or <code>big_int40_t</code> in a large array saves a lot
 969 of space compared to one of the 64-bit types.</p>
 970 </dd>
 971 <dt class="hdlist1">Why bother with binary I/O? Why not just use C&#43;&#43; Standard Library stream inserters and extractors?</dt>
 972 <dd>
 973 <div class="ulist">
 974 <ul>
 975 <li>
 976 <p>Data interchange formats often specify binary integer data. Binary integer
 977 data is smaller and therefore I/O is faster and file sizes are smaller. Transfer
 978 between systems is less expensive.</p>
 979 </li>
 980 <li>
 981 <p>Furthermore, binary integer data is of fixed size, and so fixed-size disk
 982 records are possible without padding, easing sorting and allowing random access.</p>
 983 </li>
 984 <li>
 985 <p>Disadvantages, such as the inability to use text utilities on the resulting
 986 files, limit usefulness to applications where the binary I/O advantages are
 987 paramount.</p>
 988 </li>
 989 </ul>
 990 </div>
 991 </dd>
 992 <dt class="hdlist1">Which is better, big-endian or little-endian?</dt>
 993 <dd>
 994 <p>Big-endian tends to be preferred in a networking environment and is a bit more
 995 of an industry standard, but little-endian may be preferred for applications
 996 that run primarily on x86, x86-64, and other little-endian CPU&#8217;s. The
 997 <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> article gives more pros and cons.</p>
 998 </dd>
 999 <dt class="hdlist1">Why are only big and little native endianness supported?</dt>
1000 <dd>
1001 <p>These are the only endian schemes that have any practical value today. PDP-11
1002 and the other middle endian approaches are interesting  curiosities but have no
1003 relevance for today&#8217;s C&#43;&#43; developers. The same is true for architectures that
1004 allow runtime endianness switching. The
1005 <a href="#conversion_native_order_specification">specification for native ordering</a> has
1006 been carefully crafted to allow support for such orderings in the future, should
1007 the need arise. Thanks to Howard Hinnant for suggesting this.</p>
1008 </dd>
1009 <dt class="hdlist1">Why do both the buffer and arithmetic types exist?</dt>
1010 <dd>
1011 <p>Conversions in the buffer types are explicit. Conversions in the arithmetic
1012 types are implicit. This fundamental difference is a deliberate design feature
1013 that would be lost if the inheritance hierarchy were collapsed.
1014 The original design provided only arithmetic types. Buffer types were requested
1015 during formal review by those wishing total control over when conversion occurs.
1016 They also felt that buffer types would be less likely to be misused by
1017 maintenance programmers not familiar with the implications of performing a lot
1018 of integer operations on the endian arithmetic integer types.</p>
1019 </dd>
1020 <dt class="hdlist1">What is gained by using the buffer types rather than always just using the arithmetic types?</dt>
1021 <dd>
1022 <p>Assurance that hidden conversions are not performed. This is of overriding
1023 importance to users concerned about achieving the ultimate in terms of speed.
1024 "Always just using the arithmetic types" is fine for other users. When the
1025 ultimate in speed needs to be ensured, the arithmetic types can be used in the
1026 same design patterns or idioms that would be used for buffer types, resulting in
1027 the same code being generated for either types.</p>
1028 </dd>
1029 <dt class="hdlist1">What are the limitations of integer support?</dt>
1030 <dd>
1031 <p>Tests have only been performed on machines that  use two&#8217;s complement
1032 arithmetic. The Endian conversion functions only support 16, 32, and 64-bit
1033 aligned integers. The endian types only support 8, 16, 24, 32, 40, 48, 56, and
1034 64-bit unaligned integers, and 8, 16, 32, and 64-bit aligned integers.</p>
1035 </dd>
1036 <dt class="hdlist1">Why is there no floating point support?</dt>
1037 <dd>
1038 <p>An attempt was made to support four-byte <code>float</code>s and eight-byte
1039 <code>double</code>s, limited to
1040 <a href="http://en.wikipedia.org/wiki/IEEE_floating_point">IEEE 754</a> (also known as
1041 ISO/IEC/IEEE 60559) floating point and further limited to systems where floating
1042 point endianness does not differ from integer endianness. Even with those
1043 limitations, support for floating point types was not reliable and was removed.
1044 For example, simply reversing the endianness of a floating point number can
1045 result in a signaling-NAN. For all practical purposes, binary serialization and
1046 endianness for integers are one and the same problem. That is not true for
1047 floating point numbers, so binary serialization interfaces and formats for
1048 floating point does not fit well in an endian-based library.</p>
1049 </dd>
1050 </dl>
1051 </div>
1052 </div>
1053 <div class="sect2">
1054 <h3 id="overview_history">History</h3>
1055 <div class="sect3">
1056 <h4 id="overview_changes_requested_by_formal_review">Changes requested by formal review</h4>
1057 <div class="paragraph">
1058 <p>The library was reworked from top to bottom to accommodate changes requested
1059 during the formal review. See <a href="#appendix_mini_review_topics">Mini-Review</a>
1060 page for details.</p>
1061 </div>
1062 </div>
1063 <div class="sect3">
1064 <h4 id="overview_other_changes_since_formal_review">Other changes since formal review</h4>
1065 <div class="ulist">
1066 <ul>
1067 <li>
1068 <p>Header <code>boost/endian/endian.hpp</code> has been renamed to
1069 <code>boost/endian/arithmetic.hpp</code>. Headers
1070 <code>boost/endian/conversion.hpp</code> and <code>boost/endian/buffers.hpp</code> have been added.
1071 Infrastructure file names were changed accordingly.</p>
1072 </li>
1073 <li>
1074 <p>The endian arithmetic type aliases have been renamed, using a naming pattern
1075 that is consistent for both integer and floating point, and a consistent set of
1076 aliases supplied for the endian buffer types.</p>
1077 </li>
1078 <li>
1079 <p>The unaligned-type alias names still have the <code>_t</code> suffix, but the
1080 aligned-type alias names now have an <code>_at</code> suffix.</p>
1081 </li>
1082 <li>
1083 <p><code>endian_reverse()</code> overloads for <code>int8_t</code> and <code>uint8_t</code> have been added for
1084 improved generality. (Pierre Talbot)</p>
1085 </li>
1086 <li>
1087 <p>Overloads of <code>endian_reverse_inplace()</code> have been replaced with a single
1088 <code>endian_reverse_inplace()</code> template. (Pierre Talbot)</p>
1089 </li>
1090 <li>
1091 <p>For X86 and X64 architectures, which permit unaligned loads and stores,
1092 unaligned little endian buffer and arithmetic types use regular loads and
1093 stores when the size is exact. This makes unaligned little endian buffer and
1094 arithmetic types significantly more efficient on these architectures. (Jeremy
1095 Maitin-Shepard)</p>
1096 </li>
1097 <li>
1098 <p>C&#43;&#43;11 features affecting interfaces, such as <code>noexcept</code>, are now used.
1099 C&#43;&#43;03 compilers are still supported.</p>
1100 </li>
1101 <li>
1102 <p>Acknowledgements have been updated.</p>
1103 </li>
1104 </ul>
1105 </div>
1106 </div>
1107 </div>
1108 <div class="sect2">
1109 <h3 id="overview_compatibility_with_interim_releases">Compatibility with interim releases</h3>
1110 <div class="paragraph">
1111 <p>Prior to the official Boost release, class template <code>endian_arithmetic</code> has been
1112 used for a decade or more with the same functionality but under the name
1113 <code>endian</code>. Other names also changed in the official release. If the macro
1114 <code>BOOST_ENDIAN_DEPRECATED_NAMES</code> is defined, those old now deprecated names are
1115 still supported. However, the class template <code>endian</code> name is only provided for
1116 compilers supporting C&#43;&#43;11 template aliases. For C&#43;&#43;03 compilers, the name
1117 will have to be changed to <code>endian_arithmetic</code>.</p>
1118 </div>
1119 <div class="paragraph">
1120 <p>To support backward header compatibility, deprecated header
1121 <code>boost/endian/endian.hpp</code> forwards to <code>boost/endian/arithmetic.hpp</code>. It requires
1122 <code>BOOST_ENDIAN_DEPRECATED_NAMES</code> be defined. It should only be used while
1123 transitioning to the official Boost release of the library as it will be removed
1124 in some future release.</p>
1125 </div>
1126 </div>
1127 <div class="sect2">
1128 <h3 id="overview_cpp03_support">C&#43;&#43;03 support for C&#43;&#43;11 features</h3>
1129 <table class="tableblock frame-all grid-all stretch">
1130 <colgroup>
1131 <col style="width: 50%;">
1132 <col style="width: 50%;">
1133 </colgroup>
1134 <thead>
1135 <tr>
1136 <th class="tableblock halign-left valign-top">C&#43;&#43;11 Feature</th>
1137 <th class="tableblock halign-left valign-top">Action with C&#43;&#43;03 Compilers</th>
1138 </tr>
1139 </thead>
1140 <tbody>
1141 <tr>
1142 <td class="tableblock halign-left valign-top"><p class="tableblock">Scoped enums</p></td>
1143 <td class="tableblock halign-left valign-top"><p class="tableblock">Uses header
1144 <a href="http://www.boost.org/libs/core/doc/html/core/scoped_enum.html">boost/core/scoped_enum.hpp</a>
1145 to emulate C&#43;&#43;11 scoped enums.</p></td>
1146 </tr>
1147 <tr>
1148 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>noexcept</code></p></td>
1149 <td class="tableblock halign-left valign-top"><p class="tableblock">Uses <code>BOOST_NOEXCEPT</code> macro, which is defined as null for compilers not
1150 supporting this C&#43;&#43;11 feature.</p></td>
1151 </tr>
1152 <tr>
1153 <td class="tableblock halign-left valign-top"><p class="tableblock">C&#43;&#43;11 PODs
1154 (<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2342.htm">N2342</a>)</p></td>
1155 <td class="tableblock halign-left valign-top"><p class="tableblock">Takes advantage of C&#43;&#43;03 compilers that relax C&#43;&#43;03 POD rules, but see
1156 Limitations <a href="#buffers_limitations">here</a> and <a href="#arithmetic_limitations">here</a>.
1157 Also see macros for explicit POD control <a href="#buffers_compilation">here</a> and
1158 <a href="#arithmetic_compilation">here</a></p></td>
1159 </tr>
1160 </tbody>
1161 </table>
1162 </div>
1163 <div class="sect2">
1164 <h3 id="overview_future_directions">Future directions</h3>
1165 <div class="dlist">
1166 <dl>
1167 <dt class="hdlist1">Standardization.</dt>
1168 <dd>
1169 <p>The plan is to submit Boost.Endian to the C&#43;&#43; standards committee for possible
1170 inclusion in a Technical Specification or the C&#43;&#43; standard itself.</p>
1171 </dd>
1172 <dt class="hdlist1">Specializations for <code>numeric_limits</code>.</dt>
1173 <dd>
1174 <p>Roger Leigh requested that all <code>boost::endian</code> types provide <code>numeric_limits</code>
1175 specializations.
1176 See <a href="https://github.com/boostorg/endian/issues/4">GitHub issue 4</a>.</p>
1177 </dd>
1178 <dt class="hdlist1">Character buffer support.</dt>
1179 <dd>
1180 <p>Peter Dimov pointed out during the mini-review that getting and setting basic
1181 arithmetic types (or <code>&lt;cstdint&gt;</code> equivalents) from/to an offset into an array of
1182 unsigned char is a common need. See
1183 <a href="http://lists.boost.org/Archives/boost/2015/01/219574.php">Boost.Endian
1184 mini-review posting</a>.</p>
1185 </dd>
1186 <dt class="hdlist1">Out-of-range detection.</dt>
1187 <dd>
1188 <p>Peter Dimov pointed suggested during the mini-review that throwing an exception
1189 on buffer values being out-of-range might be desirable. See the end of
1190 <a href="http://lists.boost.org/Archives/boost/2015/01/219659.php">this posting</a> and
1191 subsequent replies.</p>
1192 </dd>
1193 </dl>
1194 </div>
1195 </div>
1196 <div class="sect2">
1197 <h3 id="overview_acknowledgements">Acknowledgements</h3>
1198 <div class="paragraph">
1199 <p>Comments and suggestions were received from Adder, Benaka Moorthi, Christopher
1200 Kohlhoff, Cliff Green, Daniel James, Dave Handley, Gennaro Proto, Giovanni Piero
1201 Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Howard Hinnant, Jason Newton,
1202 Jeff Flinn, Jeremy Maitin-Shepard, John Filo, John Maddock, Kim Barrett, Marsh
1203 Ray, Martin Bonner, Mathias Gaunard, Matias Capeletto, Neil Mayhew, Nevin Liber,
1204 Olaf van der Spek, Paul Bristow, Peter Dimov, Pierre Talbot, Phil Endecott,
1205 Philip Bennefall, Pyry Jahkola, Rene Rivera, Robert Stewart, Roger Leigh, Roland
1206 Schwarz, Scott McMurray, Sebastian Redl, Tim Blechmann, Tim Moore, tymofey,
1207 Tomas Puverle, Vincente Botet, Yuval Ronen and Vitaly Budovsk. Apologies if
1208 anyone has been missed.</p>
1209 </div>
1210 <div class="paragraph">
1211 <p>The documentation was converted into Asciidoc format by Glen Fernandes.</p>
1212 </div>
1213 </div>
1214 </div>
1215 </div>
1216 <div class="sect1">
1217 <h2 id="changelog">Revision History</h2>
1218 <div class="sectionbody">
1219 <div class="sect2">
1220 <h3 id="overview_changes_in_1_72_0">Changes in 1.72.0</h3>
1221 <div class="ulist">
1222 <ul>
1223 <li>
1224 <p>Made <code>endian_reverse</code>, <code>conditional_reverse</code> and <code>*_to_*</code> <code>constexpr</code>
1225 on GCC and Clang</p>
1226 </li>
1227 <li>
1228 <p>Added convenience load and store functions</p>
1229 </li>
1230 <li>
1231 <p>Added floating point convenience typedefs</p>
1232 </li>
1233 <li>
1234 <p>Added a non-const overload of <code>data()</code>; changed its return type to <code>unsigned char*</code></p>
1235 </li>
1236 <li>
1237 <p>Added <code>__int128</code> support to <code>endian_reverse</code> when available</p>
1238 </li>
1239 <li>
1240 <p>Added a convenience header <code>boost/endian.hpp</code></p>
1241 </li>
1242 </ul>
1243 </div>
1244 </div>
1245 <div class="sect2">
1246 <h3 id="overview_changes_in_1_71_0">Changes in 1.71.0</h3>
1247 <div class="ulist">
1248 <ul>
1249 <li>
1250 <p>Clarified requirements on the value type template parameter</p>
1251 </li>
1252 <li>
1253 <p>Added support for <code>float</code> and <code>double</code></p>
1254 </li>
1255 <li>
1256 <p>Added <code>endian_load</code>, <code>endian_store</code></p>
1257 </li>
1258 <li>
1259 <p>Updated <code>endian_reverse</code> to correctly support all non-<code>bool</code> integral types</p>
1260 </li>
1261 <li>
1262 <p>Moved deprecated names to the deprecated header <code>endian.hpp</code></p>
1263 </li>
1264 </ul>
1265 </div>
1266 </div>
1267 </div>
1268 </div>
1269 <div class="sect1">
1270 <h2 id="conversion">Endian Conversion Functions</h2>
1271 <div class="sectionbody">
1272 <div class="sect2">
1273 <h3 id="conversion_introduction">Introduction</h3>
1274 <div class="paragraph">
1275 <p>Header <code>boost/endian/conversion.hpp</code> provides byte order reversal and conversion
1276 functions that convert objects of the built-in integer types between native,
1277 big, or little endian byte ordering. User defined types are also supported.</p>
1278 </div>
1279 </div>
1280 <div class="sect2">
1281 <h3 id="conversion_reference">Reference</h3>
1282 <div class="paragraph">
1283 <p>Functions are implemented <code>inline</code> if appropriate. For C&#43;&#43;03 compilers,
1284 <code>noexcept</code> is elided. Boost scoped enum emulation is used so that the library
1285 still works for compilers that do not support scoped enums.</p>
1286 </div>
1287 <div class="sect3">
1288 <h4 id="conversion_definitions">Definitions</h4>
1289 <div class="paragraph">
1290 <p><strong>Endianness</strong> refers to the ordering of bytes within internal or external
1291 integers and other arithmetic data. Most-significant byte first is called
1292 <strong>big endian</strong> ordering. Least-significant byte first is called
1293 <strong>little endian</strong> ordering. Other orderings are possible and some CPU
1294 architectures support both big and little ordering.</p>
1295 </div>
1296 <div class="admonitionblock note">
1297 <table>
1298 <tr>
1299 <td class="icon">
1300 <div class="title">Note</div>
1301 </td>
1302 <td class="content">
1303 The names are derived from
1304 <a href="http://en.wikipedia.org/wiki/Jonathan_Swift">Jonathan Swift</a>'s satirical novel
1305 <em><a href="http://en.wikipedia.org/wiki/Gulliver&#8217;s_Travels">Gulliver&#8217;s Travels</a></em>, where
1306 rival kingdoms opened their soft-boiled eggs at different ends. Wikipedia has an
1307 extensive description of <a href="https://en.wikipedia.org/wiki/Endianness">Endianness</a>.
1308 </td>
1309 </tr>
1310 </table>
1311 </div>
1312 <div class="paragraph">
1313 <p>The standard integral types (C&#43;&#43;std 3.9.1) except <code>bool</code> are collectively
1314 called the <strong>endian types</strong>.</p>
1315 </div>
1316 </div>
1317 <div class="sect3">
1318 <h4 id="conversion_header_boostendianconversion_hpp_synopsis">Header <code>&lt;boost/endian/conversion.hpp&gt;</code> Synopsis</h4>
1319 <div class="listingblock">
1320 <div class="content">
1321 <pre class="highlight"><code>#define BOOST_ENDIAN_INTRINSIC_MSG \
1322    &#8220;message describing presence or absence of intrinsics&#8221;
1323
1324 namespace boost
1325 {
1326 namespace endian
1327 {
1328   enum class order
1329   {
1330     native = <code>see below</code>,
1331     big    = <code>see below</code>,
1332     little = <code>see below</code>,
1333   };
1334
1335   // Byte reversal functions
1336
1337   template &lt;class Endian&gt;
1338     Endian endian_reverse(Endian x) noexcept;
1339
1340   template &lt;class EndianReversible&gt;
1341     EndianReversible big_to_native(EndianReversible x) noexcept;
1342   template &lt;class EndianReversible&gt;
1343     EndianReversible native_to_big(EndianReversible x) noexcept;
1344   template &lt;class EndianReversible&gt;
1345     EndianReversible little_to_native(EndianReversible x) noexcept;
1346   template &lt;class EndianReversible&gt;
1347     EndianReversible native_to_little(EndianReversible x) noexcept;
1348
1349   template &lt;order O1, order O2, class EndianReversible&gt;
1350     EndianReversible conditional_reverse(EndianReversible x) noexcept;
1351   template &lt;class EndianReversible&gt;
1352     EndianReversible conditional_reverse(EndianReversible x,
1353       order order1, order order2) noexcept;
1354
1355   // In-place byte reversal functions
1356
1357   template &lt;class EndianReversible&gt;
1358     void endian_reverse_inplace(EndianReversible&amp; x) noexcept;
1359
1360   template &lt;class EndianReversibleInplace&gt;
1361     void big_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;
1362   template &lt;class EndianReversibleInplace&gt;
1363     void native_to_big_inplace(EndianReversibleInplace&amp; x) noexcept;
1364   template &lt;class EndianReversibleInplace&gt;
1365     void little_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;
1366   template &lt;class EndianReversibleInplace&gt;
1367     void native_to_little_inplace(EndianReversibleInplace&amp; x) noexcept;
1368
1369   template &lt;order O1, order O2, class EndianReversibleInplace&gt;
1370     void conditional_reverse_inplace(EndianReversibleInplace&amp; x) noexcept;
1371   template &lt;class EndianReversibleInplace&gt;
1372    void conditional_reverse_inplace(EndianReversibleInplace&amp; x,
1373      order order1, order order2) noexcept;
1374
1375   // Generic load and store functions
1376
1377   template&lt;class T, std::size_t N, order Order&gt;
1378     T endian_load( unsigned char const * p ) noexcept;
1379
1380   template&lt;class T, std::size_t N, order Order&gt;
1381     void endian_store( unsigned char * p, T const &amp; v ) noexcept;
1382
1383   // Convenience load functions
1384
1385   boost::int16_t load_little_s16( unsigned char const * p ) noexcept;
1386   boost::uint16_t load_little_u16( unsigned char const * p ) noexcept;
1387   boost::int16_t load_big_s16( unsigned char const * p ) noexcept;
1388   boost::uint16_t load_big_u16( unsigned char const * p ) noexcept;
1389
1390   boost::int32_t load_little_s24( unsigned char const * p ) noexcept;
1391   boost::uint32_t load_little_u24( unsigned char const * p ) noexcept;
1392   boost::int32_t load_big_s24( unsigned char const * p ) noexcept;
1393   boost::uint32_t load_big_u24( unsigned char const * p ) noexcept;
1394
1395   boost::int32_t load_little_s32( unsigned char const * p ) noexcept;
1396   boost::uint32_t load_little_u32( unsigned char const * p ) noexcept;
1397   boost::int32_t load_big_s32( unsigned char const * p ) noexcept;
1398   boost::uint32_t load_big_u32( unsigned char const * p ) noexcept;
1399
1400   boost::int64_t load_little_s40( unsigned char const * p ) noexcept;
1401   boost::uint64_t load_little_u40( unsigned char const * p ) noexcept;
1402   boost::int64_t load_big_s40( unsigned char const * p ) noexcept;
1403   boost::uint64_t load_big_u40( unsigned char const * p ) noexcept;
1404
1405   boost::int64_t load_little_s48( unsigned char const * p ) noexcept;
1406   boost::uint64_t load_little_u48( unsigned char const * p ) noexcept;
1407   boost::int64_t load_big_s48( unsigned char const * p ) noexcept;
1408   boost::uint64_t load_big_u48( unsigned char const * p ) noexcept;
1409
1410   boost::int64_t load_little_s56( unsigned char const * p ) noexcept;
1411   boost::uint64_t load_little_u56( unsigned char const * p ) noexcept;
1412   boost::int64_t load_big_s56( unsigned char const * p ) noexcept;
1413   boost::uint64_t load_big_u56( unsigned char const * p ) noexcept;
1414
1415   boost::int64_t load_little_s64( unsigned char const * p ) noexcept;
1416   boost::uint64_t load_little_u64( unsigned char const * p ) noexcept;
1417   boost::int64_t load_big_s64( unsigned char const * p ) noexcept;
1418   boost::uint64_t load_big_u64( unsigned char const * p ) noexcept;
1419
1420   // Convenience store functions
1421
1422   void store_little_s16( unsigned char * p, boost::int16_t v ) noexcept;
1423   void store_little_u16( unsigned char * p, boost::uint16_t v ) noexcept;
1424   void store_big_s16( unsigned char * p, boost::int16_t v ) noexcept;
1425   void store_big_u16( unsigned char * p, boost::uint16_t v ) noexcept;
1426
1427   void store_little_s24( unsigned char * p, boost::int32_t v ) noexcept;
1428   void store_little_u24( unsigned char * p, boost::uint32_t v ) noexcept;
1429   void store_big_s24( unsigned char * p, boost::int32_t v ) noexcept;
1430   void store_big_u24( unsigned char * p, boost::uint32_t v ) noexcept;
1431
1432   void store_little_s32( unsigned char * p, boost::int32_t v ) noexcept;
1433   void store_little_u32( unsigned char * p, boost::uint32_t v ) noexcept;
1434   void store_big_s32( unsigned char * p, boost::int32_t v ) noexcept;
1435   void store_big_u32( unsigned char * p, boost::uint32_t v ) noexcept;
1436
1437   void store_little_s40( unsigned char * p, boost::int64_t v ) noexcept;
1438   void store_little_u40( unsigned char * p, boost::uint64_t v ) noexcept;
1439   void store_big_s40( unsigned char * p, boost::int64_t v ) noexcept;
1440   void store_big_u40( unsigned char * p, boost::uint64_t v ) noexcept;
1441
1442   void store_little_s48( unsigned char * p, boost::int64_t v ) noexcept;
1443   void store_little_u48( unsigned char * p, boost::uint64_t v ) noexcept;
1444   void store_big_s48( unsigned char * p, boost::int64_t v ) noexcept;
1445   void store_big_u48( unsigned char * p, boost::uint64_t v ) noexcept;
1446
1447   void store_little_s56( unsigned char * p, boost::int64_t v ) noexcept;
1448   void store_little_u56( unsigned char * p, boost::uint64_t v ) noexcept;
1449   void store_big_s56( unsigned char * p, boost::int64_t v ) noexcept;
1450   void store_big_u56( unsigned char * p, boost::uint64_t v ) noexcept;
1451
1452   void store_little_s64( unsigned char * p, boost::int64_t v ) noexcept;
1453   void store_little_u64( unsigned char * p, boost::uint64_t v ) noexcept;
1454   void store_big_s64( unsigned char * p, boost::int64_t v ) noexcept;
1455   void store_big_u64( unsigned char * p, boost::uint64_t v ) noexcept;
1456
1457 } // namespace endian
1458 } // namespace boost</code></pre>
1459 </div>
1460 </div>
1461 <div class="paragraph">
1462 <p>The values of <code>order::little</code> and <code>order::big</code> shall not be equal to one
1463 another.</p>
1464 </div>
1465 <div class="paragraph">
1466 <p>The value of <code>order::native</code> shall be:</p>
1467 </div>
1468 <div class="ulist">
1469 <ul>
1470 <li>
1471 <p>equal to <code>order::big</code> if the execution environment is big endian, otherwise</p>
1472 </li>
1473 <li>
1474 <p>equal to <code>order::little</code> if the execution environment is little endian,
1475 otherwise</p>
1476 </li>
1477 <li>
1478 <p>unequal to both <code>order::little</code> and <code>order::big</code>.</p>
1479 </li>
1480 </ul>
1481 </div>
1482 </div>
1483 <div class="sect3">
1484 <h4 id="conversion_requirements">Requirements</h4>
1485 <div class="sect4">
1486 <h5 id="conversion_template_argument_requirements">Template argument requirements</h5>
1487 <div class="paragraph">
1488 <p>The template definitions in the <code>boost/endian/conversion.hpp</code> header refer to
1489 various named requirements whose details are set out in the tables in this
1490 subsection. In these tables, <code>T</code> is an object or reference type to be supplied
1491 by a C&#43;&#43; program instantiating a template; <code>x</code> is a value of type (possibly
1492 <code>const</code>) <code>T</code>; <code>mlx</code> is a modifiable lvalue of type <code>T</code>.</p>
1493 </div>
1494 <div class="sect5">
1495 <h6 id="conversion_endianreversible">EndianReversible requirements (in addition to <code>CopyConstructible</code>)</h6>
1496 <table class="tableblock frame-all grid-all stretch">
1497 <colgroup>
1498 <col style="width: 33.3333%;">
1499 <col style="width: 33.3333%;">
1500 <col style="width: 33.3334%;">
1501 </colgroup>
1502 <thead>
1503 <tr>
1504 <th class="tableblock halign-left valign-top">Expression</th>
1505 <th class="tableblock halign-left valign-top">Return</th>
1506 <th class="tableblock halign-left valign-top">Requirements</th>
1507 </tr>
1508 </thead>
1509 <tbody>
1510 <tr>
1511 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>endian_reverse(x)</code></p></td>
1512 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>T</code></p></td>
1513 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
1514 <p><code>T</code> is an endian type or a class type.</p>
1515 </div>
1516 <div class="paragraph">
1517 <p>If <code>T</code> is an endian type, returns the value of <code>x</code> with the order of bytes
1518 reversed.</p>
1519 </div>
1520 <div class="paragraph">
1521 <p>If <code>T</code> is a class type, the function:</p>
1522 </div>
1523 <div class="ulist">
1524 <ul>
1525 <li>
1526 <p>Returns the value of <code>x</code> with the order of bytes reversed for all data members
1527 of types or arrays of types that meet the <code>EndianReversible</code> requirements, and;</p>
1528 </li>
1529 <li>
1530 <p>Is a non-member function in the same namespace as <code>T</code> that can be found by
1531 argument dependent lookup (ADL).</p>
1532 </li>
1533 </ul>
1534 </div></div></td>
1535 </tr>
1536 </tbody>
1537 </table>
1538 </div>
1539 <div class="sect5">
1540 <h6 id="conversion_endianreversibleinplace">EndianReversibleInplace requirements (in addition to <code>CopyConstructible</code>)</h6>
1541 <table class="tableblock frame-all grid-all stretch">
1542 <colgroup>
1543 <col style="width: 50%;">
1544 <col style="width: 50%;">
1545 </colgroup>
1546 <thead>
1547 <tr>
1548 <th class="tableblock halign-left valign-top">Expression</th>
1549 <th class="tableblock halign-left valign-top">Requirements</th>
1550 </tr>
1551 </thead>
1552 <tbody>
1553 <tr>
1554 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>endian_reverse_inplace(mlx)</code></p></td>
1555 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
1556 <p><code>T</code> is an endian type or a class type.</p>
1557 </div>
1558 <div class="paragraph">
1559 <p>If <code>T</code> is an endian type, reverses the order of bytes in <code>mlx</code>.</p>
1560 </div>
1561 <div class="paragraph">
1562 <p>If <code>T</code> is a class type, the function:</p>
1563 </div>
1564 <div class="ulist">
1565 <ul>
1566 <li>
1567 <p>Reverses the order of bytes of all data members of <code>mlx</code> that have types or
1568 arrays of types that meet the <code>EndianReversible</code> or <code>EndianReversibleInplace</code>
1569 requirements, and;</p>
1570 </li>
1571 <li>
1572 <p>Is a non-member function in the same namespace as <code>T</code> that can be found by
1573 argument dependent lookup (ADL).</p>
1574 </li>
1575 </ul>
1576 </div></div></td>
1577 </tr>
1578 </tbody>
1579 </table>
1580 <div class="admonitionblock note">
1581 <table>
1582 <tr>
1583 <td class="icon">
1584 <div class="title">Note</div>
1585 </td>
1586 <td class="content">
1587 Because there is a function template for <code>endian_reverse_inplace</code> that
1588 calls <code>endian_reverse</code>, only <code>endian_reverse</code> is required for a user-defined
1589 type to meet the <code>EndianReversibleInplace</code> requirements. Although User-defined
1590 types are not required to supply an <code>endian_reverse_inplace</code> function, doing so
1591 may improve efficiency.
1592 </td>
1593 </tr>
1594 </table>
1595 </div>
1596 </div>
1597 </div>
1598 <div class="sect4">
1599 <h5 id="conversion_customization_points_for_user_defined_types_udts">Customization points for user-defined types (UDTs)</h5>
1600 <div class="paragraph">
1601 <p>This subsection describes requirements on the Endian library&#8217;s  implementation.</p>
1602 </div>
1603 <div class="paragraph">
1604 <p>The library&#8217;s function templates requiring
1605 <code><a href="#conversion_endianreversible">EndianReversible</a></code> are required to perform
1606 reversal of endianness if needed by making an unqualified call to
1607 <code>endian_reverse()</code>.</p>
1608 </div>
1609 <div class="paragraph">
1610 <p>The library&#8217;s function templates requiring
1611 <code><a href="#conversion_endianreversibleinplace">EndianReversibleInplace</a></code> are required to
1612 perform reversal of endianness if needed by making an unqualified call to
1613 <code>endian_reverse_inplace()</code>.</p>
1614 </div>
1615 <div class="paragraph">
1616 <p>See <code>example/udt_conversion_example.cpp</code> for an example user-defined type.</p>
1617 </div>
1618 </div>
1619 </div>
1620 <div class="sect3">
1621 <h4 id="conversion_byte_reversal_functions">Byte Reversal Functions</h4>
1622 <div class="listingblock">
1623 <div class="content">
1624 <pre class="highlight"><code>template &lt;class Endian&gt;
1625 Endian endian_reverse(Endian x) noexcept;</code></pre>
1626 </div>
1627 </div>
1628 <div class="ulist none">
1629 <ul class="none">
1630 <li>
1631 <p></p>
1632 <div class="dlist">
1633 <dl>
1634 <dt class="hdlist1">Requires</dt>
1635 <dd>
1636 <p><code>Endian</code> must be a standard integral type that is not <code>bool</code>.</p>
1637 </dd>
1638 <dt class="hdlist1">Returns</dt>
1639 <dd>
1640 <p><code>x</code>, with the order of its constituent bytes reversed.</p>
1641 </dd>
1642 </dl>
1643 </div>
1644 </li>
1645 </ul>
1646 </div>
1647 <div class="listingblock">
1648 <div class="content">
1649 <pre class="highlight"><code>template &lt;class EndianReversible&gt;
1650 EndianReversible big_to_native(EndianReversible x) noexcept;</code></pre>
1651 </div>
1652 </div>
1653 <div class="ulist none">
1654 <ul class="none">
1655 <li>
1656 <p></p>
1657 <div class="dlist">
1658 <dl>
1659 <dt class="hdlist1">Returns</dt>
1660 <dd>
1661 <p><code>conditional_reverse&lt;order::big, order::native&gt;(x)</code>.</p>
1662 </dd>
1663 </dl>
1664 </div>
1665 </li>
1666 </ul>
1667 </div>
1668 <div class="listingblock">
1669 <div class="content">
1670 <pre class="highlight"><code>template &lt;class EndianReversible&gt;
1671 EndianReversible native_to_big(EndianReversible x) noexcept;</code></pre>
1672 </div>
1673 </div>
1674 <div class="ulist none">
1675 <ul class="none">
1676 <li>
1677 <p></p>
1678 <div class="dlist">
1679 <dl>
1680 <dt class="hdlist1">Returns</dt>
1681 <dd>
1682 <p><code>conditional_reverse&lt;order::native, order::big&gt;(x)</code>.</p>
1683 </dd>
1684 </dl>
1685 </div>
1686 </li>
1687 </ul>
1688 </div>
1689 <div class="listingblock">
1690 <div class="content">
1691 <pre class="highlight"><code>template &lt;class EndianReversible&gt;
1692 EndianReversible little_to_native(EndianReversible x) noexcept;</code></pre>
1693 </div>
1694 </div>
1695 <div class="ulist none">
1696 <ul class="none">
1697 <li>
1698 <p></p>
1699 <div class="dlist">
1700 <dl>
1701 <dt class="hdlist1">Returns</dt>
1702 <dd>
1703 <p><code>conditional_reverse&lt;order::little, order::native&gt;(x)</code>.</p>
1704 </dd>
1705 </dl>
1706 </div>
1707 </li>
1708 </ul>
1709 </div>
1710 <div class="listingblock">
1711 <div class="content">
1712 <pre class="highlight"><code>template &lt;class EndianReversible&gt;
1713 EndianReversible native_to_little(EndianReversible x) noexcept;</code></pre>
1714 </div>
1715 </div>
1716 <div class="ulist none">
1717 <ul class="none">
1718 <li>
1719 <p></p>
1720 <div class="dlist">
1721 <dl>
1722 <dt class="hdlist1">Returns</dt>
1723 <dd>
1724 <p><code>conditional_reverse&lt;order::native, order::little&gt;(x)</code>.</p>
1725 </dd>
1726 </dl>
1727 </div>
1728 </li>
1729 </ul>
1730 </div>
1731 <div class="listingblock">
1732 <div class="content">
1733 <pre class="highlight"><code>template &lt;order O1, order O2, class EndianReversible&gt;
1734 EndianReversible conditional_reverse(EndianReversible x) noexcept;</code></pre>
1735 </div>
1736 </div>
1737 <div class="ulist none">
1738 <ul class="none">
1739 <li>
1740 <p></p>
1741 <div class="dlist">
1742 <dl>
1743 <dt class="hdlist1">Returns</dt>
1744 <dd>
1745 <p><code>x</code> if <code>O1 == O2,</code> otherwise <code>endian_reverse(x)</code>.</p>
1746 </dd>
1747 <dt class="hdlist1">Remarks</dt>
1748 <dd>
1749 <p>Whether <code>x</code> or <code>endian_reverse(x)</code> is to be returned shall be
1750 determined at compile time.</p>
1751 </dd>
1752 </dl>
1753 </div>
1754 </li>
1755 </ul>
1756 </div>
1757 <div class="listingblock">
1758 <div class="content">
1759 <pre class="highlight"><code>template &lt;class EndianReversible&gt;
1760 EndianReversible conditional_reverse(EndianReversible x,
1761      order order1, order order2) noexcept;</code></pre>
1762 </div>
1763 </div>
1764 <div class="ulist none">
1765 <ul class="none">
1766 <li>
1767 <p></p>
1768 <div class="dlist">
1769 <dl>
1770 <dt class="hdlist1">Returns</dt>
1771 <dd>
1772 <p><code>order1 == order2? x: endian_reverse(x)</code>.</p>
1773 </dd>
1774 </dl>
1775 </div>
1776 </li>
1777 </ul>
1778 </div>
1779 </div>
1780 <div class="sect3">
1781 <h4 id="conversion_in_place_byte_reversal_functions">In-place Byte Reversal Functions</h4>
1782 <div class="listingblock">
1783 <div class="content">
1784 <pre class="highlight"><code>template &lt;class EndianReversible&gt;
1785 void endian_reverse_inplace(EndianReversible&amp; x) noexcept;</code></pre>
1786 </div>
1787 </div>
1788 <div class="ulist none">
1789 <ul class="none">
1790 <li>
1791 <p></p>
1792 <div class="dlist">
1793 <dl>
1794 <dt class="hdlist1">Effects</dt>
1795 <dd>
1796 <p><code>x = endian_reverse(x)</code>.</p>
1797 </dd>
1798 </dl>
1799 </div>
1800 </li>
1801 </ul>
1802 </div>
1803 <div class="listingblock">
1804 <div class="content">
1805 <pre class="highlight"><code>template &lt;class EndianReversibleInplace&gt;
1806 void big_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;</code></pre>
1807 </div>
1808 </div>
1809 <div class="ulist none">
1810 <ul class="none">
1811 <li>
1812 <p></p>
1813 <div class="dlist">
1814 <dl>
1815 <dt class="hdlist1">Effects</dt>
1816 <dd>
1817 <p><code>conditional_reverse_inplace&lt;order::big, order::native&gt;(x)</code>.</p>
1818 </dd>
1819 </dl>
1820 </div>
1821 </li>
1822 </ul>
1823 </div>
1824 <div class="listingblock">
1825 <div class="content">
1826 <pre class="highlight"><code>template &lt;class EndianReversibleInplace&gt;
1827 void native_to_big_inplace(EndianReversibleInplace&amp; x) noexcept;</code></pre>
1828 </div>
1829 </div>
1830 <div class="ulist none">
1831 <ul class="none">
1832 <li>
1833 <p></p>
1834 <div class="dlist">
1835 <dl>
1836 <dt class="hdlist1">Effects</dt>
1837 <dd>
1838 <p><code>conditional_reverse_inplace&lt;order::native, order::big&gt;(x)</code>.</p>
1839 </dd>
1840 </dl>
1841 </div>
1842 </li>
1843 </ul>
1844 </div>
1845 <div class="listingblock">
1846 <div class="content">
1847 <pre class="highlight"><code>template &lt;class EndianReversibleInplace&gt;
1848 void little_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;</code></pre>
1849 </div>
1850 </div>
1851 <div class="ulist none">
1852 <ul class="none">
1853 <li>
1854 <p></p>
1855 <div class="dlist">
1856 <dl>
1857 <dt class="hdlist1">Effects</dt>
1858 <dd>
1859 <p><code>conditional_reverse_inplace&lt;order::little, order::native&gt;(x)</code>.</p>
1860 </dd>
1861 </dl>
1862 </div>
1863 </li>
1864 </ul>
1865 </div>
1866 <div class="listingblock">
1867 <div class="content">
1868 <pre class="highlight"><code>template &lt;class EndianReversibleInplace&gt;
1869 void native_to_little_inplace(EndianReversibleInplace&amp; x) noexcept;</code></pre>
1870 </div>
1871 </div>
1872 <div class="ulist none">
1873 <ul class="none">
1874 <li>
1875 <p></p>
1876 <div class="dlist">
1877 <dl>
1878 <dt class="hdlist1">Effects</dt>
1879 <dd>
1880 <p><code>conditional_reverse_inplace&lt;order::native, order::little&gt;(x)</code>.</p>
1881 </dd>
1882 </dl>
1883 </div>
1884 </li>
1885 </ul>
1886 </div>
1887 <div class="listingblock">
1888 <div class="content">
1889 <pre class="highlight"><code>template &lt;order O1, order O2, class EndianReversibleInplace&gt;
1890 void conditional_reverse_inplace(EndianReversibleInplace&amp; x) noexcept;</code></pre>
1891 </div>
1892 </div>
1893 <div class="ulist none">
1894 <ul class="none">
1895 <li>
1896 <p></p>
1897 <div class="dlist">
1898 <dl>
1899 <dt class="hdlist1">Effects</dt>
1900 <dd>
1901 <p>None if <code>O1 == O2,</code> otherwise <code>endian_reverse_inplace(x)</code>.</p>
1902 </dd>
1903 <dt class="hdlist1">Remarks</dt>
1904 <dd>
1905 <p>Which effect applies shall be determined at compile time.</p>
1906 </dd>
1907 </dl>
1908 </div>
1909 </li>
1910 </ul>
1911 </div>
1912 <div class="listingblock">
1913 <div class="content">
1914 <pre class="highlight"><code>template &lt;class EndianReversibleInplace&gt;
1915 void conditional_reverse_inplace(EndianReversibleInplace&amp; x,
1916      order order1, order order2) noexcept;</code></pre>
1917 </div>
1918 </div>
1919 <div class="ulist none">
1920 <ul class="none">
1921 <li>
1922 <p></p>
1923 <div class="dlist">
1924 <dl>
1925 <dt class="hdlist1">Effects</dt>
1926 <dd>
1927 <p>If <code>order1 == order2</code> then <code>endian_reverse_inplace(x)</code>.</p>
1928 </dd>
1929 </dl>
1930 </div>
1931 </li>
1932 </ul>
1933 </div>
1934 </div>
1935 <div class="sect3">
1936 <h4 id="conversion_generic_load_and_store_functions">Generic Load and Store Functions</h4>
1937 <div class="listingblock">
1938 <div class="content">
1939 <pre class="highlight"><code>template&lt;class T, std::size_t N, order Order&gt;
1940 T endian_load( unsigned char const * p ) noexcept;</code></pre>
1941 </div>
1942 </div>
1943 <div class="ulist none">
1944 <ul class="none">
1945 <li>
1946 <p></p>
1947 <div class="dlist">
1948 <dl>
1949 <dt class="hdlist1">Requires</dt>
1950 <dd>
1951 <p><code>sizeof(T)</code> must be 1, 2, 4, or 8. <code>N</code> must be between 1 and
1952 <code>sizeof(T)</code>, inclusive. <code>T</code> must be trivially copyable. If <code>N</code> is not
1953 equal to <code>sizeof(T)</code>, <code>T</code> must be integral or <code>enum</code>.</p>
1954 </dd>
1955 <dt class="hdlist1">Effects</dt>
1956 <dd>
1957 <p>Reads <code>N</code> bytes starting from <code>p</code>, in forward or reverse order
1958 depending on whether <code>Order</code> matches the native endianness or not,
1959 interprets the resulting bit pattern as a value of type <code>T</code>, and returns it.
1960 If <code>sizeof(T)</code> is bigger than <code>N</code>, zero-extends when <code>T</code> is unsigned,
1961 sign-extends otherwise.</p>
1962 </dd>
1963 </dl>
1964 </div>
1965 </li>
1966 </ul>
1967 </div>
1968 <div class="listingblock">
1969 <div class="content">
1970 <pre class="highlight"><code>template&lt;class T, std::size_t N, order Order&gt;
1971 void endian_store( unsigned char * p, T const &amp; v ) noexcept;</code></pre>
1972 </div>
1973 </div>
1974 <div class="ulist none">
1975 <ul class="none">
1976 <li>
1977 <p></p>
1978 <div class="dlist">
1979 <dl>
1980 <dt class="hdlist1">Requires</dt>
1981 <dd>
1982 <p><code>sizeof(T)</code> must be 1, 2, 4, or 8. <code>N</code> must be between 1 and
1983 <code>sizeof(T)</code>, inclusive. <code>T</code> must be trivially copyable. If <code>N</code> is not
1984 equal to <code>sizeof(T)</code>, <code>T</code> must be integral or <code>enum</code>.</p>
1985 </dd>
1986 <dt class="hdlist1">Effects</dt>
1987 <dd>
1988 <p>Writes to <code>p</code> the <code>N</code> least significant bytes from the object
1989 representation of <code>v</code>, in forward or reverse order depending on whether
1990 <code>Order</code> matches the native endianness or not.</p>
1991 </dd>
1992 </dl>
1993 </div>
1994 </li>
1995 </ul>
1996 </div>
1997 </div>
1998 <div class="sect3">
1999 <h4 id="conversion_convenience_load_functions">Convenience Load Functions</h4>
2000 <div class="listingblock">
2001 <div class="content">
2002 <pre class="highlight"><code>inline boost::intM_t load_little_sN( unsigned char const * p ) noexcept;</code></pre>
2003 </div>
2004 </div>
2005 <div class="ulist none">
2006 <ul class="none">
2007 <li>
2008 <p></p>
2009 <div class="paragraph">
2010 <p>Reads an N-bit signed little-endian integer from <code>p</code>.</p>
2011 </div>
2012 <div class="dlist">
2013 <dl>
2014 <dt class="hdlist1">Returns</dt>
2015 <dd>
2016 <p><code>endian_load&lt;boost::intM_t, N/8, order::little&gt;( p )</code>.</p>
2017 </dd>
2018 </dl>
2019 </div>
2020 </li>
2021 </ul>
2022 </div>
2023 <div class="listingblock">
2024 <div class="content">
2025 <pre class="highlight"><code>inline boost::uintM_t load_little_uN( unsigned char const * p ) noexcept;</code></pre>
2026 </div>
2027 </div>
2028 <div class="ulist none">
2029 <ul class="none">
2030 <li>
2031 <p></p>
2032 <div class="paragraph">
2033 <p>Reads an N-bit unsigned little-endian integer from <code>p</code>.</p>
2034 </div>
2035 <div class="dlist">
2036 <dl>
2037 <dt class="hdlist1">Returns</dt>
2038 <dd>
2039 <p><code>endian_load&lt;boost::uintM_t, N/8, order::little&gt;( p )</code>.</p>
2040 </dd>
2041 </dl>
2042 </div>
2043 </li>
2044 </ul>
2045 </div>
2046 <div class="listingblock">
2047 <div class="content">
2048 <pre class="highlight"><code>inline boost::intM_t load_big_sN( unsigned char const * p ) noexcept;</code></pre>
2049 </div>
2050 </div>
2051 <div class="ulist none">
2052 <ul class="none">
2053 <li>
2054 <p></p>
2055 <div class="paragraph">
2056 <p>Reads an N-bit signed big-endian integer from <code>p</code>.</p>
2057 </div>
2058 <div class="dlist">
2059 <dl>
2060 <dt class="hdlist1">Returns</dt>
2061 <dd>
2062 <p><code>endian_load&lt;boost::intM_t, N/8, order::big&gt;( p )</code>.</p>
2063 </dd>
2064 </dl>
2065 </div>
2066 </li>
2067 </ul>
2068 </div>
2069 <div class="listingblock">
2070 <div class="content">
2071 <pre class="highlight"><code>inline boost::uintM_t load_big_uN( unsigned char const * p ) noexcept;</code></pre>
2072 </div>
2073 </div>
2074 <div class="ulist none">
2075 <ul class="none">
2076 <li>
2077 <p></p>
2078 <div class="paragraph">
2079 <p>Reads an N-bit unsigned big-endian integer from <code>p</code>.</p>
2080 </div>
2081 <div class="dlist">
2082 <dl>
2083 <dt class="hdlist1">Returns</dt>
2084 <dd>
2085 <p><code>endian_load&lt;boost::uintM_t, N/8, order::big&gt;( p )</code>.</p>
2086 </dd>
2087 </dl>
2088 </div>
2089 </li>
2090 </ul>
2091 </div>
2092 </div>
2093 <div class="sect3">
2094 <h4 id="conversion_convenience_store_functions">Convenience Store Functions</h4>
2095 <div class="listingblock">
2096 <div class="content">
2097 <pre class="highlight"><code>inline void store_little_sN( unsigned char * p, boost::intM_t v ) noexcept;</code></pre>
2098 </div>
2099 </div>
2100 <div class="ulist none">
2101 <ul class="none">
2102 <li>
2103 <p></p>
2104 <div class="paragraph">
2105 <p>Writes an N-bit signed little-endian integer to <code>p</code>.</p>
2106 </div>
2107 <div class="dlist">
2108 <dl>
2109 <dt class="hdlist1">Effects</dt>
2110 <dd>
2111 <p><code>endian_store&lt;boost::intM_t, N/8, order::little&gt;( p, v )</code>.</p>
2112 </dd>
2113 </dl>
2114 </div>
2115 </li>
2116 </ul>
2117 </div>
2118 <div class="listingblock">
2119 <div class="content">
2120 <pre class="highlight"><code>inline void store_little_uN( unsigned char * p, boost::uintM_t v ) noexcept;</code></pre>
2121 </div>
2122 </div>
2123 <div class="ulist none">
2124 <ul class="none">
2125 <li>
2126 <p></p>
2127 <div class="paragraph">
2128 <p>Writes an N-bit unsigned little-endian integer to <code>p</code>.</p>
2129 </div>
2130 <div class="dlist">
2131 <dl>
2132 <dt class="hdlist1">Effects</dt>
2133 <dd>
2134 <p><code>endian_store&lt;boost::uintM_t, N/8, order::little&gt;( p, v )</code>.</p>
2135 </dd>
2136 </dl>
2137 </div>
2138 </li>
2139 </ul>
2140 </div>
2141 <div class="listingblock">
2142 <div class="content">
2143 <pre class="highlight"><code>inline void store_big_sN( unsigned char * p, boost::intM_t v ) noexcept;</code></pre>
2144 </div>
2145 </div>
2146 <div class="ulist none">
2147 <ul class="none">
2148 <li>
2149 <p></p>
2150 <div class="paragraph">
2151 <p>Writes an N-bit signed big-endian integer to <code>p</code>.</p>
2152 </div>
2153 <div class="dlist">
2154 <dl>
2155 <dt class="hdlist1">Effects</dt>
2156 <dd>
2157 <p><code>endian_store&lt;boost::intM_t, N/8, order::big&gt;( p, v )</code>.</p>
2158 </dd>
2159 </dl>
2160 </div>
2161 </li>
2162 </ul>
2163 </div>
2164 <div class="listingblock">
2165 <div class="content">
2166 <pre class="highlight"><code>inline void store_big_uN( unsigned char * p, boost::uintM_t v ) noexcept;</code></pre>
2167 </div>
2168 </div>
2169 <div class="ulist none">
2170 <ul class="none">
2171 <li>
2172 <p></p>
2173 <div class="paragraph">
2174 <p>Writes an N-bit unsigned big-endian integer to <code>p</code>.</p>
2175 </div>
2176 <div class="dlist">
2177 <dl>
2178 <dt class="hdlist1">Effects</dt>
2179 <dd>
2180 <p><code>endian_store&lt;boost::uintM_t, N/8, order::big&gt;( p, v )</code>.</p>
2181 </dd>
2182 </dl>
2183 </div>
2184 </li>
2185 </ul>
2186 </div>
2187 </div>
2188 </div>
2189 <div class="sect2">
2190 <h3 id="conversion_faq">FAQ</h3>
2191 <div class="paragraph">
2192 <p>See the <a href="#overview_faq">Overview FAQ</a> for a library-wide FAQ.</p>
2193 </div>
2194 <div class="paragraph">
2195 <p><strong>Why are both value returning and modify-in-place functions provided?</strong></p>
2196 </div>
2197 <div class="ulist">
2198 <ul>
2199 <li>
2200 <p>Returning the result by value is the standard C and C&#43;&#43; idiom for functions
2201 that compute a value from an argument. Modify-in-place functions allow cleaner
2202 code in many real-world endian use cases and are more efficient for user-defined
2203 types that have members such as string data that do not need to be reversed.
2204 Thus both forms are provided.</p>
2205 </li>
2206 </ul>
2207 </div>
2208 <div class="paragraph">
2209 <p><strong>Why not use the Linux names (htobe16, htole16, be16toh, le16toh, etc.) ?</strong></p>
2210 </div>
2211 <div class="ulist">
2212 <ul>
2213 <li>
2214 <p>Those names are non-standard and vary even between POSIX-like operating
2215 systems. A C&#43;&#43; library TS was going to use those names, but found they were
2216 sometimes implemented as macros. Since macros do not respect scoping and
2217 namespace rules, to use them would be very error prone.</p>
2218 </li>
2219 </ul>
2220 </div>
2221 </div>
2222 <div class="sect2">
2223 <h3 id="conversion_acknowledgements">Acknowledgements</h3>
2224 <div class="paragraph">
2225 <p>Tomas Puverle was instrumental in identifying and articulating the need to
2226 support endian conversion as separate from endian integer types. Phil Endecott
2227 suggested the form of the value returning signatures. Vicente Botet and other
2228 reviewers suggested supporting  user defined types. General reverse template
2229 implementation approach using <code>std::reverse</code> suggested by Mathias Gaunard.
2230 Portable implementation approach for 16, 32, and 64-bit integers suggested by
2231 tymofey, with avoidance of undefined behavior as suggested by Giovanni Piero
2232 Deretta, and a further refinement suggested by Pyry Jahkola. Intrinsic builtins
2233 implementation approach for 16, 32, and 64-bit integers suggested by several
2234 reviewers, and by David Stone, who provided his Boost licensed macro
2235 implementation that became the starting point for
2236 <code>boost/endian/detail/intrinsic.hpp</code>.  Pierre Talbot provided the
2237 <code>int8_t endian_reverse()</code> and templated <code>endian_reverse_inplace()</code>
2238 implementations.</p>
2239 </div>
2240 </div>
2241 </div>
2242 </div>
2243 <div class="sect1">
2244 <h2 id="buffers">Endian Buffer Types</h2>
2245 <div class="sectionbody">
2246 <div class="sect2">
2247 <h3 id="buffers_introduction">Introduction</h3>
2248 <div class="paragraph">
2249 <p>The internal byte order of arithmetic types is traditionally called
2250 <strong>endianness</strong>. See the <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> for a full
2251 exploration of <strong>endianness</strong>, including definitions of <strong>big endian</strong> and <strong>little
2252 endian</strong>.</p>
2253 </div>
2254 <div class="paragraph">
2255 <p>Header <code>boost/endian/buffers.hpp</code> provides <code>endian_buffer</code>, a portable endian
2256 integer binary buffer class template with control over byte order, value type,
2257 size, and alignment independent of the platform&#8217;s native endianness. Typedefs
2258 provide easy-to-use names for common configurations.</p>
2259 </div>
2260 <div class="paragraph">
2261 <p>Use cases primarily involve data portability, either via files or network
2262 connections, but these byte-holders may also be used to reduce memory use, file
2263 size, or network activity since they provide binary numeric sizes not otherwise
2264 available.</p>
2265 </div>
2266 <div class="paragraph">
2267 <p>Class <code>endian_buffer</code> is aimed at users who wish explicit control over when
2268 endianness conversions occur. It also serves as the base class for the
2269 <a href="#arithmetic">endian_arithmetic</a> class template, which is aimed at users who
2270 wish fully automatic endianness conversion and direct support for all normal
2271 arithmetic operations.</p>
2272 </div>
2273 </div>
2274 <div class="sect2">
2275 <h3 id="buffers_example">Example</h3>
2276 <div class="paragraph">
2277 <p>The <code>example/endian_example.cpp</code> program writes a binary file containing
2278 four-byte, big-endian and little-endian integers:</p>
2279 </div>
2280 <div class="listingblock">
2281 <div class="content">
2282 <pre class="highlight"><code>#include &lt;iostream&gt;
2283 #include &lt;cstdio&gt;
2284 #include &lt;boost/endian/buffers.hpp&gt;  // see Synopsis below
2285 #include &lt;boost/static_assert.hpp&gt;
2286
2287 using namespace boost::endian;
2288
2289 namespace
2290 {
2291   //  This is an extract from a very widely used GIS file format.
2292   //  Why the designer decided to mix big and little endians in
2293   //  the same file is not known. But this is a real-world format
2294   //  and users wishing to write low level code manipulating these
2295   //  files have to deal with the mixed endianness.
2296
2297   struct header
2298   {
2299     big_int32_buf_t     file_code;
2300     big_int32_buf_t     file_length;
2301     little_int32_buf_t  version;
2302     little_int32_buf_t  shape_type;
2303   };
2304
2305   const char* filename = "test.dat";
2306 }
2307
2308 int main(int, char* [])
2309 {
2310   header h;
2311
2312   BOOST_STATIC_ASSERT(sizeof(h) == 16U);  // reality check
2313
2314   h.file_code   = 0x01020304;
2315   h.file_length = sizeof(header);
2316   h.version     = 1;
2317   h.shape_type  = 0x01020304;
2318
2319   //  Low-level I/O such as POSIX read/write or &lt;cstdio&gt;
2320   //  fread/fwrite is sometimes used for binary file operations
2321   //  when ultimate efficiency is important. Such I/O is often
2322   //  performed in some C++ wrapper class, but to drive home the
2323   //  point that endian integers are often used in fairly
2324   //  low-level code that does bulk I/O operations, &lt;cstdio&gt;
2325   //  fopen/fwrite is used for I/O in this example.
2326
2327   std::FILE* fi = std::fopen(filename, "wb");  // MUST BE BINARY
2328
2329   if (!fi)
2330   {
2331     std::cout &lt;&lt; "could not open " &lt;&lt; filename &lt;&lt; '\n';
2332     return 1;
2333   }
2334
2335   if (std::fwrite(&amp;h, sizeof(header), 1, fi) != 1)
2336   {
2337     std::cout &lt;&lt; "write failure for " &lt;&lt; filename &lt;&lt; '\n';
2338     return 1;
2339   }
2340
2341   std::fclose(fi);
2342
2343   std::cout &lt;&lt; "created file " &lt;&lt; filename &lt;&lt; '\n';
2344
2345   return 0;
2346 }</code></pre>
2347 </div>
2348 </div>
2349 <div class="paragraph">
2350 <p>After compiling and executing <code>example/endian_example.cpp</code>, a hex dump of
2351 <code>test.dat</code> shows:</p>
2352 </div>
2353 <div class="listingblock">
2354 <div class="content">
2355 <pre class="highlight"><code>01020304 00000010 01000000 04030201</code></pre>
2356 </div>
2357 </div>
2358 <div class="paragraph">
2359 <p>Notice that the first two 32-bit integers are big endian while the second two
2360 are little endian, even though the machine this was compiled and run on was
2361 little endian.</p>
2362 </div>
2363 </div>
2364 <div class="sect2">
2365 <h3 id="buffers_limitations">Limitations</h3>
2366 <div class="paragraph">
2367 <p>Requires <code>&lt;climits&gt;</code>, <code>CHAR_BIT == 8</code>. If <code>CHAR_BIT</code> is some other value,
2368 compilation will result in an <code>#error</code>. This restriction is in place because the
2369 design, implementation, testing, and documentation has only considered issues
2370 related to 8-bit bytes, and there have been no real-world use cases presented
2371 for other sizes.</p>
2372 </div>
2373 <div class="paragraph">
2374 <p>In C&#43;&#43;03, <code>endian_buffer</code> does not meet the requirements for POD types because
2375 it has constructors and a private data member. This means that
2376 common use cases are relying on unspecified behavior in that the C&#43;&#43; Standard
2377 does not guarantee memory layout for non-POD types. This has not been a problem
2378 in practice since all known C&#43;&#43; compilers  lay out memory as if <code>endian</code> were
2379 a POD type. In C&#43;&#43;11, it is possible to specify the default constructor as
2380 trivial, and private data members and base classes  no longer disqualify a type
2381 from being a POD type. Thus under C&#43;&#43;11, <code>endian_buffer</code> will no longer be
2382 relying on unspecified behavior.</p>
2383 </div>
2384 </div>
2385 <div class="sect2">
2386 <h3 id="buffers_feature_set">Feature set</h3>
2387 <div class="ulist">
2388 <ul>
2389 <li>
2390 <p>Big endian| little endian | native endian byte ordering.</p>
2391 </li>
2392 <li>
2393 <p>Signed | unsigned</p>
2394 </li>
2395 <li>
2396 <p>Unaligned | aligned</p>
2397 </li>
2398 <li>
2399 <p>1-8 byte (unaligned) | 1, 2, 4, 8 byte (aligned)</p>
2400 </li>
2401 <li>
2402 <p>Choice of  value type</p>
2403 </li>
2404 </ul>
2405 </div>
2406 </div>
2407 <div class="sect2">
2408 <h3 id="buffers_enums_and_typedefs">Enums and typedefs</h3>
2409 <div class="paragraph">
2410 <p>Two scoped enums are provided:</p>
2411 </div>
2412 <div class="listingblock">
2413 <div class="content">
2414 <pre class="highlight"><code>enum class order { big, little, native };
2415
2416 enum class align { no, yes };</code></pre>
2417 </div>
2418 </div>
2419 <div class="paragraph">
2420 <p>One class template is provided:</p>
2421 </div>
2422 <div class="listingblock">
2423 <div class="content">
2424 <pre class="highlight"><code>template &lt;order Order, typename T, std::size_t Nbits,
2425   align Align = align::no&gt;
2426 class endian_buffer;</code></pre>
2427 </div>
2428 </div>
2429 <div class="paragraph">
2430 <p>Typedefs, such as <code>big_int32_buf_t</code>, provide convenient naming conventions for
2431 common use cases:</p>
2432 </div>
2433 <table class="tableblock frame-all grid-all stretch">
2434 <colgroup>
2435 <col style="width: 20%;">
2436 <col style="width: 20%;">
2437 <col style="width: 20%;">
2438 <col style="width: 20%;">
2439 <col style="width: 20%;">
2440 </colgroup>
2441 <thead>
2442 <tr>
2443 <th class="tableblock halign-left valign-top">Name</th>
2444 <th class="tableblock halign-left valign-top">Alignment</th>
2445 <th class="tableblock halign-left valign-top">Endianness</th>
2446 <th class="tableblock halign-left valign-top">Sign</th>
2447 <th class="tableblock halign-left valign-top">Sizes in bits (n)</th>
2448 </tr>
2449 </thead>
2450 <tbody>
2451 <tr>
2452 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_intN_buf_t</code></p></td>
2453 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
2454 <td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
2455 <td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
2456 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
2457 </tr>
2458 <tr>
2459 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_uintN_buf_t</code></p></td>
2460 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
2461 <td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
2462 <td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
2463 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
2464 </tr>
2465 <tr>
2466 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_intN_buf_t</code></p></td>
2467 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
2468 <td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
2469 <td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
2470 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
2471 </tr>
2472 <tr>
2473 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_uintN_buf_t</code></p></td>
2474 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
2475 <td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
2476 <td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
2477 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
2478 </tr>
2479 <tr>
2480 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>native_intN_buf_t</code></p></td>
2481 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
2482 <td class="tableblock halign-left valign-top"><p class="tableblock">native</p></td>
2483 <td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
2484 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
2485 </tr>
2486 <tr>
2487 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>native_uintN_buf_t</code></p></td>
2488 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
2489 <td class="tableblock halign-left valign-top"><p class="tableblock">native</p></td>
2490 <td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
2491 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
2492 </tr>
2493 <tr>
2494 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_intN_buf_at</code></p></td>
2495 <td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
2496 <td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
2497 <td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
2498 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
2499 </tr>
2500 <tr>
2501 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_uintN_buf_at</code></p></td>
2502 <td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
2503 <td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
2504 <td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
2505 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
2506 </tr>
2507 <tr>
2508 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_intN_buf_at</code></p></td>
2509 <td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
2510 <td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
2511 <td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
2512 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
2513 </tr>
2514 <tr>
2515 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_uintN_buf_at</code></p></td>
2516 <td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
2517 <td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
2518 <td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
2519 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
2520 </tr>
2521 </tbody>
2522 </table>
2523 <div class="paragraph">
2524 <p>The unaligned types do not cause compilers to insert padding bytes in classes
2525 and structs. This is an important characteristic that can be exploited to
2526 minimize wasted space in memory, files, and network transmissions.</p>
2527 </div>
2528 <div class="admonitionblock caution">
2529 <table>
2530 <tr>
2531 <td class="icon">
2532 <div class="title">Caution</div>
2533 </td>
2534 <td class="content">
2535 Code that uses aligned types is possibly non-portable because alignment
2536 requirements vary between hardware architectures and because alignment may be
2537 affected by compiler switches or pragmas. For example, alignment of an 64-bit
2538 integer may be to a 32-bit boundary on a 32-bit machine and to a 64-bit boundary
2539 on a 64-bit machine. Furthermore, aligned types are only available on
2540 architectures with 8, 16, 32, and 64-bit integer types.
2541 </td>
2542 </tr>
2543 </table>
2544 </div>
2545 <div class="admonitionblock tip">
2546 <table>
2547 <tr>
2548 <td class="icon">
2549 <div class="title">Tip</div>
2550 </td>
2551 <td class="content">
2552 Prefer unaligned buffer types.
2553 </td>
2554 </tr>
2555 </table>
2556 </div>
2557 <div class="admonitionblock tip">
2558 <table>
2559 <tr>
2560 <td class="icon">
2561 <div class="title">Tip</div>
2562 </td>
2563 <td class="content">
2564 Protect yourself against alignment ills. For example:
2565 </td>
2566 </tr>
2567 </table>
2568 </div>
2569 <div class="dlist none">
2570 <dl>
2571 <dt></dt>
2572 <dd>
2573 <div class="listingblock">
2574 <div class="content">
2575 <pre class="highlight"><code>static_assert(sizeof(containing_struct) == 12, "sizeof(containing_struct) is wrong");</code></pre>
2576 </div>
2577 </div>
2578 </dd>
2579 </dl>
2580 </div>
2581 <div class="paragraph">
2582 <p>Note: One-byte big and little buffer types have identical layout on all
2583 platforms, so they never actually reverse endianness. They are provided to
2584 enable generic code, and to improve code readability and searchability.</p>
2585 </div>
2586 </div>
2587 <div class="sect2">
2588 <h3 id="buffers_class_template_endian_buffer">Class template <code>endian_buffer</code></h3>
2589 <div class="paragraph">
2590 <p>An <code>endian_buffer</code> is a byte-holder for arithmetic types with
2591 user-specified endianness, value type, size, and alignment.</p>
2592 </div>
2593 <div class="sect3">
2594 <h4 id="buffers_synopsis">Synopsis</h4>
2595 <div class="listingblock">
2596 <div class="content">
2597 <pre class="highlight"><code>namespace boost
2598 {
2599   namespace endian
2600   {
2601     //  C++11 features emulated if not available
2602
2603     enum class align { no, yes };
2604
2605     template &lt;order Order, class T, std::size_t Nbits,
2606       align Align = align::no&gt;
2607     class endian_buffer
2608     {
2609     public:
2610
2611       typedef T value_type;
2612
2613       endian_buffer() noexcept = default;
2614       explicit endian_buffer(T v) noexcept;
2615
2616       endian_buffer&amp; operator=(T v) noexcept;
2617       value_type value() const noexcept;
2618       unsigned char* data() noexcept;
2619       unsigned char const* data() const noexcept;
2620
2621     private:
2622
2623       unsigned char value_[Nbits / CHAR_BIT]; // exposition only
2624     };
2625
2626     //  stream inserter
2627     template &lt;class charT, class traits, order Order, class T,
2628       std::size_t n_bits, align Align&gt;
2629     std::basic_ostream&lt;charT, traits&gt;&amp;
2630       operator&lt;&lt;(std::basic_ostream&lt;charT, traits&gt;&amp; os,
2631         const endian_buffer&lt;Order, T, n_bits, Align&gt;&amp; x);
2632
2633     //  stream extractor
2634     template &lt;class charT, class traits, order Order, class T,
2635       std::size_t n_bits, align A&gt;
2636     std::basic_istream&lt;charT, traits&gt;&amp;
2637       operator&gt;&gt;(std::basic_istream&lt;charT, traits&gt;&amp; is,
2638         endian_buffer&lt;Order, T, n_bits, Align&gt;&amp; x);
2639
2640     // typedefs
2641
2642     // unaligned big endian signed integer buffers
2643     typedef endian_buffer&lt;order::big, int_least8_t, 8&gt;        big_int8_buf_t;
2644     typedef endian_buffer&lt;order::big, int_least16_t, 16&gt;      big_int16_buf_t;
2645     typedef endian_buffer&lt;order::big, int_least32_t, 24&gt;      big_int24_buf_t;
2646     typedef endian_buffer&lt;order::big, int_least32_t, 32&gt;      big_int32_buf_t;
2647     typedef endian_buffer&lt;order::big, int_least64_t, 40&gt;      big_int40_buf_t;
2648     typedef endian_buffer&lt;order::big, int_least64_t, 48&gt;      big_int48_buf_t;
2649     typedef endian_buffer&lt;order::big, int_least64_t, 56&gt;      big_int56_buf_t;
2650     typedef endian_buffer&lt;order::big, int_least64_t, 64&gt;      big_int64_buf_t;
2651
2652     // unaligned big endian unsigned integer buffers
2653     typedef endian_buffer&lt;order::big, uint_least8_t, 8&gt;       big_uint8_buf_t;
2654     typedef endian_buffer&lt;order::big, uint_least16_t, 16&gt;     big_uint16_buf_t;
2655     typedef endian_buffer&lt;order::big, uint_least32_t, 24&gt;     big_uint24_buf_t;
2656     typedef endian_buffer&lt;order::big, uint_least32_t, 32&gt;     big_uint32_buf_t;
2657     typedef endian_buffer&lt;order::big, uint_least64_t, 40&gt;     big_uint40_buf_t;
2658     typedef endian_buffer&lt;order::big, uint_least64_t, 48&gt;     big_uint48_buf_t;
2659     typedef endian_buffer&lt;order::big, uint_least64_t, 56&gt;     big_uint56_buf_t;
2660     typedef endian_buffer&lt;order::big, uint_least64_t, 64&gt;     big_uint64_buf_t;
2661
2662     // unaligned big endian floating point buffers
2663     typedef endian_buffer&lt;order::big, float, 32&gt;              big_float32_buf_t;
2664     typedef endian_buffer&lt;order::big, double, 64&gt;             big_float64_buf_t;
2665
2666     // unaligned little endian signed integer buffers
2667     typedef endian_buffer&lt;order::little, int_least8_t, 8&gt;     little_int8_buf_t;
2668     typedef endian_buffer&lt;order::little, int_least16_t, 16&gt;   little_int16_buf_t;
2669     typedef endian_buffer&lt;order::little, int_least32_t, 24&gt;   little_int24_buf_t;
2670     typedef endian_buffer&lt;order::little, int_least32_t, 32&gt;   little_int32_buf_t;
2671     typedef endian_buffer&lt;order::little, int_least64_t, 40&gt;   little_int40_buf_t;
2672     typedef endian_buffer&lt;order::little, int_least64_t, 48&gt;   little_int48_buf_t;
2673     typedef endian_buffer&lt;order::little, int_least64_t, 56&gt;   little_int56_buf_t;
2674     typedef endian_buffer&lt;order::little, int_least64_t, 64&gt;   little_int64_buf_t;
2675
2676     // unaligned little endian unsigned integer buffers
2677     typedef endian_buffer&lt;order::little, uint_least8_t, 8&gt;    little_uint8_buf_t;
2678     typedef endian_buffer&lt;order::little, uint_least16_t, 16&gt;  little_uint16_buf_t;
2679     typedef endian_buffer&lt;order::little, uint_least32_t, 24&gt;  little_uint24_buf_t;
2680     typedef endian_buffer&lt;order::little, uint_least32_t, 32&gt;  little_uint32_buf_t;
2681     typedef endian_buffer&lt;order::little, uint_least64_t, 40&gt;  little_uint40_buf_t;
2682     typedef endian_buffer&lt;order::little, uint_least64_t, 48&gt;  little_uint48_buf_t;
2683     typedef endian_buffer&lt;order::little, uint_least64_t, 56&gt;  little_uint56_buf_t;
2684     typedef endian_buffer&lt;order::little, uint_least64_t, 64&gt;  little_uint64_buf_t;
2685
2686     // unaligned little endian floating point buffers
2687     typedef endian_buffer&lt;order::little, float, 32&gt;           little_float32_buf_t;
2688     typedef endian_buffer&lt;order::little, double, 64&gt;          little_float64_buf_t;
2689
2690     // unaligned native endian signed integer types
2691     typedef implementation-defined_int8_buf_t   native_int8_buf_t;
2692     typedef implementation-defined_int16_buf_t  native_int16_buf_t;
2693     typedef implementation-defined_int24_buf_t  native_int24_buf_t;
2694     typedef implementation-defined_int32_buf_t  native_int32_buf_t;
2695     typedef implementation-defined_int40_buf_t  native_int40_buf_t;
2696     typedef implementation-defined_int48_buf_t  native_int48_buf_t;
2697     typedef implementation-defined_int56_buf_t  native_int56_buf_t;
2698     typedef implementation-defined_int64_buf_t  native_int64_buf_t;
2699
2700     // unaligned native endian unsigned integer types
2701     typedef implementation-defined_uint8_buf_t   native_uint8_buf_t;
2702     typedef implementation-defined_uint16_buf_t  native_uint16_buf_t;
2703     typedef implementation-defined_uint24_buf_t  native_uint24_buf_t;
2704     typedef implementation-defined_uint32_buf_t  native_uint32_buf_t;
2705     typedef implementation-defined_uint40_buf_t  native_uint40_buf_t;
2706     typedef implementation-defined_uint48_buf_t  native_uint48_buf_t;
2707     typedef implementation-defined_uint56_buf_t  native_uint56_buf_t;
2708     typedef implementation-defined_uint64_buf_t  native_uint64_buf_t;
2709
2710     // unaligned native endian floating point types
2711     typedef implementation-defined_float32_buf_t  native_float32_buf_t;
2712     typedef implementation-defined_float64_buf_t  native_float64_buf_t;
2713
2714     // aligned big endian signed integer buffers
2715     typedef endian_buffer&lt;order::big, int8_t, 8, align::yes&gt;       big_int8_buf_at;
2716     typedef endian_buffer&lt;order::big, int16_t, 16, align::yes&gt;     big_int16_buf_at;
2717     typedef endian_buffer&lt;order::big, int32_t, 32, align::yes&gt;     big_int32_buf_at;
2718     typedef endian_buffer&lt;order::big, int64_t, 64, align::yes&gt;     big_int64_buf_at;
2719
2720     // aligned big endian unsigned integer buffers
2721     typedef endian_buffer&lt;order::big, uint8_t, 8, align::yes&gt;      big_uint8_buf_at;
2722     typedef endian_buffer&lt;order::big, uint16_t, 16, align::yes&gt;    big_uint16_buf_at;
2723     typedef endian_buffer&lt;order::big, uint32_t, 32, align::yes&gt;    big_uint32_buf_at;
2724     typedef endian_buffer&lt;order::big, uint64_t, 64, align::yes&gt;    big_uint64_buf_at;
2725
2726     // aligned big endian floating point buffers
2727     typedef endian_buffer&lt;order::big, float, 32, align::yes&gt;       big_float32_buf_at;
2728     typedef endian_buffer&lt;order::big, double, 64, align::yes&gt;      big_float64_buf_at;
2729
2730     // aligned little endian signed integer buffers
2731     typedef endian_buffer&lt;order::little, int8_t, 8, align::yes&gt;    little_int8_buf_at;
2732     typedef endian_buffer&lt;order::little, int16_t, 16, align::yes&gt;  little_int16_buf_at;
2733     typedef endian_buffer&lt;order::little, int32_t, 32, align::yes&gt;  little_int32_buf_at;
2734     typedef endian_buffer&lt;order::little, int64_t, 64, align::yes&gt;  little_int64_buf_at;
2735
2736     // aligned little endian unsigned integer buffers
2737     typedef endian_buffer&lt;order::little, uint8_t, 8, align::yes&gt;   little_uint8_buf_at;
2738     typedef endian_buffer&lt;order::little, uint16_t, 16, align::yes&gt; little_uint16_buf_at;
2739     typedef endian_buffer&lt;order::little, uint32_t, 32, align::yes&gt; little_uint32_buf_at;
2740     typedef endian_buffer&lt;order::little, uint64_t, 64, align::yes&gt; little_uint64_buf_at;
2741
2742     // aligned little endian floating point buffers
2743     typedef endian_buffer&lt;order::little, float, 32, align::yes&gt;    little_float32_buf_at;
2744     typedef endian_buffer&lt;order::little, double, 64, align::yes&gt;   little_float64_buf_at;
2745
2746     // aligned native endian typedefs are not provided because
2747     // &lt;cstdint&gt; types are superior for this use case
2748
2749   } // namespace endian
2750 } // namespace boost</code></pre>
2751 </div>
2752 </div>
2753 <div class="paragraph">
2754 <p>The <code>implementation-defined</code> text in typedefs above is either <code>big</code> or <code>little</code>
2755 according to the native endianness of the platform.</p>
2756 </div>
2757 <div class="paragraph">
2758 <p>The expository data member <code>value_</code> stores the current value of the
2759 <code>endian_buffer</code> object as a sequence of bytes ordered as specified by the
2760 <code>Order</code> template parameter. The <code>CHAR_BIT</code> macro is defined in <code>&lt;climits&gt;</code>.
2761 The only supported value of <code>CHAR_BIT</code> is 8.</p>
2762 </div>
2763 <div class="paragraph">
2764 <p>The valid values of <code>Nbits</code> are as follows:</p>
2765 </div>
2766 <div class="ulist">
2767 <ul>
2768 <li>
2769 <p>When <code>sizeof(T)</code> is 1, <code>Nbits</code> shall be 8;</p>
2770 </li>
2771 <li>
2772 <p>When <code>sizeof(T)</code> is 2, <code>Nbits</code> shall be 16;</p>
2773 </li>
2774 <li>
2775 <p>When <code>sizeof(T)</code> is 4, <code>Nbits</code> shall be 24 or 32;</p>
2776 </li>
2777 <li>
2778 <p>When <code>sizeof(T)</code> is 8, <code>Nbits</code> shall be 40, 48, 56, or 64.</p>
2779 </li>
2780 </ul>
2781 </div>
2782 <div class="paragraph">
2783 <p>Other values of <code>sizeof(T)</code> are not supported.</p>
2784 </div>
2785 <div class="paragraph">
2786 <p>When <code>Nbits</code> is equal to <code>sizeof(T)*8</code>, <code>T</code> must be a trivially copyable type
2787 (such as <code>float</code>) that is assumed to have the same endianness as <code>uintNbits_t</code>.</p>
2788 </div>
2789 <div class="paragraph">
2790 <p>When <code>Nbits</code> is less than <code>sizeof(T)*8</code>, <code>T</code> must be either a standard integral
2791 type (C&#43;&#43;std, [basic.fundamental]) or an <code>enum</code>.</p>
2792 </div>
2793 </div>
2794 <div class="sect3">
2795 <h4 id="buffers_members">Members</h4>
2796 <div class="listingblock">
2797 <div class="content">
2798 <pre class="highlight"><code>endian_buffer() noexcept = default;</code></pre>
2799 </div>
2800 </div>
2801 <div class="ulist none">
2802 <ul class="none">
2803 <li>
2804 <p></p>
2805 <div class="dlist">
2806 <dl>
2807 <dt class="hdlist1">Effects</dt>
2808 <dd>
2809 <p>Constructs an uninitialized object.</p>
2810 </dd>
2811 </dl>
2812 </div>
2813 </li>
2814 </ul>
2815 </div>
2816 <div class="listingblock">
2817 <div class="content">
2818 <pre class="highlight"><code>explicit endian_buffer(T v) noexcept;</code></pre>
2819 </div>
2820 </div>
2821 <div class="ulist none">
2822 <ul class="none">
2823 <li>
2824 <p></p>
2825 <div class="dlist">
2826 <dl>
2827 <dt class="hdlist1">Effects</dt>
2828 <dd>
2829 <p><code>endian_store&lt;T, Nbits/8, Order&gt;( value_, v )</code>.</p>
2830 </dd>
2831 </dl>
2832 </div>
2833 </li>
2834 </ul>
2835 </div>
2836 <div class="listingblock">
2837 <div class="content">
2838 <pre class="highlight"><code>endian_buffer&amp; operator=(T v) noexcept;</code></pre>
2839 </div>
2840 </div>
2841 <div class="ulist none">
2842 <ul class="none">
2843 <li>
2844 <p></p>
2845 <div class="dlist">
2846 <dl>
2847 <dt class="hdlist1">Effects</dt>
2848 <dd>
2849 <p><code>endian_store&lt;T, Nbits/8, Order&gt;( value_, v )</code>.</p>
2850 </dd>
2851 <dt class="hdlist1">Returns</dt>
2852 <dd>
2853 <p><code>*this</code>.</p>
2854 </dd>
2855 </dl>
2856 </div>
2857 </li>
2858 </ul>
2859 </div>
2860 <div class="listingblock">
2861 <div class="content">
2862 <pre class="highlight"><code>value_type value() const noexcept;</code></pre>
2863 </div>
2864 </div>
2865 <div class="ulist none">
2866 <ul class="none">
2867 <li>
2868 <p></p>
2869 <div class="dlist">
2870 <dl>
2871 <dt class="hdlist1">Returns</dt>
2872 <dd>
2873 <p><code>endian_load&lt;T, Nbits/8, Order&gt;( value_ )</code>.</p>
2874 </dd>
2875 </dl>
2876 </div>
2877 </li>
2878 </ul>
2879 </div>
2880 <div class="listingblock">
2881 <div class="content">
2882 <pre class="highlight"><code>unsigned char* data() noexcept;</code></pre>
2883 </div>
2884 </div>
2885 <div class="listingblock">
2886 <div class="content">
2887 <pre class="highlight"><code>unsigned char const* data() const noexcept;</code></pre>
2888 </div>
2889 </div>
2890 <div class="ulist none">
2891 <ul class="none">
2892 <li>
2893 <p></p>
2894 <div class="dlist">
2895 <dl>
2896 <dt class="hdlist1">Returns</dt>
2897 <dd>
2898 <p>A pointer to the first byte of <code>value_</code>.</p>
2899 </dd>
2900 </dl>
2901 </div>
2902 </li>
2903 </ul>
2904 </div>
2905 </div>
2906 <div class="sect3">
2907 <h4 id="buffers_non_member_functions">Non-member functions</h4>
2908 <div class="listingblock">
2909 <div class="content">
2910 <pre class="highlight"><code>template &lt;class charT, class traits, order Order, class T,
2911   std::size_t n_bits, align Align&gt;
2912 std::basic_ostream&lt;charT, traits&gt;&amp; operator&lt;&lt;(std::basic_ostream&lt;charT, traits&gt;&amp; os,
2913   const endian_buffer&lt;Order, T, n_bits, Align&gt;&amp; x);</code></pre>
2914 </div>
2915 </div>
2916 <div class="ulist none">
2917 <ul class="none">
2918 <li>
2919 <p></p>
2920 <div class="dlist">
2921 <dl>
2922 <dt class="hdlist1">Returns</dt>
2923 <dd>
2924 <p><code>os &lt;&lt; x.value()</code>.</p>
2925 </dd>
2926 </dl>
2927 </div>
2928 </li>
2929 </ul>
2930 </div>
2931 <div class="listingblock">
2932 <div class="content">
2933 <pre class="highlight"><code>template &lt;class charT, class traits, order Order, class T,
2934   std::size_t n_bits, align A&gt;
2935 std::basic_istream&lt;charT, traits&gt;&amp; operator&gt;&gt;(std::basic_istream&lt;charT, traits&gt;&amp; is,
2936   endian_buffer&lt;Order, T, n_bits, Align&gt;&amp; x);</code></pre>
2937 </div>
2938 </div>
2939 <div class="ulist none">
2940 <ul class="none">
2941 <li>
2942 <p></p>
2943 <div class="dlist">
2944 <dl>
2945 <dt class="hdlist1">Effects</dt>
2946 <dd>
2947 <p>As if:</p>
2948 <div class="listingblock">
2949 <div class="content">
2950 <pre class="highlight"><code>T i;
2951 if (is &gt;&gt; i)
2952   x = i;</code></pre>
2953 </div>
2954 </div>
2955 </dd>
2956 <dt class="hdlist1">Returns</dt>
2957 <dd>
2958 <p><code>is</code>.</p>
2959 </dd>
2960 </dl>
2961 </div>
2962 </li>
2963 </ul>
2964 </div>
2965 </div>
2966 </div>
2967 <div class="sect2">
2968 <h3 id="buffers_faq">FAQ</h3>
2969 <div class="paragraph">
2970 <p>See the <a href="#overview_faq">Overview FAQ</a> for a library-wide FAQ.</p>
2971 </div>
2972 <div class="dlist">
2973 <dl>
2974 <dt class="hdlist1">Why not just use Boost.Serialization?</dt>
2975 <dd>
2976 <p>Serialization involves a conversion for every object involved in I/O. Endian
2977 integers require no conversion or copying. They are already in the desired
2978 format for binary I/O. Thus they can be read or written in bulk.</p>
2979 </dd>
2980 <dt class="hdlist1">Are endian types PODs?</dt>
2981 <dd>
2982 <p>Yes for C&#43;&#43;11. No for C&#43;&#43;03, although several
2983 <a href="#buffers_compilation">macros</a> are available to force PODness in all cases.</p>
2984 </dd>
2985 <dt class="hdlist1">What are the implications of endian integer types not being PODs with C&#43;&#43;03 compilers?</dt>
2986 <dd>
2987 <p>They can&#8217;t be used in unions. Also, compilers aren&#8217;t required to align or lay
2988 out storage in portable ways, although this potential problem hasn&#8217;t prevented
2989 use of Boost.Endian with real compilers.</p>
2990 </dd>
2991 <dt class="hdlist1">What good is native endianness?</dt>
2992 <dd>
2993 <p>It  provides alignment and size guarantees not available from the built-in
2994 types. It eases generic  programming.</p>
2995 </dd>
2996 <dt class="hdlist1">Why bother with the aligned endian types?</dt>
2997 <dd>
2998 <p>Aligned integer operations may be faster (as much as 10 to 20 times faster) if
2999 the endianness and alignment of  the type matches the endianness and alignment
3000 requirements of the machine. The code, however, is likely to be somewhat less
3001 portable than with the unaligned types.</p>
3002 </dd>
3003 </dl>
3004 </div>
3005 </div>
3006 <div class="sect2">
3007 <h3 id="buffers_design_considerations_for_boost_endian_buffers">Design considerations for Boost.Endian buffers</h3>
3008 <div class="ulist">
3009 <ul>
3010 <li>
3011 <p>Must be suitable for I/O - in other words, must be memcpyable.</p>
3012 </li>
3013 <li>
3014 <p>Must provide exactly the size and internal byte ordering specified.</p>
3015 </li>
3016 <li>
3017 <p>Must work correctly when the internal integer representation has more bits
3018 that the sum of the bits in the external byte representation. Sign extension
3019 must work correctly when the internal integer representation type has more
3020 bits than the sum of the bits in the external bytes. For example, using
3021 a 64-bit integer internally to represent 40-bit (5 byte) numbers must work for
3022 both positive and negative values.</p>
3023 </li>
3024 <li>
3025 <p>Must work correctly (including using the same defined external
3026 representation) regardless of whether a compiler treats char as signed or
3027 unsigned.</p>
3028 </li>
3029 <li>
3030 <p>Unaligned types must not cause compilers to insert padding bytes.</p>
3031 </li>
3032 <li>
3033 <p>The implementation should supply optimizations with great care. Experience
3034 has shown that optimizations of endian integers often become pessimizations
3035 when changing  machines or compilers. Pessimizations can also happen when
3036 changing compiler switches, compiler versions, or CPU models of the same
3037 architecture.</p>
3038 </li>
3039 </ul>
3040 </div>
3041 </div>
3042 <div class="sect2">
3043 <h3 id="buffers_c11">C&#43;&#43;11</h3>
3044 <div class="paragraph">
3045 <p>The availability of the C&#43;&#43;11
3046 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
3047 Functions</a> feature is detected automatically, and will be used if present to
3048 ensure that objects of <code>class endian_buffer</code> are trivial, and thus
3049 PODs.</p>
3050 </div>
3051 </div>
3052 <div class="sect2">
3053 <h3 id="buffers_compilation">Compilation</h3>
3054 <div class="paragraph">
3055 <p>Boost.Endian is implemented entirely within headers, with no need to link to
3056 any Boost object libraries.</p>
3057 </div>
3058 <div class="paragraph">
3059 <p>Several macros allow user control over features:</p>
3060 </div>
3061 <div class="ulist">
3062 <ul>
3063 <li>
3064 <p><code>BOOST_ENDIAN_NO_CTORS</code> causes <code>class endian_buffer</code> to have no
3065 constructors. The intended use is for compiling user code that must be
3066 portable between compilers regardless of C&#43;&#43;11
3067 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
3068 Functions</a> support. Use of constructors will always fail,</p>
3069 </li>
3070 <li>
3071 <p><code>BOOST_ENDIAN_FORCE_PODNESS</code> causes <code>BOOST_ENDIAN_NO_CTORS</code> to be defined if
3072 the compiler does not support C&#43;&#43;11
3073 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
3074 Functions</a>. This is ensures that objects of <code>class endian_buffer</code> are PODs, and
3075 so can be used in C&#43;&#43;03 unions. In C&#43;&#43;11, <code>class endian_buffer</code> objects are
3076 PODs, even though they have constructors, so can always be used in unions.</p>
3077 </li>
3078 </ul>
3079 </div>
3080 </div>
3081 </div>
3082 </div>
3083 <div class="sect1">
3084 <h2 id="arithmetic">Endian Arithmetic Types</h2>
3085 <div class="sectionbody">
3086 <div class="sect2">
3087 <h3 id="arithmetic_introduction">Introduction</h3>
3088 <div class="paragraph">
3089 <p>Header <code>boost/endian/arithmetic.hpp</code> provides integer binary types with
3090 control over byte order, value type, size, and alignment. Typedefs provide
3091 easy-to-use names for common configurations.</p>
3092 </div>
3093 <div class="paragraph">
3094 <p>These types provide portable byte-holders for integer data, independent of
3095 particular computer architectures. Use cases almost always involve I/O, either
3096 via files or network connections. Although data portability is the primary
3097 motivation, these integer byte-holders may also be used to reduce memory use,
3098 file size, or network activity since they provide binary integer sizes not
3099 otherwise available.</p>
3100 </div>
3101 <div class="paragraph">
3102 <p>Such integer byte-holder types are traditionally called <strong>endian</strong> types. See the
3103 <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> for a full exploration of
3104 <strong>endianness</strong>, including definitions of <strong>big endian</strong> and <strong>little endian</strong>.</p>
3105 </div>
3106 <div class="paragraph">
3107 <p>Boost endian integers provide the same full set of C&#43;&#43; assignment, arithmetic,
3108 and relational operators as C&#43;&#43; standard integral types, with the standard
3109 semantics.</p>
3110 </div>
3111 <div class="paragraph">
3112 <p>Unary arithmetic operators are <code>+</code>, <code>-</code>,  <code>~</code>, <code>!</code>, plus both prefix and postfix
3113 <code>--</code> and <code>++</code>. Binary arithmetic operators are <code>+</code>, <code>+=</code>, <code>-</code>, <code>-=</code>, <code>*</code>,
3114 <code>*=</code>, <code>/</code>, <code>/=</code>, <code>&amp;</code>, <code>&amp;=</code>, <code>|</code>, <code>|=</code>, <code>^</code>, <code>^=</code>, <code>&lt;&lt;</code>, <code>&lt;&lt;=</code>, <code>&gt;&gt;</code>, and
3115 <code>&gt;&gt;=</code>. Binary relational operators are <code>==</code>, <code>!=</code>, <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, and <code>&gt;=</code>.</p>
3116 </div>
3117 <div class="paragraph">
3118 <p>Implicit conversion to the underlying value type is provided. An implicit
3119 constructor converting from the underlying value type is provided.</p>
3120 </div>
3121 </div>
3122 <div class="sect2">
3123 <h3 id="arithmetic_example">Example</h3>
3124 <div class="paragraph">
3125 <p>The <code>endian_example.cpp</code> program writes a binary file containing four-byte,
3126 big-endian and little-endian integers:</p>
3127 </div>
3128 <div class="listingblock">
3129 <div class="content">
3130 <pre class="highlight"><code>#include &lt;iostream&gt;
3131 #include &lt;cstdio&gt;
3132 #include &lt;boost/endian/arithmetic.hpp&gt;
3133 #include &lt;boost/static_assert.hpp&gt;
3134
3135 using namespace boost::endian;
3136
3137 namespace
3138 {
3139   //  This is an extract from a very widely used GIS file format.
3140   //  Why the designer decided to mix big and little endians in
3141   //  the same file is not known. But this is a real-world format
3142   //  and users wishing to write low level code manipulating these
3143   //  files have to deal with the mixed endianness.
3144
3145   struct header
3146   {
3147     big_int32_t     file_code;
3148     big_int32_t     file_length;
3149     little_int32_t  version;
3150     little_int32_t  shape_type;
3151   };
3152
3153   const char* filename = "test.dat";
3154 }
3155
3156 int main(int, char* [])
3157 {
3158   header h;
3159
3160   BOOST_STATIC_ASSERT(sizeof(h) == 16U);  // reality check
3161
3162   h.file_code   = 0x01020304;
3163   h.file_length = sizeof(header);
3164   h.version     = 1;
3165   h.shape_type  = 0x01020304;
3166
3167   //  Low-level I/O such as POSIX read/write or &lt;cstdio&gt;
3168   //  fread/fwrite is sometimes used for binary file operations
3169   //  when ultimate efficiency is important. Such I/O is often
3170   //  performed in some C++ wrapper class, but to drive home the
3171   //  point that endian integers are often used in fairly
3172   //  low-level code that does bulk I/O operations, &lt;cstdio&gt;
3173   //  fopen/fwrite is used for I/O in this example.
3174
3175   std::FILE* fi = std::fopen(filename, "wb");  // MUST BE BINARY
3176
3177   if (!fi)
3178   {
3179     std::cout &lt;&lt; "could not open " &lt;&lt; filename &lt;&lt; '\n';
3180     return 1;
3181   }
3182
3183   if (std::fwrite(&amp;h, sizeof(header), 1, fi) != 1)
3184   {
3185     std::cout &lt;&lt; "write failure for " &lt;&lt; filename &lt;&lt; '\n';
3186     return 1;
3187   }
3188
3189   std::fclose(fi);
3190
3191   std::cout &lt;&lt; "created file " &lt;&lt; filename &lt;&lt; '\n';
3192
3193   return 0;
3194 }</code></pre>
3195 </div>
3196 </div>
3197 <div class="paragraph">
3198 <p>After compiling and executing <code>endian_example.cpp</code>, a hex dump of <code>test.dat</code>
3199 shows:</p>
3200 </div>
3201 <div class="listingblock">
3202 <div class="content">
3203 <pre class="highlight"><code>01020304 00000010 01000000 04030201</code></pre>
3204 </div>
3205 </div>
3206 <div class="paragraph">
3207 <p>Notice that the first two 32-bit integers are big endian while the second two
3208 are little endian, even though the machine this was compiled and run on was
3209 little endian.</p>
3210 </div>
3211 </div>
3212 <div class="sect2">
3213 <h3 id="arithmetic_limitations">Limitations</h3>
3214 <div class="paragraph">
3215 <p>Requires <code>&lt;climits&gt;</code>, <code>CHAR_BIT == 8</code>. If <code>CHAR_BIT</code> is some other value,
3216 compilation will result in an <code>#error</code>. This restriction is in place because the
3217 design, implementation, testing, and documentation has only considered issues
3218 related to 8-bit bytes, and there have been no real-world use cases presented
3219 for other sizes.</p>
3220 </div>
3221 <div class="paragraph">
3222 <p>In C&#43;&#43;03, <code>endian_arithmetic</code> does not meet the requirements for POD types
3223 because it has constructors, private data members, and a base class. This means
3224 that common use cases are relying on unspecified behavior in that the C&#43;&#43;
3225 Standard does not guarantee memory layout for non-POD types. This has not been a
3226 problem in practice since all known C&#43;&#43; compilers  lay out memory as if
3227 <code>endian</code> were a POD type. In C&#43;&#43;11, it is possible to specify the default
3228 constructor as trivial, and private data members and base classes  no longer
3229 disqualify a type from being a POD type. Thus under C&#43;&#43;11, <code>endian_arithmetic</code>
3230 will no longer be relying on unspecified behavior.</p>
3231 </div>
3232 </div>
3233 <div class="sect2">
3234 <h3 id="arithmetic_feature_set">Feature set</h3>
3235 <div class="ulist">
3236 <ul>
3237 <li>
3238 <p>Big endian| little endian | native endian byte ordering.</p>
3239 </li>
3240 <li>
3241 <p>Signed | unsigned</p>
3242 </li>
3243 <li>
3244 <p>Unaligned | aligned</p>
3245 </li>
3246 <li>
3247 <p>1-8 byte (unaligned) | 1, 2, 4, 8 byte (aligned)</p>
3248 </li>
3249 <li>
3250 <p>Choice of  value type</p>
3251 </li>
3252 </ul>
3253 </div>
3254 </div>
3255 <div class="sect2">
3256 <h3 id="arithmetic_enums_and_typedefs">Enums and typedefs</h3>
3257 <div class="paragraph">
3258 <p>Two scoped enums are provided:</p>
3259 </div>
3260 <div class="listingblock">
3261 <div class="content">
3262 <pre class="highlight"><code>enum class order { big, little, native };
3263
3264 enum class align { no, yes };</code></pre>
3265 </div>
3266 </div>
3267 <div class="paragraph">
3268 <p>One class template is provided:</p>
3269 </div>
3270 <div class="listingblock">
3271 <div class="content">
3272 <pre class="highlight"><code>template &lt;order Order, typename T, std::size_t n_bits,
3273   align Align = align::no&gt;
3274 class endian_arithmetic;</code></pre>
3275 </div>
3276 </div>
3277 <div class="paragraph">
3278 <p>Typedefs, such as <code>big_int32_t</code>, provide convenient naming conventions for
3279 common use cases:</p>
3280 </div>
3281 <table class="tableblock frame-all grid-all stretch">
3282 <colgroup>
3283 <col style="width: 20%;">
3284 <col style="width: 20%;">
3285 <col style="width: 20%;">
3286 <col style="width: 20%;">
3287 <col style="width: 20%;">
3288 </colgroup>
3289 <thead>
3290 <tr>
3291 <th class="tableblock halign-left valign-top">Name</th>
3292 <th class="tableblock halign-left valign-top">Alignment</th>
3293 <th class="tableblock halign-left valign-top">Endianness</th>
3294 <th class="tableblock halign-left valign-top">Sign</th>
3295 <th class="tableblock halign-left valign-top">Sizes in bits (n)</th>
3296 </tr>
3297 </thead>
3298 <tbody>
3299 <tr>
3300 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_intN_t</code></p></td>
3301 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
3302 <td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
3303 <td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
3304 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
3305 </tr>
3306 <tr>
3307 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_uintN_t</code></p></td>
3308 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
3309 <td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
3310 <td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
3311 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
3312 </tr>
3313 <tr>
3314 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_intN_t</code></p></td>
3315 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
3316 <td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
3317 <td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
3318 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
3319 </tr>
3320 <tr>
3321 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_uintN_t</code></p></td>
3322 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
3323 <td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
3324 <td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
3325 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
3326 </tr>
3327 <tr>
3328 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>native_intN_t</code></p></td>
3329 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
3330 <td class="tableblock halign-left valign-top"><p class="tableblock">native</p></td>
3331 <td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
3332 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
3333 </tr>
3334 <tr>
3335 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>native_uintN_t</code></p></td>
3336 <td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
3337 <td class="tableblock halign-left valign-top"><p class="tableblock">native</p></td>
3338 <td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
3339 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
3340 </tr>
3341 <tr>
3342 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_intN_at</code></p></td>
3343 <td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
3344 <td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
3345 <td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
3346 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
3347 </tr>
3348 <tr>
3349 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_uintN_at</code></p></td>
3350 <td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
3351 <td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
3352 <td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
3353 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
3354 </tr>
3355 <tr>
3356 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_intN_at</code></p></td>
3357 <td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
3358 <td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
3359 <td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
3360 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
3361 </tr>
3362 <tr>
3363 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_uintN_at</code></p></td>
3364 <td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
3365 <td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
3366 <td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
3367 <td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
3368 </tr>
3369 </tbody>
3370 </table>
3371 <div class="paragraph">
3372 <p>The unaligned types do not cause compilers to insert padding bytes in classes
3373 and structs. This is an important characteristic that can be exploited to
3374 minimize wasted space in memory, files, and network transmissions.</p>
3375 </div>
3376 <div class="admonitionblock caution">
3377 <table>
3378 <tr>
3379 <td class="icon">
3380 <div class="title">Caution</div>
3381 </td>
3382 <td class="content">
3383 Code that uses aligned types is possibly non-portable because
3384 alignment requirements vary between hardware architectures and because
3385 alignment may be affected by compiler switches or pragmas. For example,
3386 alignment of an 64-bit integer may be to a 32-bit boundary on a 32-bit machine.
3387 Furthermore, aligned types are only available on architectures with 8, 16, 32,
3388 and 64-bit integer types.
3389 </td>
3390 </tr>
3391 </table>
3392 </div>
3393 <div class="admonitionblock tip">
3394 <table>
3395 <tr>
3396 <td class="icon">
3397 <div class="title">Tip</div>
3398 </td>
3399 <td class="content">
3400 Prefer unaligned arithmetic types.
3401 </td>
3402 </tr>
3403 </table>
3404 </div>
3405 <div class="admonitionblock tip">
3406 <table>
3407 <tr>
3408 <td class="icon">
3409 <div class="title">Tip</div>
3410 </td>
3411 <td class="content">
3412 Protect yourself against alignment ills. For example:
3413 </td>
3414 </tr>
3415 </table>
3416 </div>
3417 <div class="dlist none">
3418 <dl>
3419 <dt></dt>
3420 <dd>
3421 <div class="listingblock">
3422 <div class="content">
3423 <pre class="highlight"><code>static_assert(sizeof(containing_struct) == 12, "sizeof(containing_struct) is wrong");</code></pre>
3424 </div>
3425 </div>
3426 </dd>
3427 </dl>
3428 </div>
3429 <div class="admonitionblock note">
3430 <table>
3431 <tr>
3432 <td class="icon">
3433 <div class="title">Note</div>
3434 </td>
3435 <td class="content">
3436 One-byte arithmetic types have identical layout on all platforms, so they
3437 never actually reverse endianness. They are provided to enable generic code,
3438 and to improve code readability and searchability.
3439 </td>
3440 </tr>
3441 </table>
3442 </div>
3443 </div>
3444 <div class="sect2">
3445 <h3 id="arithmetic_class_template_endian_arithmetic">Class template <code>endian_arithmetic</code></h3>
3446 <div class="paragraph">
3447 <p>An <code>endian_integer</code> is an integer byte-holder with user-specified endianness,
3448 value type, size, and alignment. The usual operations on arithmetic types are
3449 supplied.</p>
3450 </div>
3451 <div class="sect3">
3452 <h4 id="arithmetic_synopsis">Synopsis</h4>
3453 <div class="listingblock">
3454 <div class="content">
3455 <pre class="highlight"><code>#include &lt;boost/endian/buffers.hpp&gt;
3456
3457 namespace boost
3458 {
3459   namespace endian
3460   {
3461     //  C++11 features emulated if not available
3462
3463     enum class align { no, yes };
3464
3465     template &lt;order Order, class T, std::size_t n_bits,
3466       align Align = align::no&gt;
3467     class endian_arithmetic
3468       : public endian_buffer&lt;Order, T, n_bits, Align&gt;
3469     {
3470     public:
3471
3472       typedef T value_type;
3473
3474       // if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++11 PODs are not
3475       // available then these two constructors will not be present
3476       endian_arithmetic() noexcept = default;
3477       endian_arithmetic(T v) noexcept;
3478
3479       endian_arithmetic&amp; operator=(T v) noexcept;
3480       operator value_type() const noexcept;
3481       value_type value() const noexcept; // for exposition; see endian_buffer
3482       unsigned char* data() noexcept; // for exposition; see endian_buffer
3483       unsigned char const* data() const noexcept; // for exposition; see endian_buffer
3484
3485       // arithmetic operations
3486       //   note that additional operations are provided by the value_type
3487       value_type operator+() const noexcept;
3488       endian_arithmetic&amp; operator+=(value_type y) noexcept;
3489       endian_arithmetic&amp; operator-=(value_type y) noexcept;
3490       endian_arithmetic&amp; operator*=(value_type y) noexcept;
3491       endian_arithmetic&amp; operator/=(value_type y) noexcept;
3492       endian_arithmetic&amp; operator%=(value_type y) noexcept;
3493       endian_arithmetic&amp; operator&amp;=(value_type y) noexcept;
3494       endian_arithmetic&amp; operator|=(value_type y) noexcept;
3495       endian_arithmetic&amp; operator^=(value_type y) noexcept;
3496       endian_arithmetic&amp; operator&lt;&lt;=(value_type y) noexcept;
3497       endian_arithmetic&amp; operator&gt;&gt;=(value_type y) noexcept;
3498       endian_arithmetic&amp; operator++() noexcept;
3499       endian_arithmetic&amp; operator--() noexcept;
3500       endian_arithmetic operator++(int) noexcept;
3501       endian_arithmetic operator--(int) noexcept;
3502
3503       // Stream inserter
3504       template &lt;class charT, class traits&gt;
3505       friend std::basic_ostream&lt;charT, traits&gt;&amp;
3506         operator&lt;&lt;(std::basic_ostream&lt;charT, traits&gt;&amp; os, const endian_arithmetic&amp; x);
3507
3508       // Stream extractor
3509       template &lt;class charT, class traits&gt;
3510       friend std::basic_istream&lt;charT, traits&gt;&amp;
3511         operator&gt;&gt;(std::basic_istream&lt;charT, traits&gt;&amp; is, endian_arithmetic&amp; x);
3512     };
3513
3514     // typedefs
3515
3516     // unaligned big endian signed integer types
3517     typedef endian_arithmetic&lt;order::big, int_least8_t, 8&gt;        big_int8_t;
3518     typedef endian_arithmetic&lt;order::big, int_least16_t, 16&gt;      big_int16_t;
3519     typedef endian_arithmetic&lt;order::big, int_least32_t, 24&gt;      big_int24_t;
3520     typedef endian_arithmetic&lt;order::big, int_least32_t, 32&gt;      big_int32_t;
3521     typedef endian_arithmetic&lt;order::big, int_least64_t, 40&gt;      big_int40_t;
3522     typedef endian_arithmetic&lt;order::big, int_least64_t, 48&gt;      big_int48_t;
3523     typedef endian_arithmetic&lt;order::big, int_least64_t, 56&gt;      big_int56_t;
3524     typedef endian_arithmetic&lt;order::big, int_least64_t, 64&gt;      big_int64_t;
3525
3526     // unaligned big endian unsigned integer types
3527     typedef endian_arithmetic&lt;order::big, uint_least8_t, 8&gt;       big_uint8_t;
3528     typedef endian_arithmetic&lt;order::big, uint_least16_t, 16&gt;     big_uint16_t;
3529     typedef endian_arithmetic&lt;order::big, uint_least32_t, 24&gt;     big_uint24_t;
3530     typedef endian_arithmetic&lt;order::big, uint_least32_t, 32&gt;     big_uint32_t;
3531     typedef endian_arithmetic&lt;order::big, uint_least64_t, 40&gt;     big_uint40_t;
3532     typedef endian_arithmetic&lt;order::big, uint_least64_t, 48&gt;     big_uint48_t;
3533     typedef endian_arithmetic&lt;order::big, uint_least64_t, 56&gt;     big_uint56_t;
3534     typedef endian_arithmetic&lt;order::big, uint_least64_t, 64&gt;     big_uint64_t;
3535
3536     // unaligned big endian floating point types
3537     typedef endian_arithmetic&lt;order::big, float, 32&gt;              big_float32_t;
3538     typedef endian_arithmetic&lt;order::big, double, 64&gt;             big_float64_t;
3539
3540     // unaligned little endian signed integer types
3541     typedef endian_arithmetic&lt;order::little, int_least8_t, 8&gt;     little_int8_t;
3542     typedef endian_arithmetic&lt;order::little, int_least16_t, 16&gt;   little_int16_t;
3543     typedef endian_arithmetic&lt;order::little, int_least32_t, 24&gt;   little_int24_t;
3544     typedef endian_arithmetic&lt;order::little, int_least32_t, 32&gt;   little_int32_t;
3545     typedef endian_arithmetic&lt;order::little, int_least64_t, 40&gt;   little_int40_t;
3546     typedef endian_arithmetic&lt;order::little, int_least64_t, 48&gt;   little_int48_t;
3547     typedef endian_arithmetic&lt;order::little, int_least64_t, 56&gt;   little_int56_t;
3548     typedef endian_arithmetic&lt;order::little, int_least64_t, 64&gt;   little_int64_t;
3549
3550     // unaligned little endian unsigned integer types
3551     typedef endian_arithmetic&lt;order::little, uint_least8_t, 8&gt;    little_uint8_t;
3552     typedef endian_arithmetic&lt;order::little, uint_least16_t, 16&gt;  little_uint16_t;
3553     typedef endian_arithmetic&lt;order::little, uint_least32_t, 24&gt;  little_uint24_t;
3554     typedef endian_arithmetic&lt;order::little, uint_least32_t, 32&gt;  little_uint32_t;
3555     typedef endian_arithmetic&lt;order::little, uint_least64_t, 40&gt;  little_uint40_t;
3556     typedef endian_arithmetic&lt;order::little, uint_least64_t, 48&gt;  little_uint48_t;
3557     typedef endian_arithmetic&lt;order::little, uint_least64_t, 56&gt;  little_uint56_t;
3558     typedef endian_arithmetic&lt;order::little, uint_least64_t, 64&gt;  little_uint64_t;
3559
3560     // unaligned little endian floating point types
3561     typedef endian_arithmetic&lt;order::little, float, 32&gt;           little_float32_t;
3562     typedef endian_arithmetic&lt;order::little, double, 64&gt;          little_float64_t;
3563
3564     // unaligned native endian signed integer types
3565     typedef implementation-defined_int8_t   native_int8_t;
3566     typedef implementation-defined_int16_t  native_int16_t;
3567     typedef implementation-defined_int24_t  native_int24_t;
3568     typedef implementation-defined_int32_t  native_int32_t;
3569     typedef implementation-defined_int40_t  native_int40_t;
3570     typedef implementation-defined_int48_t  native_int48_t;
3571     typedef implementation-defined_int56_t  native_int56_t;
3572     typedef implementation-defined_int64_t  native_int64_t;
3573
3574     // unaligned native endian unsigned integer types
3575     typedef implementation-defined_uint8_t   native_uint8_t;
3576     typedef implementation-defined_uint16_t  native_uint16_t;
3577     typedef implementation-defined_uint24_t  native_uint24_t;
3578     typedef implementation-defined_uint32_t  native_uint32_t;
3579     typedef implementation-defined_uint40_t  native_uint40_t;
3580     typedef implementation-defined_uint48_t  native_uint48_t;
3581     typedef implementation-defined_uint56_t  native_uint56_t;
3582     typedef implementation-defined_uint64_t  native_uint64_t;
3583
3584     // unaligned native endian floating point types
3585     typedef implementation-defined_float32_t  native_float32_t;
3586     typedef implementation-defined_float64_t  native_float64_t;
3587
3588     // aligned big endian signed integer types
3589     typedef endian_arithmetic&lt;order::big, int8_t, 8, align::yes&gt;       big_int8_at;
3590     typedef endian_arithmetic&lt;order::big, int16_t, 16, align::yes&gt;     big_int16_at;
3591     typedef endian_arithmetic&lt;order::big, int32_t, 32, align::yes&gt;     big_int32_at;
3592     typedef endian_arithmetic&lt;order::big, int64_t, 64, align::yes&gt;     big_int64_at;
3593
3594     // aligned big endian unsigned integer types
3595     typedef endian_arithmetic&lt;order::big, uint8_t, 8, align::yes&gt;      big_uint8_at;
3596     typedef endian_arithmetic&lt;order::big, uint16_t, 16, align::yes&gt;    big_uint16_at;
3597     typedef endian_arithmetic&lt;order::big, uint32_t, 32, align::yes&gt;    big_uint32_at;
3598     typedef endian_arithmetic&lt;order::big, uint64_t, 64, align::yes&gt;    big_uint64_at;
3599
3600     // aligned big endian floating point types
3601     typedef endian_arithmetic&lt;order::big, float, 32, align::yes&gt;       big_float32_at;
3602     typedef endian_arithmetic&lt;order::big, double, 64, align::yes&gt;      big_float64_at;
3603
3604     // aligned little endian signed integer types
3605     typedef endian_arithmetic&lt;order::little, int8_t, 8, align::yes&gt;    little_int8_at;
3606     typedef endian_arithmetic&lt;order::little, int16_t, 16, align::yes&gt;  little_int16_at;
3607     typedef endian_arithmetic&lt;order::little, int32_t, 32, align::yes&gt;  little_int32_at;
3608     typedef endian_arithmetic&lt;order::little, int64_t, 64, align::yes&gt;  little_int64_at;
3609
3610     // aligned little endian unsigned integer types
3611     typedef endian_arithmetic&lt;order::little, uint8_t, 8, align::yes&gt;   little_uint8_at;
3612     typedef endian_arithmetic&lt;order::little, uint16_t, 16, align::yes&gt; little_uint16_at;
3613     typedef endian_arithmetic&lt;order::little, uint32_t, 32, align::yes&gt; little_uint32_at;
3614     typedef endian_arithmetic&lt;order::little, uint64_t, 64, align::yes&gt; little_uint64_at;
3615
3616     // aligned little endian floating point types
3617     typedef endian_arithmetic&lt;order::little, float, 32, align::yes&gt;    little_float32_at;
3618     typedef endian_arithmetic&lt;order::little, double, 64, align::yes&gt;   little_float64_at;
3619
3620     // aligned native endian typedefs are not provided because
3621     // &lt;cstdint&gt; types are superior for that use case
3622
3623   } // namespace endian
3624 } // namespace boost</code></pre>
3625 </div>
3626 </div>
3627 <div class="paragraph">
3628 <p>The <code>implementation-defined</code> text above is either <code>big</code> or <code>little</code> according
3629 to the endianness of the platform.</p>
3630 </div>
3631 <div class="paragraph">
3632 <p>The only supported value of <code>CHAR_BIT</code> is 8.</p>
3633 </div>
3634 <div class="paragraph">
3635 <p>The valid values of <code>Nbits</code> are as follows:</p>
3636 </div>
3637 <div class="ulist">
3638 <ul>
3639 <li>
3640 <p>When <code>sizeof(T)</code> is 1, <code>Nbits</code> shall be 8;</p>
3641 </li>
3642 <li>
3643 <p>When <code>sizeof(T)</code> is 2, <code>Nbits</code> shall be 16;</p>
3644 </li>
3645 <li>
3646 <p>When <code>sizeof(T)</code> is 4, <code>Nbits</code> shall be 24 or 32;</p>
3647 </li>
3648 <li>
3649 <p>When <code>sizeof(T)</code> is 8, <code>Nbits</code> shall be 40, 48, 56, or 64.</p>
3650 </li>
3651 </ul>
3652 </div>
3653 <div class="paragraph">
3654 <p>Other values of <code>sizeof(T)</code> are not supported.</p>
3655 </div>
3656 <div class="paragraph">
3657 <p>When <code>Nbits</code> is equal to <code>sizeof(T)*8</code>, <code>T</code> must be a standard arithmetic type.</p>
3658 </div>
3659 <div class="paragraph">
3660 <p>When <code>Nbits</code> is less than <code>sizeof(T)*8</code>, <code>T</code> must be a standard integral type
3661 (C&#43;&#43;std, [basic.fundamental]) that is not <code>bool</code>.</p>
3662 </div>
3663 </div>
3664 <div class="sect3">
3665 <h4 id="arithmetic_members">Members</h4>
3666 <div class="listingblock">
3667 <div class="content">
3668 <pre class="highlight"><code>endian_arithmetic() noexcept = default;  // C++03: endian(){}</code></pre>
3669 </div>
3670 </div>
3671 <div class="ulist none">
3672 <ul class="none">
3673 <li>
3674 <p></p>
3675 <div class="dlist">
3676 <dl>
3677 <dt class="hdlist1">Effects</dt>
3678 <dd>
3679 <p>Constructs an uninitialized object.</p>
3680 </dd>
3681 </dl>
3682 </div>
3683 </li>
3684 </ul>
3685 </div>
3686 <div class="listingblock">
3687 <div class="content">
3688 <pre class="highlight"><code>endian_arithmetic(T v) noexcept;</code></pre>
3689 </div>
3690 </div>
3691 <div class="ulist none">
3692 <ul class="none">
3693 <li>
3694 <p></p>
3695 <div class="dlist">
3696 <dl>
3697 <dt class="hdlist1">Effects</dt>
3698 <dd>
3699 <p>See <code>endian_buffer::endian_buffer(T)</code>.</p>
3700 </dd>
3701 </dl>
3702 </div>
3703 </li>
3704 </ul>
3705 </div>
3706 <div class="listingblock">
3707 <div class="content">
3708 <pre class="highlight"><code>endian_arithmetic&amp; operator=(T v) noexcept;</code></pre>
3709 </div>
3710 </div>
3711 <div class="ulist none">
3712 <ul class="none">
3713 <li>
3714 <p></p>
3715 <div class="dlist">
3716 <dl>
3717 <dt class="hdlist1">Effects</dt>
3718 <dd>
3719 <p>See <code>endian_buffer::operator=(T)</code>.</p>
3720 </dd>
3721 <dt class="hdlist1">Returns</dt>
3722 <dd>
3723 <p><code>*this</code>.</p>
3724 </dd>
3725 </dl>
3726 </div>
3727 </li>
3728 </ul>
3729 </div>
3730 <div class="listingblock">
3731 <div class="content">
3732 <pre class="highlight"><code>operator T() const noexcept;</code></pre>
3733 </div>
3734 </div>
3735 <div class="ulist none">
3736 <ul class="none">
3737 <li>
3738 <p></p>
3739 <div class="dlist">
3740 <dl>
3741 <dt class="hdlist1">Returns</dt>
3742 <dd>
3743 <p><code>value()</code>.</p>
3744 </dd>
3745 </dl>
3746 </div>
3747 </li>
3748 </ul>
3749 </div>
3750 </div>
3751 <div class="sect3">
3752 <h4 id="arithmetic_other_operators">Other operators</h4>
3753 <div class="paragraph">
3754 <p>Other operators on endian objects are forwarded to the equivalent operator on
3755 <code>value_type</code>.</p>
3756 </div>
3757 </div>
3758 <div class="sect3">
3759 <h4 id="arithmetic_stream_inserter">Stream inserter</h4>
3760 <div class="listingblock">
3761 <div class="content">
3762 <pre class="highlight"><code>template &lt;class charT, class traits&gt;
3763 friend std::basic_ostream&lt;charT, traits&gt;&amp;
3764   operator&lt;&lt;(std::basic_ostream&lt;charT, traits&gt;&amp; os, const endian_arithmetic&amp; x);</code></pre>
3765 </div>
3766 </div>
3767 <div class="ulist none">
3768 <ul class="none">
3769 <li>
3770 <p></p>
3771 <div class="dlist">
3772 <dl>
3773 <dt class="hdlist1">Returns</dt>
3774 <dd>
3775 <p><code>os &lt;&lt; +x</code>.</p>
3776 </dd>
3777 </dl>
3778 </div>
3779 </li>
3780 </ul>
3781 </div>
3782 </div>
3783 <div class="sect3">
3784 <h4 id="arithmetic_stream_extractor">Stream extractor</h4>
3785 <div class="listingblock">
3786 <div class="content">
3787 <pre class="highlight"><code>template &lt;class charT, class traits&gt;
3788 friend std::basic_istream&lt;charT, traits&gt;&amp;
3789   operator&gt;&gt;(std::basic_istream&lt;charT, traits&gt;&amp; is, endian_arithmetic&amp; x);</code></pre>
3790 </div>
3791 </div>
3792 <div class="ulist none">
3793 <ul class="none">
3794 <li>
3795 <p></p>
3796 <div class="dlist">
3797 <dl>
3798 <dt class="hdlist1">Effects</dt>
3799 <dd>
3800 <p>As if:</p>
3801 <div class="listingblock">
3802 <div class="content">
3803 <pre class="highlight"><code>T i;
3804 if (is &gt;&gt; i)
3805   x = i;</code></pre>
3806 </div>
3807 </div>
3808 </dd>
3809 <dt class="hdlist1">Returns</dt>
3810 <dd>
3811 <p><code>is</code>.</p>
3812 </dd>
3813 </dl>
3814 </div>
3815 </li>
3816 </ul>
3817 </div>
3818 </div>
3819 </div>
3820 <div class="sect2">
3821 <h3 id="arithmetic_faq">FAQ</h3>
3822 <div class="paragraph">
3823 <p>See the <a href="#overview_faq">Overview FAQ</a> for a library-wide FAQ.</p>
3824 </div>
3825 <div class="dlist">
3826 <dl>
3827 <dt class="hdlist1">Why not just use Boost.Serialization?</dt>
3828 <dd>
3829 <p>Serialization involves a conversion for every object involved in I/O. Endian
3830 integers require no conversion or copying. They are already in the desired
3831 format for binary I/O. Thus they can be read or written in bulk.</p>
3832 </dd>
3833 <dt class="hdlist1">Are endian types PODs?</dt>
3834 <dd>
3835 <p>Yes for C&#43;&#43;11. No for C&#43;&#43;03, although several
3836 <a href="#arithmetic_compilation">macros</a> are available to force PODness in all cases.</p>
3837 </dd>
3838 <dt class="hdlist1">What are the implications of endian integer types not being PODs with C&#43;&#43;03 compilers?</dt>
3839 <dd>
3840 <p>They can&#8217;t be used in unions. Also, compilers aren&#8217;t required to align or lay
3841 out storage in portable ways, although this potential problem hasn&#8217;t prevented
3842 use of Boost.Endian with real compilers.</p>
3843 </dd>
3844 <dt class="hdlist1">What good is native endianness?</dt>
3845 <dd>
3846 <p>It  provides alignment and size guarantees not available from the built-in
3847 types. It eases generic programming.</p>
3848 </dd>
3849 <dt class="hdlist1">Why bother with the aligned endian types?</dt>
3850 <dd>
3851 <p>Aligned integer operations may be faster (as much as 10 to 20 times faster)
3852 if the endianness and alignment of the type matches the endianness and
3853 alignment requirements of the machine. The code, however, will be somewhat less
3854 portable than with the unaligned types.</p>
3855 </dd>
3856 <dt class="hdlist1">Why provide the arithmetic operations?</dt>
3857 <dd>
3858 <p>Providing a full set of operations reduces program clutter and makes code
3859 both easier to write and to read. Consider incrementing a variable in a record.
3860 It is very convenient to write:</p>
3861 <div class="listingblock">
3862 <div class="content">
3863 <pre class="highlight"><code>++record.foo;</code></pre>
3864 </div>
3865 </div>
3866 <div class="paragraph">
3867 <p>Rather than:</p>
3868 </div>
3869 <div class="listingblock">
3870 <div class="content">
3871 <pre class="highlight"><code>int temp(record.foo);
3872 ++temp;
3873 record.foo = temp;</code></pre>
3874 </div>
3875 </div>
3876 </dd>
3877 </dl>
3878 </div>
3879 </div>
3880 <div class="sect2">
3881 <h3 id="arithmetic_design_considerations_for_boost_endian_types">Design considerations for Boost.Endian types</h3>
3882 <div class="ulist">
3883 <ul>
3884 <li>
3885 <p>Must be suitable for I/O - in other words, must be memcpyable.</p>
3886 </li>
3887 <li>
3888 <p>Must provide exactly the size and internal byte ordering specified.</p>
3889 </li>
3890 <li>
3891 <p>Must work correctly when the internal integer representation has more bits
3892 that the sum of the bits in the external byte representation. Sign extension
3893 must work correctly when the internal integer representation type has more
3894 bits than the sum of the bits in the external bytes. For example, using
3895 a 64-bit integer internally to represent 40-bit (5 byte) numbers must work for
3896 both positive and negative values.</p>
3897 </li>
3898 <li>
3899 <p>Must work correctly (including using the same defined external
3900 representation) regardless of whether a compiler treats char as signed or
3901 unsigned.</p>
3902 </li>
3903 <li>
3904 <p>Unaligned types must not cause compilers to insert padding bytes.</p>
3905 </li>
3906 <li>
3907 <p>The implementation should supply optimizations with great care. Experience
3908 has shown that optimizations of endian integers often become pessimizations
3909 when changing machines or compilers. Pessimizations can also happen when
3910 changing compiler switches, compiler versions, or CPU models of the same
3911 architecture.</p>
3912 </li>
3913 </ul>
3914 </div>
3915 </div>
3916 <div class="sect2">
3917 <h3 id="arithmetic_experience">Experience</h3>
3918 <div class="paragraph">
3919 <p>Classes with similar functionality have been independently developed by
3920 several Boost programmers and used very successful in high-value, high-use
3921 applications for many years. These independently developed endian libraries
3922 often evolved from C libraries that were also widely used. Endian types have
3923 proven widely useful across a wide range of computer architectures and
3924 applications.</p>
3925 </div>
3926 </div>
3927 <div class="sect2">
3928 <h3 id="arithmetic_motivating_use_cases">Motivating use cases</h3>
3929 <div class="paragraph">
3930 <p>Neil Mayhew writes: "I can also provide a meaningful use-case for this
3931 library: reading TrueType font files from disk and processing the contents. The
3932 data format has fixed endianness (big) and has unaligned values in various
3933 places. Using Boost.Endian simplifies and cleans the code wonderfully."</p>
3934 </div>
3935 </div>
3936 <div class="sect2">
3937 <h3 id="arithmetic_c11">C&#43;&#43;11</h3>
3938 <div class="paragraph">
3939 <p>The availability of the C&#43;&#43;11
3940 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
3941 Functions</a> feature is detected automatically, and will be used if present to
3942 ensure that objects of <code>class endian_arithmetic</code> are trivial, and thus PODs.</p>
3943 </div>
3944 </div>
3945 <div class="sect2">
3946 <h3 id="arithmetic_compilation">Compilation</h3>
3947 <div class="paragraph">
3948 <p>Boost.Endian is implemented entirely within headers, with no need to link to any
3949 Boost object libraries.</p>
3950 </div>
3951 <div class="paragraph">
3952 <p>Several macros allow user control over features:</p>
3953 </div>
3954 <div class="ulist">
3955 <ul>
3956 <li>
3957 <p>BOOST_ENDIAN_NO_CTORS causes <code>class endian_arithmetic</code> to have no
3958 constructors. The intended use is for compiling user code that must be portable
3959 between compilers regardless of C&#43;&#43;11
3960 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
3961 Functions</a> support. Use of constructors will always fail,</p>
3962 </li>
3963 <li>
3964 <p>BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if
3965 the compiler does not support C&#43;&#43;11
3966 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
3967 Functions</a>. This is ensures that objects of <code>class endian_arithmetic</code> are PODs,
3968 and so can be used in C&#43;&#43;03 unions. In C&#43;&#43;11, <code>class endian_arithmetic</code>
3969 objects are PODs, even though they have constructors, so can always be used in
3970 unions.</p>
3971 </li>
3972 </ul>
3973 </div>
3974 </div>
3975 <div class="sect2">
3976 <h3 id="arithmetic_acknowledgements">Acknowledgements</h3>
3977 <div class="paragraph">
3978 <p>Original design developed by Darin Adler based on classes developed by Mark
3979 Borgerding. Four original class templates combined into a single
3980 <code>endian_arithmetic</code> class template by Beman Dawes, who put the library together,
3981 provided documentation,  added the typedefs, and also added the
3982 <code>unrolled_byte_loops</code> sign partial specialization to correctly extend the sign
3983 when cover integer size differs from endian representation size.</p>
3984 </div>
3985 </div>
3986 </div>
3987 </div>
3988 <div class="sect1">
3989 <h2 id="choosing">Choosing Approach</h2>
3990 <div class="sectionbody">
3991 <div class="sect2">
3992 <h3 id="choosing_introduction">Introduction</h3>
3993 <div class="paragraph">
3994 <p>Deciding which is the best endianness approach (conversion functions, buffer
3995 types, or arithmetic types) for a particular application involves complex
3996 engineering trade-offs. It is hard to assess those trade-offs without some
3997 understanding of the different interfaces, so you might want to read the
3998 <a href="#conversion">conversion functions</a>, <a href="#buffers">buffer types</a>, and
3999 <a href="#arithmetic">arithmetic types</a> pages before diving into this page.</p>
4000 </div>
4001 </div>
4002 <div class="sect2">
4003 <h3 id="choosing_choosing_between_conversion_functions_buffer_types_and_arithmetic_types">Choosing between conversion functions, buffer types, and arithmetic types</h3>
4004 <div class="paragraph">
4005 <p>The best approach to endianness for a particular application depends on the
4006 interaction between the application&#8217;s needs and the characteristics of each of
4007 the three  approaches.</p>
4008 </div>
4009 <div class="paragraph">
4010 <p><strong>Recommendation:</strong> If you are new to endianness, uncertain, or don&#8217;t want to
4011 invest the time to study engineering trade-offs, use
4012 <a href="#arithmetic">endian arithmetic types</a>. They are safe, easy to use, and easy to
4013 maintain. Use the <em><a href="#choosing_anticipating_need">anticipating need</a></em> design
4014 pattern locally around performance hot spots like lengthy loops, if needed.</p>
4015 </div>
4016 <div class="sect3">
4017 <h4 id="choosing_background">Background</h4>
4018 <div class="paragraph">
4019 <p>A dealing with endianness usually implies a program portability or a data
4020 portability requirement, and often both. That means real programs dealing with
4021 endianness are usually complex, so the examples shown here would really be
4022 written as multiple functions spread across multiple translation units. They
4023 would involve interfaces that can not be altered as they are supplied by
4024 third-parties or the standard library.</p>
4025 </div>
4026 </div>
4027 <div class="sect3">
4028 <h4 id="choosing_characteristics">Characteristics</h4>
4029 <div class="paragraph">
4030 <p>The characteristics that differentiate the three approaches to endianness are
4031 the endianness invariants, conversion explicitness, arithmetic operations, sizes
4032 available, and alignment requirements.</p>
4033 </div>
4034 <div class="sect4">
4035 <h5 id="choosing_endianness_invariants">Endianness invariants</h5>
4036 <div class="paragraph">
4037 <p><strong>Endian conversion functions</strong> use objects of the ordinary C&#43;&#43; arithmetic types
4038 like <code>int</code> or <code>unsigned short</code> to hold values. That breaks the implicit
4039 invariant that the C&#43;&#43; language rules apply. The usual language rules only apply
4040 if the endianness of the object is currently set to the native endianness for
4041 the platform. That can make it very hard to reason about logic flow, and result
4042 in difficult to find bugs.</p>
4043 </div>
4044 <div class="paragraph">
4045 <p>For example:</p>
4046 </div>
4047 <div class="listingblock">
4048 <div class="content">
4049 <pre class="highlight"><code>struct data_t  // big endian
4050 {
4051   int32_t   v1;  // description ...
4052   int32_t   v2;  // description ...
4053   ... additional character data members (i.e. non-endian)
4054   int32_t   v3;  // description ...
4055 };
4056
4057 data_t data;
4058
4059 read(data);
4060 big_to_native_inplace(data.v1);
4061 big_to_native_inplace(data.v2);
4062
4063 ...
4064
4065 ++v1;
4066 third_party::func(data.v2);
4067
4068 ...
4069
4070 native_to_big_inplace(data.v1);
4071 native_to_big_inplace(data.v2);
4072 write(data);</code></pre>
4073 </div>
4074 </div>
4075 <div class="paragraph">
4076 <p>The programmer didn&#8217;t bother to convert <code>data.v3</code> to native endianness because
4077 that member isn&#8217;t used. A later maintainer needs to pass <code>data.v3</code> to the
4078 third-party function, so adds <code>third_party::func(data.v3);</code> somewhere deep in
4079 the code. This causes a silent failure because the usual invariant that an
4080 object of type <code>int32_t</code> holds a value as described by the C&#43;&#43; core language
4081 does not apply.</p>
4082 </div>
4083 <div class="paragraph">
4084 <p><strong>Endian buffer and arithmetic types</strong> hold values internally as arrays of
4085 characters with an invariant that the endianness of the array never changes.
4086 That makes these types easier to use and programs easier to maintain.</p>
4087 </div>
4088 <div class="paragraph">
4089 <p>Here is the same example, using an endian arithmetic type:</p>
4090 </div>
4091 <div class="listingblock">
4092 <div class="content">
4093 <pre class="highlight"><code>struct data_t
4094 {
4095   big_int32_t   v1;  // description ...
4096   big_int32_t   v2;  // description ...
4097   ... additional character data members (i.e. non-endian)
4098   big_int32_t   v3;  // description ...
4099 };
4100
4101 data_t data;
4102
4103 read(data);
4104
4105 ...
4106
4107 ++v1;
4108 third_party::func(data.v2);
4109
4110 ...
4111
4112 write(data);</code></pre>
4113 </div>
4114 </div>
4115 <div class="paragraph">
4116 <p>A later maintainer can add <code>third_party::func(data.v3)</code> and it will just-work.</p>
4117 </div>
4118 </div>
4119 <div class="sect4">
4120 <h5 id="choosing_conversion_explicitness">Conversion explicitness</h5>
4121 <div class="paragraph">
4122 <p><strong>Endian conversion functions</strong> and <strong>buffer types</strong> never perform implicit
4123 conversions. This gives users explicit control of when conversion occurs, and
4124 may help avoid unnecessary conversions.</p>
4125 </div>
4126 <div class="paragraph">
4127 <p><strong>Endian arithmetic types</strong> perform conversion implicitly. That makes these types
4128 very easy to use, but can result in unnecessary conversions. Failure to hoist
4129 conversions out of inner loops can bring a performance penalty.</p>
4130 </div>
4131 </div>
4132 <div class="sect4">
4133 <h5 id="choosing_arithmetic_operations">Arithmetic operations</h5>
4134 <div class="paragraph">
4135 <p><strong>Endian conversion functions</strong> do not supply arithmetic operations, but this is
4136 not a concern since this approach uses ordinary C&#43;&#43; arithmetic types to hold
4137 values.</p>
4138 </div>
4139 <div class="paragraph">
4140 <p><strong>Endian buffer types</strong> do not supply arithmetic operations. Although this
4141 approach avoids unnecessary conversions, it can result in the introduction of
4142 additional variables and confuse maintenance programmers.</p>
4143 </div>
4144 <div class="paragraph">
4145 <p><strong>Endian arithmetic types</strong> do supply arithmetic operations. They are very easy to
4146 use if lots of arithmetic is involved.</p>
4147 </div>
4148 </div>
4149 </div>
4150 <div class="sect3">
4151 <h4 id="choosing_sizes">Sizes</h4>
4152 <div class="paragraph">
4153 <p><strong>Endianness conversion functions</strong> only support 1, 2, 4, and 8 byte integers.
4154 That&#8217;s sufficient for many applications.</p>
4155 </div>
4156 <div class="paragraph">
4157 <p><strong>Endian buffer and arithmetic types</strong> support 1, 2, 3, 4, 5, 6, 7, and 8 byte
4158 integers. For an application where memory use or I/O speed is the limiting
4159 factor, using sizes tailored to application needs can be useful.</p>
4160 </div>
4161 <div class="sect4">
4162 <h5 id="choosing_alignments">Alignments</h5>
4163 <div class="paragraph">
4164 <p><strong>Endianness conversion functions</strong> only support aligned integer and
4165 floating-point types. That&#8217;s sufficient for most applications.</p>
4166 </div>
4167 <div class="paragraph">
4168 <p><strong>Endian buffer and arithmetic types</strong> support both aligned and unaligned
4169 integer and floating-point types. Unaligned types are rarely needed, but when
4170 needed they are often very useful and workarounds are painful. For example:</p>
4171 </div>
4172 <div class="paragraph">
4173 <p>Non-portable code like this:</p>
4174 </div>
4175 <div class="listingblock">
4176 <div class="content">
4177 <pre class="highlight"><code>struct S {
4178   uint16_t a; // big endian
4179   uint32_t b; // big endian
4180 } __attribute__ ((packed));</code></pre>
4181 </div>
4182 </div>
4183 <div class="paragraph">
4184 <p>Can be replaced with portable code like this:</p>
4185 </div>
4186 <div class="listingblock">
4187 <div class="content">
4188 <pre class="highlight"><code>struct S {
4189   big_uint16_ut a;
4190   big_uint32_ut b;
4191 };</code></pre>
4192 </div>
4193 </div>
4194 </div>
4195 </div>
4196 <div class="sect3">
4197 <h4 id="choosing_design_patterns">Design patterns</h4>
4198 <div class="paragraph">
4199 <p>Applications often traffic in endian data as records or packets containing
4200 multiple endian data elements. For simplicity, we will just call them records.</p>
4201 </div>
4202 <div class="paragraph">
4203 <p>If desired endianness differs from native endianness, a conversion has to be
4204 performed. When should that conversion occur? Three design patterns have
4205 evolved.</p>
4206 </div>
4207 <div class="sect4">
4208 <h5 id="choosing_convert_only_as_needed_i_e_lazy">Convert only as needed (i.e. lazy)</h5>
4209 <div class="paragraph">
4210 <p>This pattern defers conversion to the point in the code where the data
4211 element is actually used.</p>
4212 </div>
4213 <div class="paragraph">
4214 <p>This pattern is appropriate when which endian element is actually used varies
4215 greatly according to record content or other circumstances</p>
4216 </div>
4217 </div>
4218 <div class="sect4">
4219 <h5 id="choosing_anticipating_need">Convert in anticipation of need</h5>
4220 <div class="paragraph">
4221 <p>This pattern performs conversion to native endianness in anticipation of use,
4222 such as immediately after reading records. If needed, conversion to the output
4223 endianness is performed after all possible needs have passed, such as just
4224 before writing records.</p>
4225 </div>
4226 <div class="paragraph">
4227 <p>One implementation of this pattern is to create a proxy record with endianness
4228 converted to native in a read function, and expose only that proxy to the rest
4229 of the implementation. If a write function, if needed, handles the conversion
4230 from native to the desired output endianness.</p>
4231 </div>
4232 <div class="paragraph">
4233 <p>This pattern is appropriate when all endian elements in a record are typically
4234 used regardless of record content or other circumstances.</p>
4235 </div>
4236 </div>
4237 <div class="sect4">
4238 <h5 id="choosing_convert_only_as_needed_except_locally_in_anticipation_of_need">Convert only as needed, except locally in anticipation of need</h5>
4239 <div class="paragraph">
4240 <p>This pattern in general defers conversion but for specific local needs does
4241 anticipatory conversion. Although particularly appropriate when coupled with the
4242 endian buffer or arithmetic types, it also works well with the conversion
4243 functions.</p>
4244 </div>
4245 <div class="paragraph">
4246 <p>Example:</p>
4247 </div>
4248 <div class="listingblock">
4249 <div class="content">
4250 <pre class="highlight"><code>struct data_t
4251 {
4252   big_int32_t   v1;
4253   big_int32_t   v2;
4254   big_int32_t   v3;
4255 };
4256
4257 data_t data;
4258
4259 read(data);
4260
4261 ...
4262 ++v1;
4263 ...
4264
4265 int32_t v3_temp = data.v3;  // hoist conversion out of loop
4266
4267 for (int32_t i = 0; i &lt; <code>large-number</code>; ++i)
4268 {
4269   ... <code>lengthy computation that accesses v3_temp</code> ...
4270 }
4271 data.v3 = v3_temp;
4272
4273 write(data);</code></pre>
4274 </div>
4275 </div>
4276 <div class="paragraph">
4277 <p>In general the above pseudo-code leaves conversion up to the endian arithmetic
4278 type <code>big_int32_t</code>. But to avoid conversion inside the loop, a temporary is
4279 created before the loop is entered, and then used to set the new value of
4280 <code>data.v3</code> after the loop is complete.</p>
4281 </div>
4282 <div class="paragraph">
4283 <p>Question: Won&#8217;t the compiler&#8217;s optimizer hoist the conversion out of the loop
4284 anyhow?</p>
4285 </div>
4286 <div class="paragraph">
4287 <p>Answer: VC&#43;&#43; 2015 Preview, and probably others, does not, even for a toy test
4288 program. Although the savings is small (two register <code>bswap</code> instructions), the
4289 cost might be significant if the loop is repeated enough times. On the other
4290 hand, the program may be so dominated by I/O time that even a lengthy loop will
4291 be immaterial.</p>
4292 </div>
4293 </div>
4294 </div>
4295 <div class="sect3">
4296 <h4 id="choosing_use_case_examples">Use case examples</h4>
4297 <div class="sect4">
4298 <h5 id="choosing_porting_endian_unaware_codebase">Porting endian unaware codebase</h5>
4299 <div class="paragraph">
4300 <p>An existing codebase runs on  big endian systems. It does not currently deal
4301 with endianness. The codebase needs to be modified so it can run on little
4302 endian systems under various operating systems. To ease transition and protect
4303 value of existing files, external data will continue to be maintained as big
4304 endian.</p>
4305 </div>
4306 <div class="paragraph">
4307 <p>The <a href="#arithmetic">endian arithmetic approach</a> is recommended to meet these
4308 needs. A relatively small number of header files dealing with binary I/O layouts
4309 need to change types. For example, <code>short</code> or <code>int16_t</code> would change to
4310 <code>big_int16_t</code>. No changes are required for <code>.cpp</code> files.</p>
4311 </div>
4312 </div>
4313 <div class="sect4">
4314 <h5 id="choosing_porting_endian_aware_codebase">Porting endian aware codebase</h5>
4315 <div class="paragraph">
4316 <p>An existing codebase runs on little-endian Linux systems. It already deals with
4317 endianness via
4318 <a href="http://man7.org/linux/man-pages/man3/endian.3.html">Linux provided functions</a>.
4319 Because of a business merger, the codebase has to be quickly modified for
4320 Windows and possibly other operating systems, while still supporting Linux. The
4321 codebase is reliable and the programmers are all well-aware of endian issues.</p>
4322 </div>
4323 <div class="paragraph">
4324 <p>These factors all argue for an <a href="#conversion">endian conversion approach</a> that
4325 just mechanically changes the calls to <code>htobe32</code>, etc. to
4326 <code>boost::endian::native_to_big</code>, etc. and replaces <code>&lt;endian.h&gt;</code> with
4327 <code>&lt;boost/endian/conversion.hpp&gt;</code>.</p>
4328 </div>
4329 </div>
4330 <div class="sect4">
4331 <h5 id="choosing_reliability_and_arithmetic_speed">Reliability and arithmetic-speed</h5>
4332 <div class="paragraph">
4333 <p>A new, complex, multi-threaded application is to be developed that must run
4334 on little endian machines, but do big endian network I/O. The developers believe
4335 computational speed for endian variable is critical but have seen numerous bugs
4336 result from inability to reason about endian conversion state. They are also
4337 worried that future maintenance changes could inadvertently introduce a lot of
4338 slow conversions if full-blown endian arithmetic types are used.</p>
4339 </div>
4340 <div class="paragraph">
4341 <p>The <a href="#buffers">endian buffers</a> approach is made-to-order for this use case.</p>
4342 </div>
4343 </div>
4344 <div class="sect4">
4345 <h5 id="choosing_reliability_and_ease_of_use">Reliability and ease-of-use</h5>
4346 <div class="paragraph">
4347 <p>A new, complex, multi-threaded application is to be developed that must run on
4348 little endian machines, but do big endian network I/O. The developers believe
4349 computational speed for endian variables is <strong>not critical</strong> but have seen
4350 numerous bugs result from inability to reason about endian conversion state.
4351 They are also concerned about ease-of-use both during development and long-term
4352 maintenance.</p>
4353 </div>
4354 <div class="paragraph">
4355 <p>Removing concern about conversion speed and adding concern about ease-of-use
4356 tips the balance strongly in favor the
4357 <a href="#arithmetic">endian arithmetic approach</a>.</p>
4358 </div>
4359 </div>
4360 </div>
4361 </div>
4362 </div>
4363 </div>
4364 <div class="sect1">
4365 <h2 id="appendix_mini_review_topics">Appendix A: Endian Mini-Review</h2>
4366 <div class="sectionbody">
4367 <div class="paragraph">
4368 <p>The results of the Boost.Endian formal review included a list of issues to be
4369 resolved before a mini-review.</p>
4370 </div>
4371 <div class="paragraph">
4372 <p>The issues are shown in <strong>bold</strong> below, with the resolution indicated.</p>
4373 </div>
4374 <div class="dlist">
4375 <dl>
4376 <dt class="hdlist1">Common use case scenarios should be developed.</dt>
4377 <dd>
4378 <p>Done. The documentation have been refactored. A page is now devoted to
4379 <a href="#choosing">Choosing the Approach</a> to endianness. See
4380 <a href="#choosing_use_cases">Use cases</a> for use case scenarios.</p>
4381 </dd>
4382 <dt class="hdlist1">Example programs should be developed for the common use case scenarios.</dt>
4383 <dd>
4384 <p>Done. See <a href="#choosing">Choosing the Approach</a>. Example code has been added
4385 throughout.</p>
4386 </dd>
4387 <dt class="hdlist1">Documentation should illuminate the differences between endian integer/float type and endian conversion approaches to the common use case scenarios, and provide guidelines for choosing the most appropriate approach in user&#8217;s applications.</dt>
4388 <dd>
4389 <p>Done. See <a href="#choosing">Choosing the Approach</a>.</p>
4390 </dd>
4391 <dt class="hdlist1">Conversion functions supplying results via return should be provided.</dt>
4392 <dd>
4393 <p>Done. See <a href="#conversion">Conversion Functions</a>.</p>
4394 </dd>
4395 <dt class="hdlist1">Platform specific performance enhancements such as use of compiler intrinsics or relaxed alignment requirements should be supported.</dt>
4396 <dd>
4397 <p>Done. Compiler (Clang, GCC, VisualC&#43;&#43;, etc.) intrinsics and built-in
4398 functions are used in the implementation where appropriate, as requested. See
4399 <a href="#overview_intrinsic">Built-in support for Intrinsics</a>. See
4400 <a href="#overview_timings">Timings for Example 2</a> to gauge the impact of intrinsics.</p>
4401 </dd>
4402 <dt class="hdlist1">Endian integer (and floating) types should be implemented via the conversion functions. If that can&#8217;t be done efficiently, consideration should be given to expanding the conversion function signatures to  resolve the inefficiencies.</dt>
4403 <dd>
4404 <p>Done. For the endian types, the implementation uses the endian conversion
4405 functions, and thus the intrinsics, as requested.</p>
4406 </dd>
4407 <dt class="hdlist1">Benchmarks that measure performance should be provided. It should be possible to compare platform specific performance enhancements against portable base implementations, and to compare endian integer approaches against endian conversion approaches for the common use case scenarios.</dt>
4408 <dd>
4409 <p>Done. See <a href="#overview_timings">Timings for Example 2</a>. The <code>endian/test</code>
4410 directory  also contains several additional benchmark and speed test programs.</p>
4411 </dd>
4412 <dt class="hdlist1">Float (32-bits) and double (64-bits) should be supported. IEEE 754 is the primary use case.</dt>
4413 <dd>
4414 <p>Done. The <a href="#buffers">endian buffer types</a>,
4415 <a href="#arithmetic">endian arithmetic types</a> and
4416 <a href="#conversion">endian conversion functions</a> now support 32-bit <code>(float)</code>
4417 and 64-bit <code>(double)</code> floating point, as requested.</p>
4418 </dd>
4419 <dt class="hdlist1">Support for user defined types (UDTs) is desirable, and should be provided where there would be no conflict with the other concerns.</dt>
4420 <dd>
4421 <p>Done. See <a href="#conversion_customization">Customization points for user-defined
4422 types (UDTs)</a>.</p>
4423 </dd>
4424 <dt class="hdlist1">There is some concern that endian integer/float arithmetic operations might used inadvertently or inappropriately. The impact of adding an endian_buffer class without arithmetic operations should be investigated.</dt>
4425 <dd>
4426 <p>Done. The endian types have been decomposed into class template
4427 <code><a href="#buffers">endian_buffer</a></code> and class template
4428 <code><a href="#arithmetic">endian_arithmetic</a></code>. Class <code>endian_buffer</code> is a public base
4429 class for <code>endian_arithmetic</code>, and can also be used by users as a stand-alone
4430 class.</p>
4431 </dd>
4432 <dt class="hdlist1">Stream insertion and extraction of the endian integer/float types should be documented and included in the test coverage.</dt>
4433 <dd>
4434 <p>Done. See <a href="#buffers_stream_inserter">Stream inserter</a> and
4435 <a href="#buffers_stream_extractor">Stream extractor</a>.</p>
4436 </dd>
4437 <dt class="hdlist1">Binary I/O support that was investigated during development of the Endian library should be put up for mini-review for inclusion in the Boost I/O library.</dt>
4438 <dd>
4439 <p>Not done yet. Will be handled as a separate min-review soon after the Endian
4440 mini-review.</p>
4441 </dd>
4442 <dt class="hdlist1">Other requested changes.</dt>
4443 <dd>
4444 <p> In addition to the named-endianness conversion functions, functions that
4445 perform compile-time (via template) and run-time (via function argument)
4446 dispatch are now provided.
4447  <code>order*native</code> is now a synonym for <code>order*big</code> or <code>order*little</code> according
4448 to the endianness of the platform. This reduces the number of template
4449 specializations required.
4450  Headers have been reorganized to make them easier to read, with a synopsis
4451 at the front and implementation following.</p>
4452 </dd>
4453 </dl>
4454 </div>
4455 </div>
4456 </div>
4457 <div class="sect1">
4458 <h2 id="choosing_copyright_and_license">Appendix B: Copyright and License</h2>
4459 <div class="sectionbody">
4460 <div class="paragraph">
4461 <p>This documentation is</p>
4462 </div>
4463 <div class="ulist">
4464 <ul>
4465 <li>
4466 <p>Copyright 2011-2016 Beman Dawes</p>
4467 </li>
4468 <li>
4469 <p>Copyright 2019 Peter Dimov</p>
4470 </li>
4471 </ul>
4472 </div>
4473 <div class="paragraph">
4474 <p>and is distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</p>
4475 </div>
4476 </div>
4477 </div>
4478 </div>
4479 <div id="footer">
4480 <div id="footer-text">
4481 Last updated 2019-12-10 00:18:50 UTC
4482 </div>
4483 </div>
4484 <style>
4485
4486 *:not(pre)>code { background: none; color: #600000; }
4487 :not(pre):not([class^=L])>code { background: none; color: #600000; }
4488 table tr.even, table tr.alt, table tr:nth-of-type(even) { background: none; }
4489
4490 </style>
4491 </body>
4492 </html>