devn00b
/
EQ2EMu


			
							1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492
							<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.8">
<meta name="author" content="Beman Dawes">
<title>Boost.Endian: The Boost Endian Library</title>
<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">
<style>
/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
/* Uncomment @import statement below to use as custom stylesheet */
/*@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";*/
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
audio,canvas,video{display:inline-block}
audio:not([controls]){display:none;height:0}
script{display:none!important}
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
a{background:transparent}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
abbr[title]{border-bottom:1px dotted}
b,strong{font-weight:bold}
dfn{font-style:italic}
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
html,body{font-size:100%}
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}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.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}
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}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:none}
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
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}
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}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
abbr{text-transform:none}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
blockquote cite::before{content:"\2014 \0020"}
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
table thead,table tfoot{background:#f7f8f7}
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}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
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}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
*: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}
*:not(pre)>code.nobreak{word-wrap:normal}
*:not(pre)>code.nowrap{white-space:nowrap}
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}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
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}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#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}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#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}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#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}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#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}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#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}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#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}
#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}
#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}
#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}
#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}
.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
.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}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.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)}
table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.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}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.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}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.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}
.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
.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}
.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}
@media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}
.literalblock pre.nowrap,.literalblock pre.nowrap pre,.listingblock pre.nowrap,.listingblock pre.nowrap pre{white-space:pre;word-wrap:normal}
.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.listingblock>.content{position:relative}
.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}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}
table.pyhltable td.code{padding-left:.75em;padding-right:0}
pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #dddddf}
pre.pygments .lineno{display:inline-block;margin-right:.25em}
table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
.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}
.quoteblock blockquote{margin:0;padding:0;border:0}
.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)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.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}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.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}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
table.tableblock{max-width:100%;border-collapse:separate}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content{margin-bottom:-1.25em}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
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}
table.frame-all{border-width:1px}
table.frame-sides{border-width:0 1px}
table.frame-topbot,table.frame-ends{border-width:1px 0}
table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7}
table.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
td>div.verse{white-space:pre}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
ul.checklist{margin-left:.625em}
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}
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
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}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.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}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
.gist .file-data>table td.line-data{width:99%}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background-color:#00fafa}
.black{color:#000}
.black-background{background-color:#000}
.blue{color:#0000bf}
.blue-background{background-color:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background-color:#fa00fa}
.gray{color:#606060}
.gray-background{background-color:#7d7d7d}
.green{color:#006000}
.green-background{background-color:#007d00}
.lime{color:#00bf00}
.lime-background{background-color:#00fa00}
.maroon{color:#600000}
.maroon-background{background-color:#7d0000}
.navy{color:#000060}
.navy-background{background-color:#00007d}
.olive{color:#606000}
.olive-background{background-color:#7d7d00}
.purple{color:#600060}
.purple-background{background-color:#7d007d}
.red{color:#bf0000}
.red-background{background-color:#fa0000}
.silver{color:#909090}
.silver-background{background-color:#bcbcbc}
.teal{color:#006060}
.teal-background{background-color:#007d7d}
.white{color:#bfbfbf}
.white-background{background-color:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background-color:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.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}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>Boost.Endian: The Boost Endian Library</h1>
<div class="details">
<span id="author" class="author">Beman Dawes</span><br>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#overview">Overview</a>
<ul class="sectlevel2">
<li><a href="#overview_abstract">Abstract</a></li>
<li><a href="#overview_endianness">Introduction to endianness</a></li>
<li><a href="#overview_introduction">Introduction to the Boost.Endian library</a></li>
<li><a href="#overview_choosing_between_conversion_functions_buffer_types_and_arithmetic_types">Choosing between conversion functions, buffer types, and arithmetic types</a></li>
<li><a href="#overview_intrinsics">Built-in support for Intrinsics</a></li>
<li><a href="#overview_performance">Performance</a></li>
<li><a href="#overview_faq">Overall FAQ</a></li>
<li><a href="#overview_history">History</a></li>
<li><a href="#overview_compatibility_with_interim_releases">Compatibility with interim releases</a></li>
<li><a href="#overview_cpp03_support">C&#43;&#43;03 support for C&#43;&#43;11 features</a></li>
<li><a href="#overview_future_directions">Future directions</a></li>
<li><a href="#overview_acknowledgements">Acknowledgements</a></li>
</ul>
</li>
<li><a href="#changelog">Revision History</a>
<ul class="sectlevel2">
<li><a href="#overview_changes_in_1_72_0">Changes in 1.72.0</a></li>
<li><a href="#overview_changes_in_1_71_0">Changes in 1.71.0</a></li>
</ul>
</li>
<li><a href="#conversion">Endian Conversion Functions</a>
<ul class="sectlevel2">
<li><a href="#conversion_introduction">Introduction</a></li>
<li><a href="#conversion_reference">Reference</a></li>
<li><a href="#conversion_faq">FAQ</a></li>
<li><a href="#conversion_acknowledgements">Acknowledgements</a></li>
</ul>
</li>
<li><a href="#buffers">Endian Buffer Types</a>
<ul class="sectlevel2">
<li><a href="#buffers_introduction">Introduction</a></li>
<li><a href="#buffers_example">Example</a></li>
<li><a href="#buffers_limitations">Limitations</a></li>
<li><a href="#buffers_feature_set">Feature set</a></li>
<li><a href="#buffers_enums_and_typedefs">Enums and typedefs</a></li>
<li><a href="#buffers_class_template_endian_buffer">Class template <code>endian_buffer</code></a></li>
<li><a href="#buffers_faq">FAQ</a></li>
<li><a href="#buffers_design_considerations_for_boost_endian_buffers">Design considerations for Boost.Endian buffers</a></li>
<li><a href="#buffers_c11">C&#43;&#43;11</a></li>
<li><a href="#buffers_compilation">Compilation</a></li>
</ul>
</li>
<li><a href="#arithmetic">Endian Arithmetic Types</a>
<ul class="sectlevel2">
<li><a href="#arithmetic_introduction">Introduction</a></li>
<li><a href="#arithmetic_example">Example</a></li>
<li><a href="#arithmetic_limitations">Limitations</a></li>
<li><a href="#arithmetic_feature_set">Feature set</a></li>
<li><a href="#arithmetic_enums_and_typedefs">Enums and typedefs</a></li>
<li><a href="#arithmetic_class_template_endian_arithmetic">Class template <code>endian_arithmetic</code></a></li>
<li><a href="#arithmetic_faq">FAQ</a></li>
<li><a href="#arithmetic_design_considerations_for_boost_endian_types">Design considerations for Boost.Endian types</a></li>
<li><a href="#arithmetic_experience">Experience</a></li>
<li><a href="#arithmetic_motivating_use_cases">Motivating use cases</a></li>
<li><a href="#arithmetic_c11">C&#43;&#43;11</a></li>
<li><a href="#arithmetic_compilation">Compilation</a></li>
<li><a href="#arithmetic_acknowledgements">Acknowledgements</a></li>
</ul>
</li>
<li><a href="#choosing">Choosing Approach</a>
<ul class="sectlevel2">
<li><a href="#choosing_introduction">Introduction</a></li>
<li><a href="#choosing_choosing_between_conversion_functions_buffer_types_and_arithmetic_types">Choosing between conversion functions, buffer types, and arithmetic types</a></li>
</ul>
</li>
<li><a href="#appendix_mini_review_topics">Appendix A: Endian Mini-Review</a></li>
<li><a href="#choosing_copyright_and_license">Appendix B: Copyright and License</a></li>
</ul>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="overview">Overview</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="overview_abstract">Abstract</h3>
<div class="paragraph">
<p>Boost.Endian provides facilities to manipulate the
<a href="#overview_endianness">endianness</a> of integers and user-defined types.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Three approaches to endianness are supported. Each has a long history of
successful use, and each approach has use cases where it is preferred over the
other approaches.</p>
</li>
<li>
<p>Primary uses:</p>
<div class="ulist">
<ul>
<li>
<p>Data portability. The Endian library supports binary data exchange, via
either external media or network transmission, regardless of platform
endianness.</p>
</li>
<li>
<p>Program portability. POSIX-based and Windows-based operating systems
traditionally supply libraries with non-portable functions to perform endian
conversion. There are at least four incompatible sets of functions in common
use. The Endian library is portable across all C&#43;&#43; platforms.</p>
</li>
</ul>
</div>
</li>
<li>
<p>Secondary use: Minimizing data size via sizes and/or alignments not supported
by the standard C&#43;&#43; integer types.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="overview_endianness">Introduction to endianness</h3>
<div class="paragraph">
<p>Consider the following code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>int16_t i = 0x0102;
FILE * file = fopen("test.bin", "wb"); // binary file!
fwrite(&amp;i, sizeof(int16_t), 1, file);
fclose(file);</code></pre>
</div>
</div>
<div class="paragraph">
<p>On OS X, Linux, or Windows systems with an Intel CPU, a hex dump of the
"test.bin" output file produces:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>0201</code></pre>
</div>
</div>
<div class="paragraph">
<p>On OS X systems with a PowerPC CPU, or Solaris systems with a SPARC CPU, a hex
dump of the "test.bin" output file produces:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>0102</code></pre>
</div>
</div>
<div class="paragraph">
<p>What&#8217;s happening here is that Intel CPUs order the bytes of an integer with the
least-significant byte first, while SPARC CPUs place the most-significant byte
first. Some CPUs, such as the PowerPC, allow the operating system to choose
which ordering applies.</p>
</div>
<div class="paragraph">
<p>Most-significant-byte-first ordering is traditionally called "big endian"
ordering and least-significant-byte-first is traditionally called
"little-endian" ordering. The names are derived from
<a href="http://en.wikipedia.org/wiki/Jonathan_Swift">Jonathan Swift</a>'s satirical novel
<em><a href="http://en.wikipedia.org/wiki/Gulliver&#8217;s_Travels">Gulliver&#8217;s Travels</a></em>, where
rival kingdoms opened their soft-boiled eggs at different ends.</p>
</div>
<div class="paragraph">
<p>See Wikipedia&#8217;s <a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article for
an extensive discussion of endianness.</p>
</div>
<div class="paragraph">
<p>Programmers can usually ignore endianness, except when reading a core  dump on
little-endian systems. But programmers  have to deal with endianness when
exchanging binary integers and binary floating point values between computer
systems with differing endianness, whether by physical file transfer or over a
network. And programmers may also want to use the library when minimizing either
internal or external data sizes is advantageous.</p>
</div>
</div>
<div class="sect2">
<h3 id="overview_introduction">Introduction to the Boost.Endian library</h3>
<div class="paragraph">
<p>Boost.Endian provides three different approaches to dealing with endianness. All
three approaches support integers and user-define types (UDTs).</p>
</div>
<div class="paragraph">
<p>Each approach has a long history of successful use, and each approach has use
cases where it is preferred to the other approaches.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><a href="#conversion">Endian conversion functions</a></dt>
<dd>
<p>The application uses the built-in integer types to hold values, and calls the
provided conversion functions to convert byte ordering as needed. Both mutating
and non-mutating conversions are supplied, and each comes in unconditional and
conditional variants.</p>
</dd>
<dt class="hdlist1"><a href="#buffers">Endian buffer types</a></dt>
<dd>
<p>The application uses the provided endian buffer types to hold values, and
explicitly converts to and from the built-in integer types. Buffer sizes of 8,
16, 24, 32, 40, 48, 56, and 64 bits (i.e. 1, 2, 3, 4, 5, 6, 7, and 8 bytes) are
provided. Unaligned integer buffer types are provided for all sizes, and aligned
buffer types are provided for 16, 32, and 64-bit sizes. The provided specific
types are typedefs for a generic class template that may be used directly for
less common use cases.</p>
</dd>
<dt class="hdlist1"><a href="#arithmetic">Endian arithmetic types</a></dt>
<dd>
<p>The application uses the provided endian arithmetic types, which supply the same
operations as the built-in C&#43;&#43; arithmetic types. All conversions are implicit.
Arithmetic sizes of 8, 16, 24, 32, 40, 48, 56, and 64 bits (i.e. 1, 2, 3, 4, 5,
6, 7, and 8 bytes) are provided. Unaligned integer types are provided for all
sizes and aligned arithmetic types are provided for 16, 32, and 64-bit sizes.
The provided specific types are typedefs for a generic class template that may
be used directly in generic code of for less common use cases.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Boost Endian is a header-only library. C&#43;&#43;11 features affecting interfaces,
such as <code>noexcept</code>, are  used only if available. See
<a href="#overview_cpp03_support">C&#43;&#43;03 support for C&#43;&#43;11 features</a> for details.</p>
</div>
</div>
<div class="sect2">
<h3 id="overview_choosing_between_conversion_functions_buffer_types_and_arithmetic_types">Choosing between conversion functions, buffer types, and arithmetic types</h3>
<div class="paragraph">
<p>This section has been moved to its own <a href="#choosing">Choosing the Approach</a> page.</p>
</div>
</div>
<div class="sect2">
<h3 id="overview_intrinsics">Built-in support for Intrinsics</h3>
<div class="paragraph">
<p>Most compilers, including GCC, Clang, and Visual C&#43;&#43;, supply  built-in support
for byte swapping intrinsics. The Endian library uses these intrinsics when
available since they may result in smaller and faster generated code,
particularly for optimized builds.</p>
</div>
<div class="paragraph">
<p>Defining the macro <code>BOOST_ENDIAN_NO_INTRINSICS</code> will suppress use of the
intrinsics. This is useful when a compiler has no intrinsic support or fails to
locate the appropriate header, perhaps because it is an older release or has
very limited supporting libraries.</p>
</div>
<div class="paragraph">
<p>The macro <code>BOOST_ENDIAN_INTRINSIC_MSG</code> is defined as either
<code>"no byte swap intrinsics"</code> or a string describing the particular set of
intrinsics being used. This is useful for eliminating missing intrinsics as a
source of performance issues.</p>
</div>
</div>
<div class="sect2">
<h3 id="overview_performance">Performance</h3>
<div class="paragraph">
<p>Consider this problem:</p>
</div>
<div class="sect3">
<h4 id="overview_example_1">Example 1</h4>
<div class="paragraph">
<p>Add 100 to a big endian value in a file, then write the result to a file</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Endian arithmetic type approach</th>
<th class="tableblock halign-left valign-top">Endian conversion function approach</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>big_int32_at x;

... read into x from a file ...


x += 100;


... write x to a file ...</pre>
</div>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>int32_t x;

... read into x from a file ...

big_to_native_inplace(x);
x += 100;
native_to_big_inplace(x);

... write x to a file ...</pre>
</div>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><strong>There will be no performance difference between the two approaches in optimized
builds, regardless of the native endianness of the machine.</strong> That&#8217;s because
optimizing compilers will generate exactly the same code for each. That
conclusion was confirmed by studying the generated assembly code for GCC and
Visual C&#43;&#43;. Furthermore, time spent doing I/O will determine the speed of this
application.</p>
</div>
<div class="paragraph">
<p>Now consider a slightly different problem:</p>
</div>
</div>
<div class="sect3">
<h4 id="overview_example_2">Example 2</h4>
<div class="paragraph">
<p>Add a million values to a big endian value in a file, then write the result to a
file</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Endian arithmetic type approach</th>
<th class="tableblock halign-left valign-top">Endian conversion function approach</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>big_int32_at x;

... read into x from a file ...


for (int32_t i = 0; i &lt; 1000000; ++i)
  x += i;


... write x to a file ...</pre>
</div>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
<div class="content">
<pre>int32_t x;

... read into x from a file ...

big_to_native_inplace(x);

for (int32_t i = 0; i &lt; 1000000; ++i)
  x += i;

native_to_big_inplace(x);

... write x to a file ...</pre>
</div>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>With the Endian arithmetic approach, on little endian platforms an implicit
conversion from and then back to big endian is done inside the loop. With the
Endian conversion function approach, the user has ensured the conversions are
done outside the loop, so the code may run more quickly on little endian
platforms.</p>
</div>
</div>
<div class="sect3">
<h4 id="overview_timings">Timings</h4>
<div class="paragraph">
<p>These tests were run against release builds on a circa 2012 4-core little endian
X64 Intel Core i5-3570K CPU @ 3.40GHz under Windows 7.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
The Windows CPU timer has very high granularity. Repeated runs of the
same tests often yield considerably different results.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>See <code>test/loop_time_test.cpp</code> for the actual code and <code>benchmark/Jamfile.v2</code> for
the build setup.</p>
</div>
<div class="sect4">
<h5 id="overview_gnu_c_version_4_8_2_on_linux_virtual_machine">GNU C++ version 4.8.2 on Linux virtual machine</h5>
<div class="paragraph">
<p>Iterations: 10'000'000'000, Intrinsics: <code>__builtin_bswap16</code>, etc.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Test Case</th>
<th class="tableblock halign-left valign-top">Endian arithmetic type</th>
<th class="tableblock halign-left valign-top">Endian conversion function</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">16-bit aligned big endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8.46 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5.28 s</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">16-bit aligned little endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5.28 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5.22 s</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">32-bit aligned big endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8.40 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2.11 s</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">32-bit aligned little endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2.11 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2.10 s</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">64-bit aligned big endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">14.02 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">3.10 s</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">64-bit aligned little endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">3.00 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">3.03 s</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="overview_microsoft_visual_c_version_14_0">Microsoft Visual C++ version 14.0</h5>
<div class="paragraph">
<p>Iterations: 10'000'000'000, Intrinsics: <code>&lt;cstdlib&gt;</code> <code>_byteswap_ushort</code>, etc.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Test Case</th>
<th class="tableblock halign-left valign-top">Endian arithmetic type</th>
<th class="tableblock halign-left valign-top">Endian conversion function</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">16-bit aligned big endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8.27 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5.26 s</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">16-bit aligned little endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5.29 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5.32 s</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">32-bit aligned big endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8.36 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5.24 s</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">32-bit aligned little endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5.24 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">5.24 s</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">64-bit aligned big endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">13.65 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">3.34 s</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">64-bit aligned little endian</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">3.35 s</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2.73 s</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="overview_faq">Overall FAQ</h3>
<div class="dlist">
<dl>
<dt class="hdlist1">Is the implementation header only?</dt>
<dd>
<p>Yes.</p>
</dd>
<dt class="hdlist1">Are C&#43;&#43;03 compilers supported?</dt>
<dd>
<p>Yes.</p>
</dd>
<dt class="hdlist1">Does the implementation use compiler intrinsic built-in byte swapping?</dt>
<dd>
<p>Yes, if available. See <a href="#overview_intrinsics">Intrinsic built-in support</a>.</p>
</dd>
<dt class="hdlist1">Why bother with endianness?</dt>
<dd>
<p>Binary data portability is the primary use case.</p>
</dd>
<dt class="hdlist1">Does endianness have any uses outside of portable binary file or network I/O formats?</dt>
<dd>
<p>Using the unaligned integer types with a size tailored to the application&#8217;s
needs is a minor secondary use that saves internal or external memory space. For
example, using <code>big_int40_buf_t</code> or <code>big_int40_t</code> in a large array saves a lot
of space compared to one of the 64-bit types.</p>
</dd>
<dt class="hdlist1">Why bother with binary I/O? Why not just use C&#43;&#43; Standard Library stream inserters and extractors?</dt>
<dd>
<div class="ulist">
<ul>
<li>
<p>Data interchange formats often specify binary integer data. Binary integer
data is smaller and therefore I/O is faster and file sizes are smaller. Transfer
between systems is less expensive.</p>
</li>
<li>
<p>Furthermore, binary integer data is of fixed size, and so fixed-size disk
records are possible without padding, easing sorting and allowing random access.</p>
</li>
<li>
<p>Disadvantages, such as the inability to use text utilities on the resulting
files, limit usefulness to applications where the binary I/O advantages are
paramount.</p>
</li>
</ul>
</div>
</dd>
<dt class="hdlist1">Which is better, big-endian or little-endian?</dt>
<dd>
<p>Big-endian tends to be preferred in a networking environment and is a bit more
of an industry standard, but little-endian may be preferred for applications
that run primarily on x86, x86-64, and other little-endian CPU&#8217;s. The
<a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> article gives more pros and cons.</p>
</dd>
<dt class="hdlist1">Why are only big and little native endianness supported?</dt>
<dd>
<p>These are the only endian schemes that have any practical value today. PDP-11
and the other middle endian approaches are interesting  curiosities but have no
relevance for today&#8217;s C&#43;&#43; developers. The same is true for architectures that
allow runtime endianness switching. The
<a href="#conversion_native_order_specification">specification for native ordering</a> has
been carefully crafted to allow support for such orderings in the future, should
the need arise. Thanks to Howard Hinnant for suggesting this.</p>
</dd>
<dt class="hdlist1">Why do both the buffer and arithmetic types exist?</dt>
<dd>
<p>Conversions in the buffer types are explicit. Conversions in the arithmetic
types are implicit. This fundamental difference is a deliberate design feature
that would be lost if the inheritance hierarchy were collapsed.
The original design provided only arithmetic types. Buffer types were requested
during formal review by those wishing total control over when conversion occurs.
They also felt that buffer types would be less likely to be misused by
maintenance programmers not familiar with the implications of performing a lot
of integer operations on the endian arithmetic integer types.</p>
</dd>
<dt class="hdlist1">What is gained by using the buffer types rather than always just using the arithmetic types?</dt>
<dd>
<p>Assurance that hidden conversions are not performed. This is of overriding
importance to users concerned about achieving the ultimate in terms of speed.
"Always just using the arithmetic types" is fine for other users. When the
ultimate in speed needs to be ensured, the arithmetic types can be used in the
same design patterns or idioms that would be used for buffer types, resulting in
the same code being generated for either types.</p>
</dd>
<dt class="hdlist1">What are the limitations of integer support?</dt>
<dd>
<p>Tests have only been performed on machines that  use two&#8217;s complement
arithmetic. The Endian conversion functions only support 16, 32, and 64-bit
aligned integers. The endian types only support 8, 16, 24, 32, 40, 48, 56, and
64-bit unaligned integers, and 8, 16, 32, and 64-bit aligned integers.</p>
</dd>
<dt class="hdlist1">Why is there no floating point support?</dt>
<dd>
<p>An attempt was made to support four-byte <code>float</code>s and eight-byte
<code>double</code>s, limited to
<a href="http://en.wikipedia.org/wiki/IEEE_floating_point">IEEE 754</a> (also known as
ISO/IEC/IEEE 60559) floating point and further limited to systems where floating
point endianness does not differ from integer endianness. Even with those
limitations, support for floating point types was not reliable and was removed.
For example, simply reversing the endianness of a floating point number can
result in a signaling-NAN. For all practical purposes, binary serialization and
endianness for integers are one and the same problem. That is not true for
floating point numbers, so binary serialization interfaces and formats for
floating point does not fit well in an endian-based library.</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="overview_history">History</h3>
<div class="sect3">
<h4 id="overview_changes_requested_by_formal_review">Changes requested by formal review</h4>
<div class="paragraph">
<p>The library was reworked from top to bottom to accommodate changes requested
during the formal review. See <a href="#appendix_mini_review_topics">Mini-Review</a>
page for details.</p>
</div>
</div>
<div class="sect3">
<h4 id="overview_other_changes_since_formal_review">Other changes since formal review</h4>
<div class="ulist">
<ul>
<li>
<p>Header <code>boost/endian/endian.hpp</code> has been renamed to
<code>boost/endian/arithmetic.hpp</code>. Headers
<code>boost/endian/conversion.hpp</code> and <code>boost/endian/buffers.hpp</code> have been added.
Infrastructure file names were changed accordingly.</p>
</li>
<li>
<p>The endian arithmetic type aliases have been renamed, using a naming pattern
that is consistent for both integer and floating point, and a consistent set of
aliases supplied for the endian buffer types.</p>
</li>
<li>
<p>The unaligned-type alias names still have the <code>_t</code> suffix, but the
aligned-type alias names now have an <code>_at</code> suffix.</p>
</li>
<li>
<p><code>endian_reverse()</code> overloads for <code>int8_t</code> and <code>uint8_t</code> have been added for
improved generality. (Pierre Talbot)</p>
</li>
<li>
<p>Overloads of <code>endian_reverse_inplace()</code> have been replaced with a single
<code>endian_reverse_inplace()</code> template. (Pierre Talbot)</p>
</li>
<li>
<p>For X86 and X64 architectures, which permit unaligned loads and stores,
unaligned little endian buffer and arithmetic types use regular loads and
stores when the size is exact. This makes unaligned little endian buffer and
arithmetic types significantly more efficient on these architectures. (Jeremy
Maitin-Shepard)</p>
</li>
<li>
<p>C&#43;&#43;11 features affecting interfaces, such as <code>noexcept</code>, are now used.
C&#43;&#43;03 compilers are still supported.</p>
</li>
<li>
<p>Acknowledgements have been updated.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="overview_compatibility_with_interim_releases">Compatibility with interim releases</h3>
<div class="paragraph">
<p>Prior to the official Boost release, class template <code>endian_arithmetic</code> has been
used for a decade or more with the same functionality but under the name
<code>endian</code>. Other names also changed in the official release. If the macro
<code>BOOST_ENDIAN_DEPRECATED_NAMES</code> is defined, those old now deprecated names are
still supported. However, the class template <code>endian</code> name is only provided for
compilers supporting C&#43;&#43;11 template aliases. For C&#43;&#43;03 compilers, the name
will have to be changed to <code>endian_arithmetic</code>.</p>
</div>
<div class="paragraph">
<p>To support backward header compatibility, deprecated header
<code>boost/endian/endian.hpp</code> forwards to <code>boost/endian/arithmetic.hpp</code>. It requires
<code>BOOST_ENDIAN_DEPRECATED_NAMES</code> be defined. It should only be used while
transitioning to the official Boost release of the library as it will be removed
in some future release.</p>
</div>
</div>
<div class="sect2">
<h3 id="overview_cpp03_support">C&#43;&#43;03 support for C&#43;&#43;11 features</h3>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">C&#43;&#43;11 Feature</th>
<th class="tableblock halign-left valign-top">Action with C&#43;&#43;03 Compilers</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Scoped enums</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Uses header
<a href="http://www.boost.org/libs/core/doc/html/core/scoped_enum.html">boost/core/scoped_enum.hpp</a>
to emulate C&#43;&#43;11 scoped enums.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>noexcept</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Uses <code>BOOST_NOEXCEPT</code> macro, which is defined as null for compilers not
supporting this C&#43;&#43;11 feature.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">C&#43;&#43;11 PODs
(<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2342.htm">N2342</a>)</p></td>
<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
Limitations <a href="#buffers_limitations">here</a> and <a href="#arithmetic_limitations">here</a>.
Also see macros for explicit POD control <a href="#buffers_compilation">here</a> and
<a href="#arithmetic_compilation">here</a></p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="overview_future_directions">Future directions</h3>
<div class="dlist">
<dl>
<dt class="hdlist1">Standardization.</dt>
<dd>
<p>The plan is to submit Boost.Endian to the C&#43;&#43; standards committee for possible
inclusion in a Technical Specification or the C&#43;&#43; standard itself.</p>
</dd>
<dt class="hdlist1">Specializations for <code>numeric_limits</code>.</dt>
<dd>
<p>Roger Leigh requested that all <code>boost::endian</code> types provide <code>numeric_limits</code>
specializations.
See <a href="https://github.com/boostorg/endian/issues/4">GitHub issue 4</a>.</p>
</dd>
<dt class="hdlist1">Character buffer support.</dt>
<dd>
<p>Peter Dimov pointed out during the mini-review that getting and setting basic
arithmetic types (or <code>&lt;cstdint&gt;</code> equivalents) from/to an offset into an array of
unsigned char is a common need. See
<a href="http://lists.boost.org/Archives/boost/2015/01/219574.php">Boost.Endian
mini-review posting</a>.</p>
</dd>
<dt class="hdlist1">Out-of-range detection.</dt>
<dd>
<p>Peter Dimov pointed suggested during the mini-review that throwing an exception
on buffer values being out-of-range might be desirable. See the end of
<a href="http://lists.boost.org/Archives/boost/2015/01/219659.php">this posting</a> and
subsequent replies.</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="overview_acknowledgements">Acknowledgements</h3>
<div class="paragraph">
<p>Comments and suggestions were received from Adder, Benaka Moorthi, Christopher
Kohlhoff, Cliff Green, Daniel James, Dave Handley, Gennaro Proto, Giovanni Piero
Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Howard Hinnant, Jason Newton,
Jeff Flinn, Jeremy Maitin-Shepard, John Filo, John Maddock, Kim Barrett, Marsh
Ray, Martin Bonner, Mathias Gaunard, Matias Capeletto, Neil Mayhew, Nevin Liber,
Olaf van der Spek, Paul Bristow, Peter Dimov, Pierre Talbot, Phil Endecott,
Philip Bennefall, Pyry Jahkola, Rene Rivera, Robert Stewart, Roger Leigh, Roland
Schwarz, Scott McMurray, Sebastian Redl, Tim Blechmann, Tim Moore, tymofey,
Tomas Puverle, Vincente Botet, Yuval Ronen and Vitaly Budovsk. Apologies if
anyone has been missed.</p>
</div>
<div class="paragraph">
<p>The documentation was converted into Asciidoc format by Glen Fernandes.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="changelog">Revision History</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="overview_changes_in_1_72_0">Changes in 1.72.0</h3>
<div class="ulist">
<ul>
<li>
<p>Made <code>endian_reverse</code>, <code>conditional_reverse</code> and <code>*_to_*</code> <code>constexpr</code>
on GCC and Clang</p>
</li>
<li>
<p>Added convenience load and store functions</p>
</li>
<li>
<p>Added floating point convenience typedefs</p>
</li>
<li>
<p>Added a non-const overload of <code>data()</code>; changed its return type to <code>unsigned char*</code></p>
</li>
<li>
<p>Added <code>__int128</code> support to <code>endian_reverse</code> when available</p>
</li>
<li>
<p>Added a convenience header <code>boost/endian.hpp</code></p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="overview_changes_in_1_71_0">Changes in 1.71.0</h3>
<div class="ulist">
<ul>
<li>
<p>Clarified requirements on the value type template parameter</p>
</li>
<li>
<p>Added support for <code>float</code> and <code>double</code></p>
</li>
<li>
<p>Added <code>endian_load</code>, <code>endian_store</code></p>
</li>
<li>
<p>Updated <code>endian_reverse</code> to correctly support all non-<code>bool</code> integral types</p>
</li>
<li>
<p>Moved deprecated names to the deprecated header <code>endian.hpp</code></p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="conversion">Endian Conversion Functions</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="conversion_introduction">Introduction</h3>
<div class="paragraph">
<p>Header <code>boost/endian/conversion.hpp</code> provides byte order reversal and conversion
functions that convert objects of the built-in integer types between native,
big, or little endian byte ordering. User defined types are also supported.</p>
</div>
</div>
<div class="sect2">
<h3 id="conversion_reference">Reference</h3>
<div class="paragraph">
<p>Functions are implemented <code>inline</code> if appropriate. For C&#43;&#43;03 compilers,
<code>noexcept</code> is elided. Boost scoped enum emulation is used so that the library
still works for compilers that do not support scoped enums.</p>
</div>
<div class="sect3">
<h4 id="conversion_definitions">Definitions</h4>
<div class="paragraph">
<p><strong>Endianness</strong> refers to the ordering of bytes within internal or external
integers and other arithmetic data. Most-significant byte first is called
<strong>big endian</strong> ordering. Least-significant byte first is called
<strong>little endian</strong> ordering. Other orderings are possible and some CPU
architectures support both big and little ordering.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The names are derived from
<a href="http://en.wikipedia.org/wiki/Jonathan_Swift">Jonathan Swift</a>'s satirical novel
<em><a href="http://en.wikipedia.org/wiki/Gulliver&#8217;s_Travels">Gulliver&#8217;s Travels</a></em>, where
rival kingdoms opened their soft-boiled eggs at different ends. Wikipedia has an
extensive description of <a href="https://en.wikipedia.org/wiki/Endianness">Endianness</a>.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The standard integral types (C&#43;&#43;std 3.9.1) except <code>bool</code> are collectively
called the <strong>endian types</strong>.</p>
</div>
</div>
<div class="sect3">
<h4 id="conversion_header_boostendianconversion_hpp_synopsis">Header <code>&lt;boost/endian/conversion.hpp&gt;</code> Synopsis</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>#define BOOST_ENDIAN_INTRINSIC_MSG \
   &#8220;message describing presence or absence of intrinsics&#8221;

namespace boost
{
namespace endian
{
  enum class order
  {
    native = <code>see below</code>,
    big    = <code>see below</code>,
    little = <code>see below</code>,
  };

  // Byte reversal functions

  template &lt;class Endian&gt;
    Endian endian_reverse(Endian x) noexcept;

  template &lt;class EndianReversible&gt;
    EndianReversible big_to_native(EndianReversible x) noexcept;
  template &lt;class EndianReversible&gt;
    EndianReversible native_to_big(EndianReversible x) noexcept;
  template &lt;class EndianReversible&gt;
    EndianReversible little_to_native(EndianReversible x) noexcept;
  template &lt;class EndianReversible&gt;
    EndianReversible native_to_little(EndianReversible x) noexcept;

  template &lt;order O1, order O2, class EndianReversible&gt;
    EndianReversible conditional_reverse(EndianReversible x) noexcept;
  template &lt;class EndianReversible&gt;
    EndianReversible conditional_reverse(EndianReversible x,
      order order1, order order2) noexcept;

  // In-place byte reversal functions

  template &lt;class EndianReversible&gt;
    void endian_reverse_inplace(EndianReversible&amp; x) noexcept;

  template &lt;class EndianReversibleInplace&gt;
    void big_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;
  template &lt;class EndianReversibleInplace&gt;
    void native_to_big_inplace(EndianReversibleInplace&amp; x) noexcept;
  template &lt;class EndianReversibleInplace&gt;
    void little_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;
  template &lt;class EndianReversibleInplace&gt;
    void native_to_little_inplace(EndianReversibleInplace&amp; x) noexcept;

  template &lt;order O1, order O2, class EndianReversibleInplace&gt;
    void conditional_reverse_inplace(EndianReversibleInplace&amp; x) noexcept;
  template &lt;class EndianReversibleInplace&gt;
   void conditional_reverse_inplace(EndianReversibleInplace&amp; x,
     order order1, order order2) noexcept;

  // Generic load and store functions

  template&lt;class T, std::size_t N, order Order&gt;
    T endian_load( unsigned char const * p ) noexcept;

  template&lt;class T, std::size_t N, order Order&gt;
    void endian_store( unsigned char * p, T const &amp; v ) noexcept;

  // Convenience load functions

  boost::int16_t load_little_s16( unsigned char const * p ) noexcept;
  boost::uint16_t load_little_u16( unsigned char const * p ) noexcept;
  boost::int16_t load_big_s16( unsigned char const * p ) noexcept;
  boost::uint16_t load_big_u16( unsigned char const * p ) noexcept;

  boost::int32_t load_little_s24( unsigned char const * p ) noexcept;
  boost::uint32_t load_little_u24( unsigned char const * p ) noexcept;
  boost::int32_t load_big_s24( unsigned char const * p ) noexcept;
  boost::uint32_t load_big_u24( unsigned char const * p ) noexcept;

  boost::int32_t load_little_s32( unsigned char const * p ) noexcept;
  boost::uint32_t load_little_u32( unsigned char const * p ) noexcept;
  boost::int32_t load_big_s32( unsigned char const * p ) noexcept;
  boost::uint32_t load_big_u32( unsigned char const * p ) noexcept;

  boost::int64_t load_little_s40( unsigned char const * p ) noexcept;
  boost::uint64_t load_little_u40( unsigned char const * p ) noexcept;
  boost::int64_t load_big_s40( unsigned char const * p ) noexcept;
  boost::uint64_t load_big_u40( unsigned char const * p ) noexcept;

  boost::int64_t load_little_s48( unsigned char const * p ) noexcept;
  boost::uint64_t load_little_u48( unsigned char const * p ) noexcept;
  boost::int64_t load_big_s48( unsigned char const * p ) noexcept;
  boost::uint64_t load_big_u48( unsigned char const * p ) noexcept;

  boost::int64_t load_little_s56( unsigned char const * p ) noexcept;
  boost::uint64_t load_little_u56( unsigned char const * p ) noexcept;
  boost::int64_t load_big_s56( unsigned char const * p ) noexcept;
  boost::uint64_t load_big_u56( unsigned char const * p ) noexcept;

  boost::int64_t load_little_s64( unsigned char const * p ) noexcept;
  boost::uint64_t load_little_u64( unsigned char const * p ) noexcept;
  boost::int64_t load_big_s64( unsigned char const * p ) noexcept;
  boost::uint64_t load_big_u64( unsigned char const * p ) noexcept;

  // Convenience store functions

  void store_little_s16( unsigned char * p, boost::int16_t v ) noexcept;
  void store_little_u16( unsigned char * p, boost::uint16_t v ) noexcept;
  void store_big_s16( unsigned char * p, boost::int16_t v ) noexcept;
  void store_big_u16( unsigned char * p, boost::uint16_t v ) noexcept;

  void store_little_s24( unsigned char * p, boost::int32_t v ) noexcept;
  void store_little_u24( unsigned char * p, boost::uint32_t v ) noexcept;
  void store_big_s24( unsigned char * p, boost::int32_t v ) noexcept;
  void store_big_u24( unsigned char * p, boost::uint32_t v ) noexcept;

  void store_little_s32( unsigned char * p, boost::int32_t v ) noexcept;
  void store_little_u32( unsigned char * p, boost::uint32_t v ) noexcept;
  void store_big_s32( unsigned char * p, boost::int32_t v ) noexcept;
  void store_big_u32( unsigned char * p, boost::uint32_t v ) noexcept;

  void store_little_s40( unsigned char * p, boost::int64_t v ) noexcept;
  void store_little_u40( unsigned char * p, boost::uint64_t v ) noexcept;
  void store_big_s40( unsigned char * p, boost::int64_t v ) noexcept;
  void store_big_u40( unsigned char * p, boost::uint64_t v ) noexcept;

  void store_little_s48( unsigned char * p, boost::int64_t v ) noexcept;
  void store_little_u48( unsigned char * p, boost::uint64_t v ) noexcept;
  void store_big_s48( unsigned char * p, boost::int64_t v ) noexcept;
  void store_big_u48( unsigned char * p, boost::uint64_t v ) noexcept;

  void store_little_s56( unsigned char * p, boost::int64_t v ) noexcept;
  void store_little_u56( unsigned char * p, boost::uint64_t v ) noexcept;
  void store_big_s56( unsigned char * p, boost::int64_t v ) noexcept;
  void store_big_u56( unsigned char * p, boost::uint64_t v ) noexcept;

  void store_little_s64( unsigned char * p, boost::int64_t v ) noexcept;
  void store_little_u64( unsigned char * p, boost::uint64_t v ) noexcept;
  void store_big_s64( unsigned char * p, boost::int64_t v ) noexcept;
  void store_big_u64( unsigned char * p, boost::uint64_t v ) noexcept;

} // namespace endian
} // namespace boost</code></pre>
</div>
</div>
<div class="paragraph">
<p>The values of <code>order::little</code> and <code>order::big</code> shall not be equal to one
another.</p>
</div>
<div class="paragraph">
<p>The value of <code>order::native</code> shall be:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>equal to <code>order::big</code> if the execution environment is big endian, otherwise</p>
</li>
<li>
<p>equal to <code>order::little</code> if the execution environment is little endian,
otherwise</p>
</li>
<li>
<p>unequal to both <code>order::little</code> and <code>order::big</code>.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="conversion_requirements">Requirements</h4>
<div class="sect4">
<h5 id="conversion_template_argument_requirements">Template argument requirements</h5>
<div class="paragraph">
<p>The template definitions in the <code>boost/endian/conversion.hpp</code> header refer to
various named requirements whose details are set out in the tables in this
subsection. In these tables, <code>T</code> is an object or reference type to be supplied
by a C&#43;&#43; program instantiating a template; <code>x</code> is a value of type (possibly
<code>const</code>) <code>T</code>; <code>mlx</code> is a modifiable lvalue of type <code>T</code>.</p>
</div>
<div class="sect5">
<h6 id="conversion_endianreversible">EndianReversible requirements (in addition to <code>CopyConstructible</code>)</h6>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Expression</th>
<th class="tableblock halign-left valign-top">Return</th>
<th class="tableblock halign-left valign-top">Requirements</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>endian_reverse(x)</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>T</code></p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>T</code> is an endian type or a class type.</p>
</div>
<div class="paragraph">
<p>If <code>T</code> is an endian type, returns the value of <code>x</code> with the order of bytes
reversed.</p>
</div>
<div class="paragraph">
<p>If <code>T</code> is a class type, the function:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Returns the value of <code>x</code> with the order of bytes reversed for all data members
of types or arrays of types that meet the <code>EndianReversible</code> requirements, and;</p>
</li>
<li>
<p>Is a non-member function in the same namespace as <code>T</code> that can be found by
argument dependent lookup (ADL).</p>
</li>
</ul>
</div></div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect5">
<h6 id="conversion_endianreversibleinplace">EndianReversibleInplace requirements (in addition to <code>CopyConstructible</code>)</h6>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Expression</th>
<th class="tableblock halign-left valign-top">Requirements</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>endian_reverse_inplace(mlx)</code></p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><code>T</code> is an endian type or a class type.</p>
</div>
<div class="paragraph">
<p>If <code>T</code> is an endian type, reverses the order of bytes in <code>mlx</code>.</p>
</div>
<div class="paragraph">
<p>If <code>T</code> is a class type, the function:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Reverses the order of bytes of all data members of <code>mlx</code> that have types or
arrays of types that meet the <code>EndianReversible</code> or <code>EndianReversibleInplace</code>
requirements, and;</p>
</li>
<li>
<p>Is a non-member function in the same namespace as <code>T</code> that can be found by
argument dependent lookup (ADL).</p>
</li>
</ul>
</div></div></td>
</tr>
</tbody>
</table>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Because there is a function template for <code>endian_reverse_inplace</code> that
calls <code>endian_reverse</code>, only <code>endian_reverse</code> is required for a user-defined
type to meet the <code>EndianReversibleInplace</code> requirements. Although User-defined
types are not required to supply an <code>endian_reverse_inplace</code> function, doing so
may improve efficiency.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect4">
<h5 id="conversion_customization_points_for_user_defined_types_udts">Customization points for user-defined types (UDTs)</h5>
<div class="paragraph">
<p>This subsection describes requirements on the Endian library&#8217;s  implementation.</p>
</div>
<div class="paragraph">
<p>The library&#8217;s function templates requiring
<code><a href="#conversion_endianreversible">EndianReversible</a></code> are required to perform
reversal of endianness if needed by making an unqualified call to
<code>endian_reverse()</code>.</p>
</div>
<div class="paragraph">
<p>The library&#8217;s function templates requiring
<code><a href="#conversion_endianreversibleinplace">EndianReversibleInplace</a></code> are required to
perform reversal of endianness if needed by making an unqualified call to
<code>endian_reverse_inplace()</code>.</p>
</div>
<div class="paragraph">
<p>See <code>example/udt_conversion_example.cpp</code> for an example user-defined type.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="conversion_byte_reversal_functions">Byte Reversal Functions</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class Endian&gt;
Endian endian_reverse(Endian x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Requires</dt>
<dd>
<p><code>Endian</code> must be a standard integral type that is not <code>bool</code>.</p>
</dd>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>x</code>, with the order of its constituent bytes reversed.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversible&gt;
EndianReversible big_to_native(EndianReversible x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>conditional_reverse&lt;order::big, order::native&gt;(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversible&gt;
EndianReversible native_to_big(EndianReversible x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>conditional_reverse&lt;order::native, order::big&gt;(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversible&gt;
EndianReversible little_to_native(EndianReversible x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>conditional_reverse&lt;order::little, order::native&gt;(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversible&gt;
EndianReversible native_to_little(EndianReversible x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>conditional_reverse&lt;order::native, order::little&gt;(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;order O1, order O2, class EndianReversible&gt;
EndianReversible conditional_reverse(EndianReversible x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>x</code> if <code>O1 == O2,</code> otherwise <code>endian_reverse(x)</code>.</p>
</dd>
<dt class="hdlist1">Remarks</dt>
<dd>
<p>Whether <code>x</code> or <code>endian_reverse(x)</code> is to be returned shall be
determined at compile time.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversible&gt;
EndianReversible conditional_reverse(EndianReversible x,
     order order1, order order2) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>order1 == order2? x: endian_reverse(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="conversion_in_place_byte_reversal_functions">In-place Byte Reversal Functions</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversible&gt;
void endian_reverse_inplace(EndianReversible&amp; x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>x = endian_reverse(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversibleInplace&gt;
void big_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>conditional_reverse_inplace&lt;order::big, order::native&gt;(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversibleInplace&gt;
void native_to_big_inplace(EndianReversibleInplace&amp; x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>conditional_reverse_inplace&lt;order::native, order::big&gt;(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversibleInplace&gt;
void little_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>conditional_reverse_inplace&lt;order::little, order::native&gt;(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversibleInplace&gt;
void native_to_little_inplace(EndianReversibleInplace&amp; x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>conditional_reverse_inplace&lt;order::native, order::little&gt;(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;order O1, order O2, class EndianReversibleInplace&gt;
void conditional_reverse_inplace(EndianReversibleInplace&amp; x) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p>None if <code>O1 == O2,</code> otherwise <code>endian_reverse_inplace(x)</code>.</p>
</dd>
<dt class="hdlist1">Remarks</dt>
<dd>
<p>Which effect applies shall be determined at compile time.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class EndianReversibleInplace&gt;
void conditional_reverse_inplace(EndianReversibleInplace&amp; x,
     order order1, order order2) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p>If <code>order1 == order2</code> then <code>endian_reverse_inplace(x)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="conversion_generic_load_and_store_functions">Generic Load and Store Functions</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template&lt;class T, std::size_t N, order Order&gt;
T endian_load( unsigned char const * p ) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Requires</dt>
<dd>
<p><code>sizeof(T)</code> must be 1, 2, 4, or 8. <code>N</code> must be between 1 and
<code>sizeof(T)</code>, inclusive. <code>T</code> must be trivially copyable. If <code>N</code> is not
equal to <code>sizeof(T)</code>, <code>T</code> must be integral or <code>enum</code>.</p>
</dd>
<dt class="hdlist1">Effects</dt>
<dd>
<p>Reads <code>N</code> bytes starting from <code>p</code>, in forward or reverse order
depending on whether <code>Order</code> matches the native endianness or not,
interprets the resulting bit pattern as a value of type <code>T</code>, and returns it.
If <code>sizeof(T)</code> is bigger than <code>N</code>, zero-extends when <code>T</code> is unsigned,
sign-extends otherwise.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template&lt;class T, std::size_t N, order Order&gt;
void endian_store( unsigned char * p, T const &amp; v ) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Requires</dt>
<dd>
<p><code>sizeof(T)</code> must be 1, 2, 4, or 8. <code>N</code> must be between 1 and
<code>sizeof(T)</code>, inclusive. <code>T</code> must be trivially copyable. If <code>N</code> is not
equal to <code>sizeof(T)</code>, <code>T</code> must be integral or <code>enum</code>.</p>
</dd>
<dt class="hdlist1">Effects</dt>
<dd>
<p>Writes to <code>p</code> the <code>N</code> least significant bytes from the object
representation of <code>v</code>, in forward or reverse order depending on whether
<code>Order</code> matches the native endianness or not.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="conversion_convenience_load_functions">Convenience Load Functions</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>inline boost::intM_t load_little_sN( unsigned char const * p ) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="paragraph">
<p>Reads an N-bit signed little-endian integer from <code>p</code>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>endian_load&lt;boost::intM_t, N/8, order::little&gt;( p )</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>inline boost::uintM_t load_little_uN( unsigned char const * p ) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="paragraph">
<p>Reads an N-bit unsigned little-endian integer from <code>p</code>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>endian_load&lt;boost::uintM_t, N/8, order::little&gt;( p )</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>inline boost::intM_t load_big_sN( unsigned char const * p ) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="paragraph">
<p>Reads an N-bit signed big-endian integer from <code>p</code>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>endian_load&lt;boost::intM_t, N/8, order::big&gt;( p )</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>inline boost::uintM_t load_big_uN( unsigned char const * p ) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="paragraph">
<p>Reads an N-bit unsigned big-endian integer from <code>p</code>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>endian_load&lt;boost::uintM_t, N/8, order::big&gt;( p )</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="conversion_convenience_store_functions">Convenience Store Functions</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>inline void store_little_sN( unsigned char * p, boost::intM_t v ) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="paragraph">
<p>Writes an N-bit signed little-endian integer to <code>p</code>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>endian_store&lt;boost::intM_t, N/8, order::little&gt;( p, v )</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>inline void store_little_uN( unsigned char * p, boost::uintM_t v ) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="paragraph">
<p>Writes an N-bit unsigned little-endian integer to <code>p</code>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>endian_store&lt;boost::uintM_t, N/8, order::little&gt;( p, v )</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>inline void store_big_sN( unsigned char * p, boost::intM_t v ) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="paragraph">
<p>Writes an N-bit signed big-endian integer to <code>p</code>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>endian_store&lt;boost::intM_t, N/8, order::big&gt;( p, v )</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>inline void store_big_uN( unsigned char * p, boost::uintM_t v ) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="paragraph">
<p>Writes an N-bit unsigned big-endian integer to <code>p</code>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>endian_store&lt;boost::uintM_t, N/8, order::big&gt;( p, v )</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="conversion_faq">FAQ</h3>
<div class="paragraph">
<p>See the <a href="#overview_faq">Overview FAQ</a> for a library-wide FAQ.</p>
</div>
<div class="paragraph">
<p><strong>Why are both value returning and modify-in-place functions provided?</strong></p>
</div>
<div class="ulist">
<ul>
<li>
<p>Returning the result by value is the standard C and C&#43;&#43; idiom for functions
that compute a value from an argument. Modify-in-place functions allow cleaner
code in many real-world endian use cases and are more efficient for user-defined
types that have members such as string data that do not need to be reversed.
Thus both forms are provided.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p><strong>Why not use the Linux names (htobe16, htole16, be16toh, le16toh, etc.) ?</strong></p>
</div>
<div class="ulist">
<ul>
<li>
<p>Those names are non-standard and vary even between POSIX-like operating
systems. A C&#43;&#43; library TS was going to use those names, but found they were
sometimes implemented as macros. Since macros do not respect scoping and
namespace rules, to use them would be very error prone.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="conversion_acknowledgements">Acknowledgements</h3>
<div class="paragraph">
<p>Tomas Puverle was instrumental in identifying and articulating the need to
support endian conversion as separate from endian integer types. Phil Endecott
suggested the form of the value returning signatures. Vicente Botet and other
reviewers suggested supporting  user defined types. General reverse template
implementation approach using <code>std::reverse</code> suggested by Mathias Gaunard.
Portable implementation approach for 16, 32, and 64-bit integers suggested by
tymofey, with avoidance of undefined behavior as suggested by Giovanni Piero
Deretta, and a further refinement suggested by Pyry Jahkola. Intrinsic builtins
implementation approach for 16, 32, and 64-bit integers suggested by several
reviewers, and by David Stone, who provided his Boost licensed macro
implementation that became the starting point for
<code>boost/endian/detail/intrinsic.hpp</code>.  Pierre Talbot provided the
<code>int8_t endian_reverse()</code> and templated <code>endian_reverse_inplace()</code>
implementations.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="buffers">Endian Buffer Types</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="buffers_introduction">Introduction</h3>
<div class="paragraph">
<p>The internal byte order of arithmetic types is traditionally called
<strong>endianness</strong>. See the <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> for a full
exploration of <strong>endianness</strong>, including definitions of <strong>big endian</strong> and <strong>little
endian</strong>.</p>
</div>
<div class="paragraph">
<p>Header <code>boost/endian/buffers.hpp</code> provides <code>endian_buffer</code>, a portable endian
integer binary buffer class template with control over byte order, value type,
size, and alignment independent of the platform&#8217;s native endianness. Typedefs
provide easy-to-use names for common configurations.</p>
</div>
<div class="paragraph">
<p>Use cases primarily involve data portability, either via files or network
connections, but these byte-holders may also be used to reduce memory use, file
size, or network activity since they provide binary numeric sizes not otherwise
available.</p>
</div>
<div class="paragraph">
<p>Class <code>endian_buffer</code> is aimed at users who wish explicit control over when
endianness conversions occur. It also serves as the base class for the
<a href="#arithmetic">endian_arithmetic</a> class template, which is aimed at users who
wish fully automatic endianness conversion and direct support for all normal
arithmetic operations.</p>
</div>
</div>
<div class="sect2">
<h3 id="buffers_example">Example</h3>
<div class="paragraph">
<p>The <code>example/endian_example.cpp</code> program writes a binary file containing
four-byte, big-endian and little-endian integers:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>#include &lt;iostream&gt;
#include &lt;cstdio&gt;
#include &lt;boost/endian/buffers.hpp&gt;  // see Synopsis below
#include &lt;boost/static_assert.hpp&gt;

using namespace boost::endian;

namespace
{
  //  This is an extract from a very widely used GIS file format.
  //  Why the designer decided to mix big and little endians in
  //  the same file is not known. But this is a real-world format
  //  and users wishing to write low level code manipulating these
  //  files have to deal with the mixed endianness.

  struct header
  {
    big_int32_buf_t     file_code;
    big_int32_buf_t     file_length;
    little_int32_buf_t  version;
    little_int32_buf_t  shape_type;
  };

  const char* filename = "test.dat";
}

int main(int, char* [])
{
  header h;

  BOOST_STATIC_ASSERT(sizeof(h) == 16U);  // reality check

  h.file_code   = 0x01020304;
  h.file_length = sizeof(header);
  h.version     = 1;
  h.shape_type  = 0x01020304;

  //  Low-level I/O such as POSIX read/write or &lt;cstdio&gt;
  //  fread/fwrite is sometimes used for binary file operations
  //  when ultimate efficiency is important. Such I/O is often
  //  performed in some C++ wrapper class, but to drive home the
  //  point that endian integers are often used in fairly
  //  low-level code that does bulk I/O operations, &lt;cstdio&gt;
  //  fopen/fwrite is used for I/O in this example.

  std::FILE* fi = std::fopen(filename, "wb");  // MUST BE BINARY

  if (!fi)
  {
    std::cout &lt;&lt; "could not open " &lt;&lt; filename &lt;&lt; '\n';
    return 1;
  }

  if (std::fwrite(&amp;h, sizeof(header), 1, fi) != 1)
  {
    std::cout &lt;&lt; "write failure for " &lt;&lt; filename &lt;&lt; '\n';
    return 1;
  }

  std::fclose(fi);

  std::cout &lt;&lt; "created file " &lt;&lt; filename &lt;&lt; '\n';

  return 0;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>After compiling and executing <code>example/endian_example.cpp</code>, a hex dump of
<code>test.dat</code> shows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>01020304 00000010 01000000 04030201</code></pre>
</div>
</div>
<div class="paragraph">
<p>Notice that the first two 32-bit integers are big endian while the second two
are little endian, even though the machine this was compiled and run on was
little endian.</p>
</div>
</div>
<div class="sect2">
<h3 id="buffers_limitations">Limitations</h3>
<div class="paragraph">
<p>Requires <code>&lt;climits&gt;</code>, <code>CHAR_BIT == 8</code>. If <code>CHAR_BIT</code> is some other value,
compilation will result in an <code>#error</code>. This restriction is in place because the
design, implementation, testing, and documentation has only considered issues
related to 8-bit bytes, and there have been no real-world use cases presented
for other sizes.</p>
</div>
<div class="paragraph">
<p>In C&#43;&#43;03, <code>endian_buffer</code> does not meet the requirements for POD types because
it has constructors and a private data member. This means that
common use cases are relying on unspecified behavior in that the C&#43;&#43; Standard
does not guarantee memory layout for non-POD types. This has not been a problem
in practice since all known C&#43;&#43; compilers  lay out memory as if <code>endian</code> were
a POD type. In C&#43;&#43;11, it is possible to specify the default constructor as
trivial, and private data members and base classes  no longer disqualify a type
from being a POD type. Thus under C&#43;&#43;11, <code>endian_buffer</code> will no longer be
relying on unspecified behavior.</p>
</div>
</div>
<div class="sect2">
<h3 id="buffers_feature_set">Feature set</h3>
<div class="ulist">
<ul>
<li>
<p>Big endian| little endian | native endian byte ordering.</p>
</li>
<li>
<p>Signed | unsigned</p>
</li>
<li>
<p>Unaligned | aligned</p>
</li>
<li>
<p>1-8 byte (unaligned) | 1, 2, 4, 8 byte (aligned)</p>
</li>
<li>
<p>Choice of  value type</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="buffers_enums_and_typedefs">Enums and typedefs</h3>
<div class="paragraph">
<p>Two scoped enums are provided:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>enum class order { big, little, native };

enum class align { no, yes };</code></pre>
</div>
</div>
<div class="paragraph">
<p>One class template is provided:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;order Order, typename T, std::size_t Nbits,
  align Align = align::no&gt;
class endian_buffer;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Typedefs, such as <code>big_int32_buf_t</code>, provide convenient naming conventions for
common use cases:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Alignment</th>
<th class="tableblock halign-left valign-top">Endianness</th>
<th class="tableblock halign-left valign-top">Sign</th>
<th class="tableblock halign-left valign-top">Sizes in bits (n)</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_intN_buf_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_uintN_buf_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_intN_buf_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_uintN_buf_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>native_intN_buf_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">native</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>native_uintN_buf_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">native</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_intN_buf_at</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_uintN_buf_at</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_intN_buf_at</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_uintN_buf_at</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The unaligned types do not cause compilers to insert padding bytes in classes
and structs. This is an important characteristic that can be exploited to
minimize wasted space in memory, files, and network transmissions.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
Code that uses aligned types is possibly non-portable because alignment
requirements vary between hardware architectures and because alignment may be
affected by compiler switches or pragmas. For example, alignment of an 64-bit
integer may be to a 32-bit boundary on a 32-bit machine and to a 64-bit boundary
on a 64-bit machine. Furthermore, aligned types are only available on
architectures with 8, 16, 32, and 64-bit integer types.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<div class="title">Tip</div>
</td>
<td class="content">
Prefer unaligned buffer types.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<div class="title">Tip</div>
</td>
<td class="content">
Protect yourself against alignment ills. For example:
</td>
</tr>
</table>
</div>
<div class="dlist none">
<dl>
<dt></dt>
<dd>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>static_assert(sizeof(containing_struct) == 12, "sizeof(containing_struct) is wrong");</code></pre>
</div>
</div>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Note: One-byte big and little buffer types have identical layout on all
platforms, so they never actually reverse endianness. They are provided to
enable generic code, and to improve code readability and searchability.</p>
</div>
</div>
<div class="sect2">
<h3 id="buffers_class_template_endian_buffer">Class template <code>endian_buffer</code></h3>
<div class="paragraph">
<p>An <code>endian_buffer</code> is a byte-holder for arithmetic types with
user-specified endianness, value type, size, and alignment.</p>
</div>
<div class="sect3">
<h4 id="buffers_synopsis">Synopsis</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>namespace boost
{
  namespace endian
  {
    //  C++11 features emulated if not available

    enum class align { no, yes };

    template &lt;order Order, class T, std::size_t Nbits,
      align Align = align::no&gt;
    class endian_buffer
    {
    public:

      typedef T value_type;

      endian_buffer() noexcept = default;
      explicit endian_buffer(T v) noexcept;

      endian_buffer&amp; operator=(T v) noexcept;
      value_type value() const noexcept;
      unsigned char* data() noexcept;
      unsigned char const* data() const noexcept;

    private:

      unsigned char value_[Nbits / CHAR_BIT]; // exposition only
    };

    //  stream inserter
    template &lt;class charT, class traits, order Order, class T,
      std::size_t n_bits, align Align&gt;
    std::basic_ostream&lt;charT, traits&gt;&amp;
      operator&lt;&lt;(std::basic_ostream&lt;charT, traits&gt;&amp; os,
        const endian_buffer&lt;Order, T, n_bits, Align&gt;&amp; x);

    //  stream extractor
    template &lt;class charT, class traits, order Order, class T,
      std::size_t n_bits, align A&gt;
    std::basic_istream&lt;charT, traits&gt;&amp;
      operator&gt;&gt;(std::basic_istream&lt;charT, traits&gt;&amp; is,
        endian_buffer&lt;Order, T, n_bits, Align&gt;&amp; x);

    // typedefs

    // unaligned big endian signed integer buffers
    typedef endian_buffer&lt;order::big, int_least8_t, 8&gt;        big_int8_buf_t;
    typedef endian_buffer&lt;order::big, int_least16_t, 16&gt;      big_int16_buf_t;
    typedef endian_buffer&lt;order::big, int_least32_t, 24&gt;      big_int24_buf_t;
    typedef endian_buffer&lt;order::big, int_least32_t, 32&gt;      big_int32_buf_t;
    typedef endian_buffer&lt;order::big, int_least64_t, 40&gt;      big_int40_buf_t;
    typedef endian_buffer&lt;order::big, int_least64_t, 48&gt;      big_int48_buf_t;
    typedef endian_buffer&lt;order::big, int_least64_t, 56&gt;      big_int56_buf_t;
    typedef endian_buffer&lt;order::big, int_least64_t, 64&gt;      big_int64_buf_t;

    // unaligned big endian unsigned integer buffers
    typedef endian_buffer&lt;order::big, uint_least8_t, 8&gt;       big_uint8_buf_t;
    typedef endian_buffer&lt;order::big, uint_least16_t, 16&gt;     big_uint16_buf_t;
    typedef endian_buffer&lt;order::big, uint_least32_t, 24&gt;     big_uint24_buf_t;
    typedef endian_buffer&lt;order::big, uint_least32_t, 32&gt;     big_uint32_buf_t;
    typedef endian_buffer&lt;order::big, uint_least64_t, 40&gt;     big_uint40_buf_t;
    typedef endian_buffer&lt;order::big, uint_least64_t, 48&gt;     big_uint48_buf_t;
    typedef endian_buffer&lt;order::big, uint_least64_t, 56&gt;     big_uint56_buf_t;
    typedef endian_buffer&lt;order::big, uint_least64_t, 64&gt;     big_uint64_buf_t;

    // unaligned big endian floating point buffers
    typedef endian_buffer&lt;order::big, float, 32&gt;              big_float32_buf_t;
    typedef endian_buffer&lt;order::big, double, 64&gt;             big_float64_buf_t;

    // unaligned little endian signed integer buffers
    typedef endian_buffer&lt;order::little, int_least8_t, 8&gt;     little_int8_buf_t;
    typedef endian_buffer&lt;order::little, int_least16_t, 16&gt;   little_int16_buf_t;
    typedef endian_buffer&lt;order::little, int_least32_t, 24&gt;   little_int24_buf_t;
    typedef endian_buffer&lt;order::little, int_least32_t, 32&gt;   little_int32_buf_t;
    typedef endian_buffer&lt;order::little, int_least64_t, 40&gt;   little_int40_buf_t;
    typedef endian_buffer&lt;order::little, int_least64_t, 48&gt;   little_int48_buf_t;
    typedef endian_buffer&lt;order::little, int_least64_t, 56&gt;   little_int56_buf_t;
    typedef endian_buffer&lt;order::little, int_least64_t, 64&gt;   little_int64_buf_t;

    // unaligned little endian unsigned integer buffers
    typedef endian_buffer&lt;order::little, uint_least8_t, 8&gt;    little_uint8_buf_t;
    typedef endian_buffer&lt;order::little, uint_least16_t, 16&gt;  little_uint16_buf_t;
    typedef endian_buffer&lt;order::little, uint_least32_t, 24&gt;  little_uint24_buf_t;
    typedef endian_buffer&lt;order::little, uint_least32_t, 32&gt;  little_uint32_buf_t;
    typedef endian_buffer&lt;order::little, uint_least64_t, 40&gt;  little_uint40_buf_t;
    typedef endian_buffer&lt;order::little, uint_least64_t, 48&gt;  little_uint48_buf_t;
    typedef endian_buffer&lt;order::little, uint_least64_t, 56&gt;  little_uint56_buf_t;
    typedef endian_buffer&lt;order::little, uint_least64_t, 64&gt;  little_uint64_buf_t;

    // unaligned little endian floating point buffers
    typedef endian_buffer&lt;order::little, float, 32&gt;           little_float32_buf_t;
    typedef endian_buffer&lt;order::little, double, 64&gt;          little_float64_buf_t;

    // unaligned native endian signed integer types
    typedef implementation-defined_int8_buf_t   native_int8_buf_t;
    typedef implementation-defined_int16_buf_t  native_int16_buf_t;
    typedef implementation-defined_int24_buf_t  native_int24_buf_t;
    typedef implementation-defined_int32_buf_t  native_int32_buf_t;
    typedef implementation-defined_int40_buf_t  native_int40_buf_t;
    typedef implementation-defined_int48_buf_t  native_int48_buf_t;
    typedef implementation-defined_int56_buf_t  native_int56_buf_t;
    typedef implementation-defined_int64_buf_t  native_int64_buf_t;

    // unaligned native endian unsigned integer types
    typedef implementation-defined_uint8_buf_t   native_uint8_buf_t;
    typedef implementation-defined_uint16_buf_t  native_uint16_buf_t;
    typedef implementation-defined_uint24_buf_t  native_uint24_buf_t;
    typedef implementation-defined_uint32_buf_t  native_uint32_buf_t;
    typedef implementation-defined_uint40_buf_t  native_uint40_buf_t;
    typedef implementation-defined_uint48_buf_t  native_uint48_buf_t;
    typedef implementation-defined_uint56_buf_t  native_uint56_buf_t;
    typedef implementation-defined_uint64_buf_t  native_uint64_buf_t;

    // unaligned native endian floating point types
    typedef implementation-defined_float32_buf_t  native_float32_buf_t;
    typedef implementation-defined_float64_buf_t  native_float64_buf_t;

    // aligned big endian signed integer buffers
    typedef endian_buffer&lt;order::big, int8_t, 8, align::yes&gt;       big_int8_buf_at;
    typedef endian_buffer&lt;order::big, int16_t, 16, align::yes&gt;     big_int16_buf_at;
    typedef endian_buffer&lt;order::big, int32_t, 32, align::yes&gt;     big_int32_buf_at;
    typedef endian_buffer&lt;order::big, int64_t, 64, align::yes&gt;     big_int64_buf_at;

    // aligned big endian unsigned integer buffers
    typedef endian_buffer&lt;order::big, uint8_t, 8, align::yes&gt;      big_uint8_buf_at;
    typedef endian_buffer&lt;order::big, uint16_t, 16, align::yes&gt;    big_uint16_buf_at;
    typedef endian_buffer&lt;order::big, uint32_t, 32, align::yes&gt;    big_uint32_buf_at;
    typedef endian_buffer&lt;order::big, uint64_t, 64, align::yes&gt;    big_uint64_buf_at;

    // aligned big endian floating point buffers
    typedef endian_buffer&lt;order::big, float, 32, align::yes&gt;       big_float32_buf_at;
    typedef endian_buffer&lt;order::big, double, 64, align::yes&gt;      big_float64_buf_at;

    // aligned little endian signed integer buffers
    typedef endian_buffer&lt;order::little, int8_t, 8, align::yes&gt;    little_int8_buf_at;
    typedef endian_buffer&lt;order::little, int16_t, 16, align::yes&gt;  little_int16_buf_at;
    typedef endian_buffer&lt;order::little, int32_t, 32, align::yes&gt;  little_int32_buf_at;
    typedef endian_buffer&lt;order::little, int64_t, 64, align::yes&gt;  little_int64_buf_at;

    // aligned little endian unsigned integer buffers
    typedef endian_buffer&lt;order::little, uint8_t, 8, align::yes&gt;   little_uint8_buf_at;
    typedef endian_buffer&lt;order::little, uint16_t, 16, align::yes&gt; little_uint16_buf_at;
    typedef endian_buffer&lt;order::little, uint32_t, 32, align::yes&gt; little_uint32_buf_at;
    typedef endian_buffer&lt;order::little, uint64_t, 64, align::yes&gt; little_uint64_buf_at;

    // aligned little endian floating point buffers
    typedef endian_buffer&lt;order::little, float, 32, align::yes&gt;    little_float32_buf_at;
    typedef endian_buffer&lt;order::little, double, 64, align::yes&gt;   little_float64_buf_at;

    // aligned native endian typedefs are not provided because
    // &lt;cstdint&gt; types are superior for this use case

  } // namespace endian
} // namespace boost</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>implementation-defined</code> text in typedefs above is either <code>big</code> or <code>little</code>
according to the native endianness of the platform.</p>
</div>
<div class="paragraph">
<p>The expository data member <code>value_</code> stores the current value of the
<code>endian_buffer</code> object as a sequence of bytes ordered as specified by the
<code>Order</code> template parameter. The <code>CHAR_BIT</code> macro is defined in <code>&lt;climits&gt;</code>.
The only supported value of <code>CHAR_BIT</code> is 8.</p>
</div>
<div class="paragraph">
<p>The valid values of <code>Nbits</code> are as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>When <code>sizeof(T)</code> is 1, <code>Nbits</code> shall be 8;</p>
</li>
<li>
<p>When <code>sizeof(T)</code> is 2, <code>Nbits</code> shall be 16;</p>
</li>
<li>
<p>When <code>sizeof(T)</code> is 4, <code>Nbits</code> shall be 24 or 32;</p>
</li>
<li>
<p>When <code>sizeof(T)</code> is 8, <code>Nbits</code> shall be 40, 48, 56, or 64.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Other values of <code>sizeof(T)</code> are not supported.</p>
</div>
<div class="paragraph">
<p>When <code>Nbits</code> is equal to <code>sizeof(T)*8</code>, <code>T</code> must be a trivially copyable type
(such as <code>float</code>) that is assumed to have the same endianness as <code>uintNbits_t</code>.</p>
</div>
<div class="paragraph">
<p>When <code>Nbits</code> is less than <code>sizeof(T)*8</code>, <code>T</code> must be either a standard integral
type (C&#43;&#43;std, [basic.fundamental]) or an <code>enum</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="buffers_members">Members</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>endian_buffer() noexcept = default;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p>Constructs an uninitialized object.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>explicit endian_buffer(T v) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>endian_store&lt;T, Nbits/8, Order&gt;( value_, v )</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>endian_buffer&amp; operator=(T v) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p><code>endian_store&lt;T, Nbits/8, Order&gt;( value_, v )</code>.</p>
</dd>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>*this</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>value_type value() const noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>endian_load&lt;T, Nbits/8, Order&gt;( value_ )</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>unsigned char* data() noexcept;</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>unsigned char const* data() const noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p>A pointer to the first byte of <code>value_</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="buffers_non_member_functions">Non-member functions</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class charT, class traits, order Order, class T,
  std::size_t n_bits, align Align&gt;
std::basic_ostream&lt;charT, traits&gt;&amp; operator&lt;&lt;(std::basic_ostream&lt;charT, traits&gt;&amp; os,
  const endian_buffer&lt;Order, T, n_bits, Align&gt;&amp; x);</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>os &lt;&lt; x.value()</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class charT, class traits, order Order, class T,
  std::size_t n_bits, align A&gt;
std::basic_istream&lt;charT, traits&gt;&amp; operator&gt;&gt;(std::basic_istream&lt;charT, traits&gt;&amp; is,
  endian_buffer&lt;Order, T, n_bits, Align&gt;&amp; x);</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p>As if:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>T i;
if (is &gt;&gt; i)
  x = i;</code></pre>
</div>
</div>
</dd>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>is</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="buffers_faq">FAQ</h3>
<div class="paragraph">
<p>See the <a href="#overview_faq">Overview FAQ</a> for a library-wide FAQ.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Why not just use Boost.Serialization?</dt>
<dd>
<p>Serialization involves a conversion for every object involved in I/O. Endian
integers require no conversion or copying. They are already in the desired
format for binary I/O. Thus they can be read or written in bulk.</p>
</dd>
<dt class="hdlist1">Are endian types PODs?</dt>
<dd>
<p>Yes for C&#43;&#43;11. No for C&#43;&#43;03, although several
<a href="#buffers_compilation">macros</a> are available to force PODness in all cases.</p>
</dd>
<dt class="hdlist1">What are the implications of endian integer types not being PODs with C&#43;&#43;03 compilers?</dt>
<dd>
<p>They can&#8217;t be used in unions. Also, compilers aren&#8217;t required to align or lay
out storage in portable ways, although this potential problem hasn&#8217;t prevented
use of Boost.Endian with real compilers.</p>
</dd>
<dt class="hdlist1">What good is native endianness?</dt>
<dd>
<p>It  provides alignment and size guarantees not available from the built-in
types. It eases generic  programming.</p>
</dd>
<dt class="hdlist1">Why bother with the aligned endian types?</dt>
<dd>
<p>Aligned integer operations may be faster (as much as 10 to 20 times faster) if
the endianness and alignment of  the type matches the endianness and alignment
requirements of the machine. The code, however, is likely to be somewhat less
portable than with the unaligned types.</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="buffers_design_considerations_for_boost_endian_buffers">Design considerations for Boost.Endian buffers</h3>
<div class="ulist">
<ul>
<li>
<p>Must be suitable for I/O - in other words, must be memcpyable.</p>
</li>
<li>
<p>Must provide exactly the size and internal byte ordering specified.</p>
</li>
<li>
<p>Must work correctly when the internal integer representation has more bits
that the sum of the bits in the external byte representation. Sign extension
must work correctly when the internal integer representation type has more
bits than the sum of the bits in the external bytes. For example, using
a 64-bit integer internally to represent 40-bit (5 byte) numbers must work for
both positive and negative values.</p>
</li>
<li>
<p>Must work correctly (including using the same defined external
representation) regardless of whether a compiler treats char as signed or
unsigned.</p>
</li>
<li>
<p>Unaligned types must not cause compilers to insert padding bytes.</p>
</li>
<li>
<p>The implementation should supply optimizations with great care. Experience
has shown that optimizations of endian integers often become pessimizations
when changing  machines or compilers. Pessimizations can also happen when
changing compiler switches, compiler versions, or CPU models of the same
architecture.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="buffers_c11">C&#43;&#43;11</h3>
<div class="paragraph">
<p>The availability of the C&#43;&#43;11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
Functions</a> feature is detected automatically, and will be used if present to
ensure that objects of <code>class endian_buffer</code> are trivial, and thus
PODs.</p>
</div>
</div>
<div class="sect2">
<h3 id="buffers_compilation">Compilation</h3>
<div class="paragraph">
<p>Boost.Endian is implemented entirely within headers, with no need to link to
any Boost object libraries.</p>
</div>
<div class="paragraph">
<p>Several macros allow user control over features:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>BOOST_ENDIAN_NO_CTORS</code> causes <code>class endian_buffer</code> to have no
constructors. The intended use is for compiling user code that must be
portable between compilers regardless of C&#43;&#43;11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
Functions</a> support. Use of constructors will always fail,</p>
</li>
<li>
<p><code>BOOST_ENDIAN_FORCE_PODNESS</code> causes <code>BOOST_ENDIAN_NO_CTORS</code> to be defined if
the compiler does not support C&#43;&#43;11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
Functions</a>. This is ensures that objects of <code>class endian_buffer</code> are PODs, and
so can be used in C&#43;&#43;03 unions. In C&#43;&#43;11, <code>class endian_buffer</code> objects are
PODs, even though they have constructors, so can always be used in unions.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="arithmetic">Endian Arithmetic Types</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="arithmetic_introduction">Introduction</h3>
<div class="paragraph">
<p>Header <code>boost/endian/arithmetic.hpp</code> provides integer binary types with
control over byte order, value type, size, and alignment. Typedefs provide
easy-to-use names for common configurations.</p>
</div>
<div class="paragraph">
<p>These types provide portable byte-holders for integer data, independent of
particular computer architectures. Use cases almost always involve I/O, either
via files or network connections. Although data portability is the primary
motivation, these integer byte-holders may also be used to reduce memory use,
file size, or network activity since they provide binary integer sizes not
otherwise available.</p>
</div>
<div class="paragraph">
<p>Such integer byte-holder types are traditionally called <strong>endian</strong> types. See the
<a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> for a full exploration of
<strong>endianness</strong>, including definitions of <strong>big endian</strong> and <strong>little endian</strong>.</p>
</div>
<div class="paragraph">
<p>Boost endian integers provide the same full set of C&#43;&#43; assignment, arithmetic,
and relational operators as C&#43;&#43; standard integral types, with the standard
semantics.</p>
</div>
<div class="paragraph">
<p>Unary arithmetic operators are <code>+</code>, <code>-</code>,  <code>~</code>, <code>!</code>, plus both prefix and postfix
<code>--</code> and <code>++</code>. Binary arithmetic operators are <code>+</code>, <code>+=</code>, <code>-</code>, <code>-=</code>, <code>*</code>,
<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
<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>
</div>
<div class="paragraph">
<p>Implicit conversion to the underlying value type is provided. An implicit
constructor converting from the underlying value type is provided.</p>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_example">Example</h3>
<div class="paragraph">
<p>The <code>endian_example.cpp</code> program writes a binary file containing four-byte,
big-endian and little-endian integers:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>#include &lt;iostream&gt;
#include &lt;cstdio&gt;
#include &lt;boost/endian/arithmetic.hpp&gt;
#include &lt;boost/static_assert.hpp&gt;

using namespace boost::endian;

namespace
{
  //  This is an extract from a very widely used GIS file format.
  //  Why the designer decided to mix big and little endians in
  //  the same file is not known. But this is a real-world format
  //  and users wishing to write low level code manipulating these
  //  files have to deal with the mixed endianness.

  struct header
  {
    big_int32_t     file_code;
    big_int32_t     file_length;
    little_int32_t  version;
    little_int32_t  shape_type;
  };

  const char* filename = "test.dat";
}

int main(int, char* [])
{
  header h;

  BOOST_STATIC_ASSERT(sizeof(h) == 16U);  // reality check

  h.file_code   = 0x01020304;
  h.file_length = sizeof(header);
  h.version     = 1;
  h.shape_type  = 0x01020304;

  //  Low-level I/O such as POSIX read/write or &lt;cstdio&gt;
  //  fread/fwrite is sometimes used for binary file operations
  //  when ultimate efficiency is important. Such I/O is often
  //  performed in some C++ wrapper class, but to drive home the
  //  point that endian integers are often used in fairly
  //  low-level code that does bulk I/O operations, &lt;cstdio&gt;
  //  fopen/fwrite is used for I/O in this example.

  std::FILE* fi = std::fopen(filename, "wb");  // MUST BE BINARY

  if (!fi)
  {
    std::cout &lt;&lt; "could not open " &lt;&lt; filename &lt;&lt; '\n';
    return 1;
  }

  if (std::fwrite(&amp;h, sizeof(header), 1, fi) != 1)
  {
    std::cout &lt;&lt; "write failure for " &lt;&lt; filename &lt;&lt; '\n';
    return 1;
  }

  std::fclose(fi);

  std::cout &lt;&lt; "created file " &lt;&lt; filename &lt;&lt; '\n';

  return 0;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>After compiling and executing <code>endian_example.cpp</code>, a hex dump of <code>test.dat</code>
shows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>01020304 00000010 01000000 04030201</code></pre>
</div>
</div>
<div class="paragraph">
<p>Notice that the first two 32-bit integers are big endian while the second two
are little endian, even though the machine this was compiled and run on was
little endian.</p>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_limitations">Limitations</h3>
<div class="paragraph">
<p>Requires <code>&lt;climits&gt;</code>, <code>CHAR_BIT == 8</code>. If <code>CHAR_BIT</code> is some other value,
compilation will result in an <code>#error</code>. This restriction is in place because the
design, implementation, testing, and documentation has only considered issues
related to 8-bit bytes, and there have been no real-world use cases presented
for other sizes.</p>
</div>
<div class="paragraph">
<p>In C&#43;&#43;03, <code>endian_arithmetic</code> does not meet the requirements for POD types
because it has constructors, private data members, and a base class. This means
that common use cases are relying on unspecified behavior in that the C&#43;&#43;
Standard does not guarantee memory layout for non-POD types. This has not been a
problem in practice since all known C&#43;&#43; compilers  lay out memory as if
<code>endian</code> were a POD type. In C&#43;&#43;11, it is possible to specify the default
constructor as trivial, and private data members and base classes  no longer
disqualify a type from being a POD type. Thus under C&#43;&#43;11, <code>endian_arithmetic</code>
will no longer be relying on unspecified behavior.</p>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_feature_set">Feature set</h3>
<div class="ulist">
<ul>
<li>
<p>Big endian| little endian | native endian byte ordering.</p>
</li>
<li>
<p>Signed | unsigned</p>
</li>
<li>
<p>Unaligned | aligned</p>
</li>
<li>
<p>1-8 byte (unaligned) | 1, 2, 4, 8 byte (aligned)</p>
</li>
<li>
<p>Choice of  value type</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_enums_and_typedefs">Enums and typedefs</h3>
<div class="paragraph">
<p>Two scoped enums are provided:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>enum class order { big, little, native };

enum class align { no, yes };</code></pre>
</div>
</div>
<div class="paragraph">
<p>One class template is provided:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;order Order, typename T, std::size_t n_bits,
  align Align = align::no&gt;
class endian_arithmetic;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Typedefs, such as <code>big_int32_t</code>, provide convenient naming conventions for
common use cases:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 20%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Alignment</th>
<th class="tableblock halign-left valign-top">Endianness</th>
<th class="tableblock halign-left valign-top">Sign</th>
<th class="tableblock halign-left valign-top">Sizes in bits (n)</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_intN_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_uintN_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_intN_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_uintN_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>native_intN_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">native</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>native_uintN_t</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">no</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">native</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,24,32,40,48,56,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_intN_at</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>big_uintN_at</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">big</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_intN_at</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">signed</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>little_uintN_at</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">yes</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">little</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">unsigned</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">8,16,32,64</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The unaligned types do not cause compilers to insert padding bytes in classes
and structs. This is an important characteristic that can be exploited to
minimize wasted space in memory, files, and network transmissions.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<div class="title">Caution</div>
</td>
<td class="content">
Code that uses aligned types is possibly non-portable because
alignment requirements vary between hardware architectures and because
alignment may be affected by compiler switches or pragmas. For example,
alignment of an 64-bit integer may be to a 32-bit boundary on a 32-bit machine.
Furthermore, aligned types are only available on architectures with 8, 16, 32,
and 64-bit integer types.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<div class="title">Tip</div>
</td>
<td class="content">
Prefer unaligned arithmetic types.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<div class="title">Tip</div>
</td>
<td class="content">
Protect yourself against alignment ills. For example:
</td>
</tr>
</table>
</div>
<div class="dlist none">
<dl>
<dt></dt>
<dd>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>static_assert(sizeof(containing_struct) == 12, "sizeof(containing_struct) is wrong");</code></pre>
</div>
</div>
</dd>
</dl>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
One-byte arithmetic types have identical layout on all platforms, so they
never actually reverse endianness. They are provided to enable generic code,
and to improve code readability and searchability.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_class_template_endian_arithmetic">Class template <code>endian_arithmetic</code></h3>
<div class="paragraph">
<p>An <code>endian_integer</code> is an integer byte-holder with user-specified endianness,
value type, size, and alignment. The usual operations on arithmetic types are
supplied.</p>
</div>
<div class="sect3">
<h4 id="arithmetic_synopsis">Synopsis</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>#include &lt;boost/endian/buffers.hpp&gt;

namespace boost
{
  namespace endian
  {
    //  C++11 features emulated if not available

    enum class align { no, yes };

    template &lt;order Order, class T, std::size_t n_bits,
      align Align = align::no&gt;
    class endian_arithmetic
      : public endian_buffer&lt;Order, T, n_bits, Align&gt;
    {
    public:

      typedef T value_type;

      // if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++11 PODs are not
      // available then these two constructors will not be present
      endian_arithmetic() noexcept = default;
      endian_arithmetic(T v) noexcept;

      endian_arithmetic&amp; operator=(T v) noexcept;
      operator value_type() const noexcept;
      value_type value() const noexcept; // for exposition; see endian_buffer
      unsigned char* data() noexcept; // for exposition; see endian_buffer
      unsigned char const* data() const noexcept; // for exposition; see endian_buffer

      // arithmetic operations
      //   note that additional operations are provided by the value_type
      value_type operator+() const noexcept;
      endian_arithmetic&amp; operator+=(value_type y) noexcept;
      endian_arithmetic&amp; operator-=(value_type y) noexcept;
      endian_arithmetic&amp; operator*=(value_type y) noexcept;
      endian_arithmetic&amp; operator/=(value_type y) noexcept;
      endian_arithmetic&amp; operator%=(value_type y) noexcept;
      endian_arithmetic&amp; operator&amp;=(value_type y) noexcept;
      endian_arithmetic&amp; operator|=(value_type y) noexcept;
      endian_arithmetic&amp; operator^=(value_type y) noexcept;
      endian_arithmetic&amp; operator&lt;&lt;=(value_type y) noexcept;
      endian_arithmetic&amp; operator&gt;&gt;=(value_type y) noexcept;
      endian_arithmetic&amp; operator++() noexcept;
      endian_arithmetic&amp; operator--() noexcept;
      endian_arithmetic operator++(int) noexcept;
      endian_arithmetic operator--(int) noexcept;

      // Stream inserter
      template &lt;class charT, class traits&gt;
      friend std::basic_ostream&lt;charT, traits&gt;&amp;
        operator&lt;&lt;(std::basic_ostream&lt;charT, traits&gt;&amp; os, const endian_arithmetic&amp; x);

      // Stream extractor
      template &lt;class charT, class traits&gt;
      friend std::basic_istream&lt;charT, traits&gt;&amp;
        operator&gt;&gt;(std::basic_istream&lt;charT, traits&gt;&amp; is, endian_arithmetic&amp; x);
    };

    // typedefs

    // unaligned big endian signed integer types
    typedef endian_arithmetic&lt;order::big, int_least8_t, 8&gt;        big_int8_t;
    typedef endian_arithmetic&lt;order::big, int_least16_t, 16&gt;      big_int16_t;
    typedef endian_arithmetic&lt;order::big, int_least32_t, 24&gt;      big_int24_t;
    typedef endian_arithmetic&lt;order::big, int_least32_t, 32&gt;      big_int32_t;
    typedef endian_arithmetic&lt;order::big, int_least64_t, 40&gt;      big_int40_t;
    typedef endian_arithmetic&lt;order::big, int_least64_t, 48&gt;      big_int48_t;
    typedef endian_arithmetic&lt;order::big, int_least64_t, 56&gt;      big_int56_t;
    typedef endian_arithmetic&lt;order::big, int_least64_t, 64&gt;      big_int64_t;

    // unaligned big endian unsigned integer types
    typedef endian_arithmetic&lt;order::big, uint_least8_t, 8&gt;       big_uint8_t;
    typedef endian_arithmetic&lt;order::big, uint_least16_t, 16&gt;     big_uint16_t;
    typedef endian_arithmetic&lt;order::big, uint_least32_t, 24&gt;     big_uint24_t;
    typedef endian_arithmetic&lt;order::big, uint_least32_t, 32&gt;     big_uint32_t;
    typedef endian_arithmetic&lt;order::big, uint_least64_t, 40&gt;     big_uint40_t;
    typedef endian_arithmetic&lt;order::big, uint_least64_t, 48&gt;     big_uint48_t;
    typedef endian_arithmetic&lt;order::big, uint_least64_t, 56&gt;     big_uint56_t;
    typedef endian_arithmetic&lt;order::big, uint_least64_t, 64&gt;     big_uint64_t;

    // unaligned big endian floating point types
    typedef endian_arithmetic&lt;order::big, float, 32&gt;              big_float32_t;
    typedef endian_arithmetic&lt;order::big, double, 64&gt;             big_float64_t;

    // unaligned little endian signed integer types
    typedef endian_arithmetic&lt;order::little, int_least8_t, 8&gt;     little_int8_t;
    typedef endian_arithmetic&lt;order::little, int_least16_t, 16&gt;   little_int16_t;
    typedef endian_arithmetic&lt;order::little, int_least32_t, 24&gt;   little_int24_t;
    typedef endian_arithmetic&lt;order::little, int_least32_t, 32&gt;   little_int32_t;
    typedef endian_arithmetic&lt;order::little, int_least64_t, 40&gt;   little_int40_t;
    typedef endian_arithmetic&lt;order::little, int_least64_t, 48&gt;   little_int48_t;
    typedef endian_arithmetic&lt;order::little, int_least64_t, 56&gt;   little_int56_t;
    typedef endian_arithmetic&lt;order::little, int_least64_t, 64&gt;   little_int64_t;

    // unaligned little endian unsigned integer types
    typedef endian_arithmetic&lt;order::little, uint_least8_t, 8&gt;    little_uint8_t;
    typedef endian_arithmetic&lt;order::little, uint_least16_t, 16&gt;  little_uint16_t;
    typedef endian_arithmetic&lt;order::little, uint_least32_t, 24&gt;  little_uint24_t;
    typedef endian_arithmetic&lt;order::little, uint_least32_t, 32&gt;  little_uint32_t;
    typedef endian_arithmetic&lt;order::little, uint_least64_t, 40&gt;  little_uint40_t;
    typedef endian_arithmetic&lt;order::little, uint_least64_t, 48&gt;  little_uint48_t;
    typedef endian_arithmetic&lt;order::little, uint_least64_t, 56&gt;  little_uint56_t;
    typedef endian_arithmetic&lt;order::little, uint_least64_t, 64&gt;  little_uint64_t;

    // unaligned little endian floating point types
    typedef endian_arithmetic&lt;order::little, float, 32&gt;           little_float32_t;
    typedef endian_arithmetic&lt;order::little, double, 64&gt;          little_float64_t;

    // unaligned native endian signed integer types
    typedef implementation-defined_int8_t   native_int8_t;
    typedef implementation-defined_int16_t  native_int16_t;
    typedef implementation-defined_int24_t  native_int24_t;
    typedef implementation-defined_int32_t  native_int32_t;
    typedef implementation-defined_int40_t  native_int40_t;
    typedef implementation-defined_int48_t  native_int48_t;
    typedef implementation-defined_int56_t  native_int56_t;
    typedef implementation-defined_int64_t  native_int64_t;

    // unaligned native endian unsigned integer types
    typedef implementation-defined_uint8_t   native_uint8_t;
    typedef implementation-defined_uint16_t  native_uint16_t;
    typedef implementation-defined_uint24_t  native_uint24_t;
    typedef implementation-defined_uint32_t  native_uint32_t;
    typedef implementation-defined_uint40_t  native_uint40_t;
    typedef implementation-defined_uint48_t  native_uint48_t;
    typedef implementation-defined_uint56_t  native_uint56_t;
    typedef implementation-defined_uint64_t  native_uint64_t;

    // unaligned native endian floating point types
    typedef implementation-defined_float32_t  native_float32_t;
    typedef implementation-defined_float64_t  native_float64_t;

    // aligned big endian signed integer types
    typedef endian_arithmetic&lt;order::big, int8_t, 8, align::yes&gt;       big_int8_at;
    typedef endian_arithmetic&lt;order::big, int16_t, 16, align::yes&gt;     big_int16_at;
    typedef endian_arithmetic&lt;order::big, int32_t, 32, align::yes&gt;     big_int32_at;
    typedef endian_arithmetic&lt;order::big, int64_t, 64, align::yes&gt;     big_int64_at;

    // aligned big endian unsigned integer types
    typedef endian_arithmetic&lt;order::big, uint8_t, 8, align::yes&gt;      big_uint8_at;
    typedef endian_arithmetic&lt;order::big, uint16_t, 16, align::yes&gt;    big_uint16_at;
    typedef endian_arithmetic&lt;order::big, uint32_t, 32, align::yes&gt;    big_uint32_at;
    typedef endian_arithmetic&lt;order::big, uint64_t, 64, align::yes&gt;    big_uint64_at;

    // aligned big endian floating point types
    typedef endian_arithmetic&lt;order::big, float, 32, align::yes&gt;       big_float32_at;
    typedef endian_arithmetic&lt;order::big, double, 64, align::yes&gt;      big_float64_at;

    // aligned little endian signed integer types
    typedef endian_arithmetic&lt;order::little, int8_t, 8, align::yes&gt;    little_int8_at;
    typedef endian_arithmetic&lt;order::little, int16_t, 16, align::yes&gt;  little_int16_at;
    typedef endian_arithmetic&lt;order::little, int32_t, 32, align::yes&gt;  little_int32_at;
    typedef endian_arithmetic&lt;order::little, int64_t, 64, align::yes&gt;  little_int64_at;

    // aligned little endian unsigned integer types
    typedef endian_arithmetic&lt;order::little, uint8_t, 8, align::yes&gt;   little_uint8_at;
    typedef endian_arithmetic&lt;order::little, uint16_t, 16, align::yes&gt; little_uint16_at;
    typedef endian_arithmetic&lt;order::little, uint32_t, 32, align::yes&gt; little_uint32_at;
    typedef endian_arithmetic&lt;order::little, uint64_t, 64, align::yes&gt; little_uint64_at;

    // aligned little endian floating point types
    typedef endian_arithmetic&lt;order::little, float, 32, align::yes&gt;    little_float32_at;
    typedef endian_arithmetic&lt;order::little, double, 64, align::yes&gt;   little_float64_at;

    // aligned native endian typedefs are not provided because
    // &lt;cstdint&gt; types are superior for that use case

  } // namespace endian
} // namespace boost</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>implementation-defined</code> text above is either <code>big</code> or <code>little</code> according
to the endianness of the platform.</p>
</div>
<div class="paragraph">
<p>The only supported value of <code>CHAR_BIT</code> is 8.</p>
</div>
<div class="paragraph">
<p>The valid values of <code>Nbits</code> are as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>When <code>sizeof(T)</code> is 1, <code>Nbits</code> shall be 8;</p>
</li>
<li>
<p>When <code>sizeof(T)</code> is 2, <code>Nbits</code> shall be 16;</p>
</li>
<li>
<p>When <code>sizeof(T)</code> is 4, <code>Nbits</code> shall be 24 or 32;</p>
</li>
<li>
<p>When <code>sizeof(T)</code> is 8, <code>Nbits</code> shall be 40, 48, 56, or 64.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Other values of <code>sizeof(T)</code> are not supported.</p>
</div>
<div class="paragraph">
<p>When <code>Nbits</code> is equal to <code>sizeof(T)*8</code>, <code>T</code> must be a standard arithmetic type.</p>
</div>
<div class="paragraph">
<p>When <code>Nbits</code> is less than <code>sizeof(T)*8</code>, <code>T</code> must be a standard integral type
(C&#43;&#43;std, [basic.fundamental]) that is not <code>bool</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="arithmetic_members">Members</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>endian_arithmetic() noexcept = default;  // C++03: endian(){}</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p>Constructs an uninitialized object.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>endian_arithmetic(T v) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p>See <code>endian_buffer::endian_buffer(T)</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>endian_arithmetic&amp; operator=(T v) noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p>See <code>endian_buffer::operator=(T)</code>.</p>
</dd>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>*this</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>operator T() const noexcept;</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>value()</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="arithmetic_other_operators">Other operators</h4>
<div class="paragraph">
<p>Other operators on endian objects are forwarded to the equivalent operator on
<code>value_type</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="arithmetic_stream_inserter">Stream inserter</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class charT, class traits&gt;
friend std::basic_ostream&lt;charT, traits&gt;&amp;
  operator&lt;&lt;(std::basic_ostream&lt;charT, traits&gt;&amp; os, const endian_arithmetic&amp; x);</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>os &lt;&lt; +x</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="arithmetic_stream_extractor">Stream extractor</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>template &lt;class charT, class traits&gt;
friend std::basic_istream&lt;charT, traits&gt;&amp;
  operator&gt;&gt;(std::basic_istream&lt;charT, traits&gt;&amp; is, endian_arithmetic&amp; x);</code></pre>
</div>
</div>
<div class="ulist none">
<ul class="none">
<li>
<p></p>
<div class="dlist">
<dl>
<dt class="hdlist1">Effects</dt>
<dd>
<p>As if:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>T i;
if (is &gt;&gt; i)
  x = i;</code></pre>
</div>
</div>
</dd>
<dt class="hdlist1">Returns</dt>
<dd>
<p><code>is</code>.</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_faq">FAQ</h3>
<div class="paragraph">
<p>See the <a href="#overview_faq">Overview FAQ</a> for a library-wide FAQ.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Why not just use Boost.Serialization?</dt>
<dd>
<p>Serialization involves a conversion for every object involved in I/O. Endian
integers require no conversion or copying. They are already in the desired
format for binary I/O. Thus they can be read or written in bulk.</p>
</dd>
<dt class="hdlist1">Are endian types PODs?</dt>
<dd>
<p>Yes for C&#43;&#43;11. No for C&#43;&#43;03, although several
<a href="#arithmetic_compilation">macros</a> are available to force PODness in all cases.</p>
</dd>
<dt class="hdlist1">What are the implications of endian integer types not being PODs with C&#43;&#43;03 compilers?</dt>
<dd>
<p>They can&#8217;t be used in unions. Also, compilers aren&#8217;t required to align or lay
out storage in portable ways, although this potential problem hasn&#8217;t prevented
use of Boost.Endian with real compilers.</p>
</dd>
<dt class="hdlist1">What good is native endianness?</dt>
<dd>
<p>It  provides alignment and size guarantees not available from the built-in
types. It eases generic programming.</p>
</dd>
<dt class="hdlist1">Why bother with the aligned endian types?</dt>
<dd>
<p>Aligned integer operations may be faster (as much as 10 to 20 times faster)
if the endianness and alignment of the type matches the endianness and
alignment requirements of the machine. The code, however, will be somewhat less
portable than with the unaligned types.</p>
</dd>
<dt class="hdlist1">Why provide the arithmetic operations?</dt>
<dd>
<p>Providing a full set of operations reduces program clutter and makes code
both easier to write and to read. Consider incrementing a variable in a record.
It is very convenient to write:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>++record.foo;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Rather than:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>int temp(record.foo);
++temp;
record.foo = temp;</code></pre>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_design_considerations_for_boost_endian_types">Design considerations for Boost.Endian types</h3>
<div class="ulist">
<ul>
<li>
<p>Must be suitable for I/O - in other words, must be memcpyable.</p>
</li>
<li>
<p>Must provide exactly the size and internal byte ordering specified.</p>
</li>
<li>
<p>Must work correctly when the internal integer representation has more bits
that the sum of the bits in the external byte representation. Sign extension
must work correctly when the internal integer representation type has more
bits than the sum of the bits in the external bytes. For example, using
a 64-bit integer internally to represent 40-bit (5 byte) numbers must work for
both positive and negative values.</p>
</li>
<li>
<p>Must work correctly (including using the same defined external
representation) regardless of whether a compiler treats char as signed or
unsigned.</p>
</li>
<li>
<p>Unaligned types must not cause compilers to insert padding bytes.</p>
</li>
<li>
<p>The implementation should supply optimizations with great care. Experience
has shown that optimizations of endian integers often become pessimizations
when changing machines or compilers. Pessimizations can also happen when
changing compiler switches, compiler versions, or CPU models of the same
architecture.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_experience">Experience</h3>
<div class="paragraph">
<p>Classes with similar functionality have been independently developed by
several Boost programmers and used very successful in high-value, high-use
applications for many years. These independently developed endian libraries
often evolved from C libraries that were also widely used. Endian types have
proven widely useful across a wide range of computer architectures and
applications.</p>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_motivating_use_cases">Motivating use cases</h3>
<div class="paragraph">
<p>Neil Mayhew writes: "I can also provide a meaningful use-case for this
library: reading TrueType font files from disk and processing the contents. The
data format has fixed endianness (big) and has unaligned values in various
places. Using Boost.Endian simplifies and cleans the code wonderfully."</p>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_c11">C&#43;&#43;11</h3>
<div class="paragraph">
<p>The availability of the C&#43;&#43;11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
Functions</a> feature is detected automatically, and will be used if present to
ensure that objects of <code>class endian_arithmetic</code> are trivial, and thus PODs.</p>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_compilation">Compilation</h3>
<div class="paragraph">
<p>Boost.Endian is implemented entirely within headers, with no need to link to any
Boost object libraries.</p>
</div>
<div class="paragraph">
<p>Several macros allow user control over features:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>BOOST_ENDIAN_NO_CTORS causes <code>class endian_arithmetic</code> to have no
constructors. The intended use is for compiling user code that must be portable
between compilers regardless of C&#43;&#43;11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
Functions</a> support. Use of constructors will always fail,</p>
</li>
<li>
<p>BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if
the compiler does not support C&#43;&#43;11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">Defaulted
Functions</a>. This is ensures that objects of <code>class endian_arithmetic</code> are PODs,
and so can be used in C&#43;&#43;03 unions. In C&#43;&#43;11, <code>class endian_arithmetic</code>
objects are PODs, even though they have constructors, so can always be used in
unions.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="arithmetic_acknowledgements">Acknowledgements</h3>
<div class="paragraph">
<p>Original design developed by Darin Adler based on classes developed by Mark
Borgerding. Four original class templates combined into a single
<code>endian_arithmetic</code> class template by Beman Dawes, who put the library together,
provided documentation,  added the typedefs, and also added the
<code>unrolled_byte_loops</code> sign partial specialization to correctly extend the sign
when cover integer size differs from endian representation size.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="choosing">Choosing Approach</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="choosing_introduction">Introduction</h3>
<div class="paragraph">
<p>Deciding which is the best endianness approach (conversion functions, buffer
types, or arithmetic types) for a particular application involves complex
engineering trade-offs. It is hard to assess those trade-offs without some
understanding of the different interfaces, so you might want to read the
<a href="#conversion">conversion functions</a>, <a href="#buffers">buffer types</a>, and
<a href="#arithmetic">arithmetic types</a> pages before diving into this page.</p>
</div>
</div>
<div class="sect2">
<h3 id="choosing_choosing_between_conversion_functions_buffer_types_and_arithmetic_types">Choosing between conversion functions, buffer types, and arithmetic types</h3>
<div class="paragraph">
<p>The best approach to endianness for a particular application depends on the
interaction between the application&#8217;s needs and the characteristics of each of
the three  approaches.</p>
</div>
<div class="paragraph">
<p><strong>Recommendation:</strong> If you are new to endianness, uncertain, or don&#8217;t want to
invest the time to study engineering trade-offs, use
<a href="#arithmetic">endian arithmetic types</a>. They are safe, easy to use, and easy to
maintain. Use the <em><a href="#choosing_anticipating_need">anticipating need</a></em> design
pattern locally around performance hot spots like lengthy loops, if needed.</p>
</div>
<div class="sect3">
<h4 id="choosing_background">Background</h4>
<div class="paragraph">
<p>A dealing with endianness usually implies a program portability or a data
portability requirement, and often both. That means real programs dealing with
endianness are usually complex, so the examples shown here would really be
written as multiple functions spread across multiple translation units. They
would involve interfaces that can not be altered as they are supplied by
third-parties or the standard library.</p>
</div>
</div>
<div class="sect3">
<h4 id="choosing_characteristics">Characteristics</h4>
<div class="paragraph">
<p>The characteristics that differentiate the three approaches to endianness are
the endianness invariants, conversion explicitness, arithmetic operations, sizes
available, and alignment requirements.</p>
</div>
<div class="sect4">
<h5 id="choosing_endianness_invariants">Endianness invariants</h5>
<div class="paragraph">
<p><strong>Endian conversion functions</strong> use objects of the ordinary C&#43;&#43; arithmetic types
like <code>int</code> or <code>unsigned short</code> to hold values. That breaks the implicit
invariant that the C&#43;&#43; language rules apply. The usual language rules only apply
if the endianness of the object is currently set to the native endianness for
the platform. That can make it very hard to reason about logic flow, and result
in difficult to find bugs.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>struct data_t  // big endian
{
  int32_t   v1;  // description ...
  int32_t   v2;  // description ...
  ... additional character data members (i.e. non-endian)
  int32_t   v3;  // description ...
};

data_t data;

read(data);
big_to_native_inplace(data.v1);
big_to_native_inplace(data.v2);

...

++v1;
third_party::func(data.v2);

...

native_to_big_inplace(data.v1);
native_to_big_inplace(data.v2);
write(data);</code></pre>
</div>
</div>
<div class="paragraph">
<p>The programmer didn&#8217;t bother to convert <code>data.v3</code> to native endianness because
that member isn&#8217;t used. A later maintainer needs to pass <code>data.v3</code> to the
third-party function, so adds <code>third_party::func(data.v3);</code> somewhere deep in
the code. This causes a silent failure because the usual invariant that an
object of type <code>int32_t</code> holds a value as described by the C&#43;&#43; core language
does not apply.</p>
</div>
<div class="paragraph">
<p><strong>Endian buffer and arithmetic types</strong> hold values internally as arrays of
characters with an invariant that the endianness of the array never changes.
That makes these types easier to use and programs easier to maintain.</p>
</div>
<div class="paragraph">
<p>Here is the same example, using an endian arithmetic type:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>struct data_t
{
  big_int32_t   v1;  // description ...
  big_int32_t   v2;  // description ...
  ... additional character data members (i.e. non-endian)
  big_int32_t   v3;  // description ...
};

data_t data;

read(data);

...

++v1;
third_party::func(data.v2);

...

write(data);</code></pre>
</div>
</div>
<div class="paragraph">
<p>A later maintainer can add <code>third_party::func(data.v3)</code> and it will just-work.</p>
</div>
</div>
<div class="sect4">
<h5 id="choosing_conversion_explicitness">Conversion explicitness</h5>
<div class="paragraph">
<p><strong>Endian conversion functions</strong> and <strong>buffer types</strong> never perform implicit
conversions. This gives users explicit control of when conversion occurs, and
may help avoid unnecessary conversions.</p>
</div>
<div class="paragraph">
<p><strong>Endian arithmetic types</strong> perform conversion implicitly. That makes these types
very easy to use, but can result in unnecessary conversions. Failure to hoist
conversions out of inner loops can bring a performance penalty.</p>
</div>
</div>
<div class="sect4">
<h5 id="choosing_arithmetic_operations">Arithmetic operations</h5>
<div class="paragraph">
<p><strong>Endian conversion functions</strong> do not supply arithmetic operations, but this is
not a concern since this approach uses ordinary C&#43;&#43; arithmetic types to hold
values.</p>
</div>
<div class="paragraph">
<p><strong>Endian buffer types</strong> do not supply arithmetic operations. Although this
approach avoids unnecessary conversions, it can result in the introduction of
additional variables and confuse maintenance programmers.</p>
</div>
<div class="paragraph">
<p><strong>Endian arithmetic types</strong> do supply arithmetic operations. They are very easy to
use if lots of arithmetic is involved.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="choosing_sizes">Sizes</h4>
<div class="paragraph">
<p><strong>Endianness conversion functions</strong> only support 1, 2, 4, and 8 byte integers.
That&#8217;s sufficient for many applications.</p>
</div>
<div class="paragraph">
<p><strong>Endian buffer and arithmetic types</strong> support 1, 2, 3, 4, 5, 6, 7, and 8 byte
integers. For an application where memory use or I/O speed is the limiting
factor, using sizes tailored to application needs can be useful.</p>
</div>
<div class="sect4">
<h5 id="choosing_alignments">Alignments</h5>
<div class="paragraph">
<p><strong>Endianness conversion functions</strong> only support aligned integer and
floating-point types. That&#8217;s sufficient for most applications.</p>
</div>
<div class="paragraph">
<p><strong>Endian buffer and arithmetic types</strong> support both aligned and unaligned
integer and floating-point types. Unaligned types are rarely needed, but when
needed they are often very useful and workarounds are painful. For example:</p>
</div>
<div class="paragraph">
<p>Non-portable code like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>struct S {
  uint16_t a; // big endian
  uint32_t b; // big endian
} __attribute__ ((packed));</code></pre>
</div>
</div>
<div class="paragraph">
<p>Can be replaced with portable code like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>struct S {
  big_uint16_ut a;
  big_uint32_ut b;
};</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="choosing_design_patterns">Design patterns</h4>
<div class="paragraph">
<p>Applications often traffic in endian data as records or packets containing
multiple endian data elements. For simplicity, we will just call them records.</p>
</div>
<div class="paragraph">
<p>If desired endianness differs from native endianness, a conversion has to be
performed. When should that conversion occur? Three design patterns have
evolved.</p>
</div>
<div class="sect4">
<h5 id="choosing_convert_only_as_needed_i_e_lazy">Convert only as needed (i.e. lazy)</h5>
<div class="paragraph">
<p>This pattern defers conversion to the point in the code where the data
element is actually used.</p>
</div>
<div class="paragraph">
<p>This pattern is appropriate when which endian element is actually used varies
greatly according to record content or other circumstances</p>
</div>
</div>
<div class="sect4">
<h5 id="choosing_anticipating_need">Convert in anticipation of need</h5>
<div class="paragraph">
<p>This pattern performs conversion to native endianness in anticipation of use,
such as immediately after reading records. If needed, conversion to the output
endianness is performed after all possible needs have passed, such as just
before writing records.</p>
</div>
<div class="paragraph">
<p>One implementation of this pattern is to create a proxy record with endianness
converted to native in a read function, and expose only that proxy to the rest
of the implementation. If a write function, if needed, handles the conversion
from native to the desired output endianness.</p>
</div>
<div class="paragraph">
<p>This pattern is appropriate when all endian elements in a record are typically
used regardless of record content or other circumstances.</p>
</div>
</div>
<div class="sect4">
<h5 id="choosing_convert_only_as_needed_except_locally_in_anticipation_of_need">Convert only as needed, except locally in anticipation of need</h5>
<div class="paragraph">
<p>This pattern in general defers conversion but for specific local needs does
anticipatory conversion. Although particularly appropriate when coupled with the
endian buffer or arithmetic types, it also works well with the conversion
functions.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>struct data_t
{
  big_int32_t   v1;
  big_int32_t   v2;
  big_int32_t   v3;
};

data_t data;

read(data);

...
++v1;
...

int32_t v3_temp = data.v3;  // hoist conversion out of loop

for (int32_t i = 0; i &lt; <code>large-number</code>; ++i)
{
  ... <code>lengthy computation that accesses v3_temp</code> ...
}
data.v3 = v3_temp;

write(data);</code></pre>
</div>
</div>
<div class="paragraph">
<p>In general the above pseudo-code leaves conversion up to the endian arithmetic
type <code>big_int32_t</code>. But to avoid conversion inside the loop, a temporary is
created before the loop is entered, and then used to set the new value of
<code>data.v3</code> after the loop is complete.</p>
</div>
<div class="paragraph">
<p>Question: Won&#8217;t the compiler&#8217;s optimizer hoist the conversion out of the loop
anyhow?</p>
</div>
<div class="paragraph">
<p>Answer: VC&#43;&#43; 2015 Preview, and probably others, does not, even for a toy test
program. Although the savings is small (two register <code>bswap</code> instructions), the
cost might be significant if the loop is repeated enough times. On the other
hand, the program may be so dominated by I/O time that even a lengthy loop will
be immaterial.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="choosing_use_case_examples">Use case examples</h4>
<div class="sect4">
<h5 id="choosing_porting_endian_unaware_codebase">Porting endian unaware codebase</h5>
<div class="paragraph">
<p>An existing codebase runs on  big endian systems. It does not currently deal
with endianness. The codebase needs to be modified so it can run on little
endian systems under various operating systems. To ease transition and protect
value of existing files, external data will continue to be maintained as big
endian.</p>
</div>
<div class="paragraph">
<p>The <a href="#arithmetic">endian arithmetic approach</a> is recommended to meet these
needs. A relatively small number of header files dealing with binary I/O layouts
need to change types. For example, <code>short</code> or <code>int16_t</code> would change to
<code>big_int16_t</code>. No changes are required for <code>.cpp</code> files.</p>
</div>
</div>
<div class="sect4">
<h5 id="choosing_porting_endian_aware_codebase">Porting endian aware codebase</h5>
<div class="paragraph">
<p>An existing codebase runs on little-endian Linux systems. It already deals with
endianness via
<a href="http://man7.org/linux/man-pages/man3/endian.3.html">Linux provided functions</a>.
Because of a business merger, the codebase has to be quickly modified for
Windows and possibly other operating systems, while still supporting Linux. The
codebase is reliable and the programmers are all well-aware of endian issues.</p>
</div>
<div class="paragraph">
<p>These factors all argue for an <a href="#conversion">endian conversion approach</a> that
just mechanically changes the calls to <code>htobe32</code>, etc. to
<code>boost::endian::native_to_big</code>, etc. and replaces <code>&lt;endian.h&gt;</code> with
<code>&lt;boost/endian/conversion.hpp&gt;</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="choosing_reliability_and_arithmetic_speed">Reliability and arithmetic-speed</h5>
<div class="paragraph">
<p>A new, complex, multi-threaded application is to be developed that must run
on little endian machines, but do big endian network I/O. The developers believe
computational speed for endian variable is critical but have seen numerous bugs
result from inability to reason about endian conversion state. They are also
worried that future maintenance changes could inadvertently introduce a lot of
slow conversions if full-blown endian arithmetic types are used.</p>
</div>
<div class="paragraph">
<p>The <a href="#buffers">endian buffers</a> approach is made-to-order for this use case.</p>
</div>
</div>
<div class="sect4">
<h5 id="choosing_reliability_and_ease_of_use">Reliability and ease-of-use</h5>
<div class="paragraph">
<p>A new, complex, multi-threaded application is to be developed that must run on
little endian machines, but do big endian network I/O. The developers believe
computational speed for endian variables is <strong>not critical</strong> but have seen
numerous bugs result from inability to reason about endian conversion state.
They are also concerned about ease-of-use both during development and long-term
maintenance.</p>
</div>
<div class="paragraph">
<p>Removing concern about conversion speed and adding concern about ease-of-use
tips the balance strongly in favor the
<a href="#arithmetic">endian arithmetic approach</a>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="appendix_mini_review_topics">Appendix A: Endian Mini-Review</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The results of the Boost.Endian formal review included a list of issues to be
resolved before a mini-review.</p>
</div>
<div class="paragraph">
<p>The issues are shown in <strong>bold</strong> below, with the resolution indicated.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Common use case scenarios should be developed.</dt>
<dd>
<p>Done. The documentation have been refactored. A page is now devoted to
<a href="#choosing">Choosing the Approach</a> to endianness. See
<a href="#choosing_use_cases">Use cases</a> for use case scenarios.</p>
</dd>
<dt class="hdlist1">Example programs should be developed for the common use case scenarios.</dt>
<dd>
<p>Done. See <a href="#choosing">Choosing the Approach</a>. Example code has been added
throughout.</p>
</dd>
<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>
<dd>
<p>Done. See <a href="#choosing">Choosing the Approach</a>.</p>
</dd>
<dt class="hdlist1">Conversion functions supplying results via return should be provided.</dt>
<dd>
<p>Done. See <a href="#conversion">Conversion Functions</a>.</p>
</dd>
<dt class="hdlist1">Platform specific performance enhancements such as use of compiler intrinsics or relaxed alignment requirements should be supported.</dt>
<dd>
<p>Done. Compiler (Clang, GCC, VisualC&#43;&#43;, etc.) intrinsics and built-in
functions are used in the implementation where appropriate, as requested. See
<a href="#overview_intrinsic">Built-in support for Intrinsics</a>. See
<a href="#overview_timings">Timings for Example 2</a> to gauge the impact of intrinsics.</p>
</dd>
<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>
<dd>
<p>Done. For the endian types, the implementation uses the endian conversion
functions, and thus the intrinsics, as requested.</p>
</dd>
<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>
<dd>
<p>Done. See <a href="#overview_timings">Timings for Example 2</a>. The <code>endian/test</code>
directory  also contains several additional benchmark and speed test programs.</p>
</dd>
<dt class="hdlist1">Float (32-bits) and double (64-bits) should be supported. IEEE 754 is the primary use case.</dt>
<dd>
<p>Done. The <a href="#buffers">endian buffer types</a>,
<a href="#arithmetic">endian arithmetic types</a> and
<a href="#conversion">endian conversion functions</a> now support 32-bit <code>(float)</code>
and 64-bit <code>(double)</code> floating point, as requested.</p>
</dd>
<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>
<dd>
<p>Done. See <a href="#conversion_customization">Customization points for user-defined
types (UDTs)</a>.</p>
</dd>
<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>
<dd>
<p>Done. The endian types have been decomposed into class template
<code><a href="#buffers">endian_buffer</a></code> and class template
<code><a href="#arithmetic">endian_arithmetic</a></code>. Class <code>endian_buffer</code> is a public base
class for <code>endian_arithmetic</code>, and can also be used by users as a stand-alone
class.</p>
</dd>
<dt class="hdlist1">Stream insertion and extraction of the endian integer/float types should be documented and included in the test coverage.</dt>
<dd>
<p>Done. See <a href="#buffers_stream_inserter">Stream inserter</a> and
<a href="#buffers_stream_extractor">Stream extractor</a>.</p>
</dd>
<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>
<dd>
<p>Not done yet. Will be handled as a separate min-review soon after the Endian
mini-review.</p>
</dd>
<dt class="hdlist1">Other requested changes.</dt>
<dd>
<p> In addition to the named-endianness conversion functions, functions that
perform compile-time (via template) and run-time (via function argument)
dispatch are now provided.
 <code>order*native</code> is now a synonym for <code>order*big</code> or <code>order*little</code> according
to the endianness of the platform. This reduces the number of template
specializations required.
 Headers have been reorganized to make them easier to read, with a synopsis
at the front and implementation following.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect1">
<h2 id="choosing_copyright_and_license">Appendix B: Copyright and License</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This documentation is</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Copyright 2011-2016 Beman Dawes</p>
</li>
<li>
<p>Copyright 2019 Peter Dimov</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>and is distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</p>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2019-12-10 00:18:50 UTC
</div>
</div>
<style>

*:not(pre)>code { background: none; color: #600000; }
:not(pre):not([class^=L])>code { background: none; color: #600000; }
table tr.even, table tr.alt, table tr:nth-of-type(even) { background: none; }

</style>
</body>
</html>