lloda
/
ra-ra


			
							1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929
							<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- ra:: (version 21, updated 2023 July 8)


(c) Daniel Llorens 2005-2023


Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.3 or

any later version published by the Free Software Foundation; with no

Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<title>ra:: — An array library for C++20</title>

<meta name="description" content="ra:: — An array library for C++20">
<meta name="keywords" content="ra:: — An array library for C++20">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="#Top" rel="start" title="Top">
<link href="#Indices" rel="index" title="Indices">
<link href="#Overview" rel="next" title="Overview">
<style type="text/css">

<!--

a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}

a.summary-letter-printindex {text-decoration: none}

div.display {margin-left: 3.2em}

div.example {margin-left: 3.2em}

pre.display-preformatted {font-family: inherit}

span:hover a.copiable-link {visibility: visible}

strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}

td.printindex-index-entry {vertical-align: top}

td.printindex-index-section {vertical-align: top}

th.entries-header-printindex {text-align:left}

th.sections-header-printindex {text-align:left}

ul.mark-bullet {list-style-type: disc}

-->

</style>

<script type='text/javascript'>

MathJax = {

  options: {

    skipHtmlTags: {'[-]': ['pre']},

    ignoreHtmlClass: 'tex2jax_ignore',

    processHtmlClass: 'tex2jax_process'

  },

};

</script><script type="text/javascript" id="MathJax-script" async

  src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js">

</script>
</head>

<body lang="en" class="tex2jax_ignore">


<div class="top-level-extent" id="Top">
<div class="nav-panel">
<p>
Next: <a href="#Overview" accesskey="n" rel="next">Overview</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h1 class="top" id="ra_003a_003a"><code class="code">ra::</code></h1>

<p><code class="code">ra::</code> (version 21, updated 2023 July 8)
</p>
<p>(c) Daniel Llorens 2005&ndash;2023
</p>
<div class="display smalldisplay">
<pre class="display-preformatted">Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
</pre></div>

<p><code class="code">ra::</code><a class="footnote" id="DOCF1" href="#FOOT1"><sup>1</sup></a> is a general purpose multidimensional array and expression template library for C++20. Please keep in mind that this manual is a work in progress. There are many errors and whole sections unwritten.
</p>


<ul class="mini-toc">
<li><a href="#Overview" accesskey="1">Overview</a></li>
<li><a href="#Usage" accesskey="2">Usage</a></li>
<li><a href="#Extras" accesskey="3">Extras</a></li>
<li><a href="#Hazards" accesskey="4">Hazards</a></li>
<li><a href="#Internals" accesskey="5">Internals</a></li>
<li><a href="#The-future" accesskey="6">The future</a></li>
<li><a href="#Reference" accesskey="7">Reference</a></li>
<li><a href="#Sources" accesskey="8">Sources</a></li>
<li><a href="#Indices" accesskey="9">Indices</a></li>
<li><a href="#Notes">Notes</a></li>
</ul>
<hr>
<div class="chapter-level-extent" id="Overview">
<div class="nav-panel">
<p>
Next: <a href="#Usage" accesskey="n" rel="next">Usage</a>, Previous: <a href="#Top" accesskey="p" rel="prev"><code class="code">ra::</code></a>, Up: <a href="#Top" accesskey="u" rel="up"><code class="code">ra::</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Overview-1">1 Overview</h2>

<a class="index-entry-id" id="index-length"></a>
<a class="index-entry-id" id="index-rank"></a>
<a class="index-entry-id" id="index-shape"></a>
<p>A multidimensional array is a container whose elements can be looked up using a multi-index (i₀, i₁, ...). Each of the indices i₀, i₁, ... has a constant range [0, n₀), [0, n₁), ... independent of the values of the other indices, so the array is ‘rectangular’. The number of indices in the multi-index is the <em class="dfn">rank</em> of the array, and the list of all the <em class="dfn">lengths</em> (n₀, n₁, ... nᵣ₋₁) is the <em class="dfn">shape</em> of the array. We speak of a rank-<em class="math tex2jax_process">\(r\)</em> array or of an <em class="math tex2jax_process">\(r\)</em>-array.
</p>
<p>Often we deal with multidimensional <em class="emph">expressions</em> where the elements aren&rsquo;t stored anywhere, but are computed on demand when the expression is looked up. In this general sense, an ‘array’ is just a function of integers with a rectangular domain.
</p>
<p>Arrays (as a representation of <em class="dfn">matrices</em>, <em class="dfn">vectors</em>, or <em class="dfn">tensors</em>) are common objects in math and programming, and it is very useful to be able to manipulate arrays as individual entities rather than as aggregates. Not only is
</p>
<pre class="verbatim">A = B+C;
</pre>
<p>much more compact and easier to read than
</p>
<pre class="verbatim">for (int i=0; i!=m; ++i)
    for (int j=0; j!=n; ++j)
        for (int k=0; k!=p; ++k)
            A(i, j, k) = B(i, j, k)+C(i, j, k);
</pre>
<p>but it&rsquo;s also safer and less redundant. For example, the order of the loops may be something you don&rsquo;t really care about.
</p>
<p>However, if array operations are implemented naively, a piece of code such as <code class="code">A=B+C</code> may result in the creation of a temporary to hold <code class="code">B+C</code> which is then assigned to <code class="code">A</code>. This is wasteful if the arrays involved are large.
</p>
<a class="index-entry-id" id="index-Blitz_002b_002b"></a>
<p>Fortunately the problem is almost as old as aggregate data types, and other programming languages have addressed it with optimizations such as <a class="url" href="https://en.wikipedia.org/wiki/Loop_fission_and_fusion">‘loop fusion’</a>, ‘drag along’ [<a class="ref" href="#Sources">Abr70</a>]
, or ‘deforestation’ [<a class="ref" href="#Sources">Wad90</a>]
. In the C++ context the technique of ‘expression templates’ was pioneered in the late 90s by libraries such as Blitz++ [<a class="ref" href="#Sources">bli17</a>]
. It works by making <code class="code">B+C</code> into an ‘expression object’ which holds references to its arguments and performs the sum only when its elements are looked up. The compiler removes the temporary expression objects during optimization, so that <code class="code">A=B+C</code> results (in principle) in the same generated code as the complicated loop nest above.
</p>

<ul class="mini-toc">
<li><a href="#Rank-polymorphism" accesskey="1">Rank polymorphism</a></li>
<li><a href="#Drag-along-and-beating" accesskey="2">Drag along and beating</a></li>
<li><a href="#Why-C_002b_002b" accesskey="3">Why C++</a></li>
<li><a href="#Guidelines" accesskey="4">Guidelines</a></li>
<li><a href="#Other-libraries" accesskey="5">Other array libraries</a></li>
</ul>
<hr>
<div class="section-level-extent" id="Rank-polymorphism">
<div class="nav-panel">
<p>
Next: <a href="#Drag-along-and-beating" accesskey="n" rel="next">Drag along and beating</a>, Up: <a href="#Overview" accesskey="u" rel="up">Overview</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Rank-polymorphism-1">1.1 Rank polymorphism</h3>

<p><em class="dfn">Rank polymorphism</em> is the ability to treat an array of rank <em class="math tex2jax_process">\(r\)</em> as an array of lower rank where the elements are themselves arrays.
</p>
<a class="index-entry-id" id="index-cell"></a>
<a class="index-entry-id" id="index-frame"></a>
<p>For example, think of a matrix A, a 2-array with shape (n₀, n₁) where the elements A(i₀, i₁) are numbers. If we consider the subarrays A(0, ...), A(1, ...), ..., A(n₀-1, ...) as individual elements, then we have a new view of A as a 1-array of length n₀ with those rows as elements. We say that the rows A(i₀)≡A(i₀, ...) are the 1-<em class="dfn">cells</em> of A, and the numbers A(i₀, i₁) are 0-cells of A. For an array of arbitrary rank <em class="math tex2jax_process">\(r\)</em> the (<em class="math tex2jax_process">\(r\)</em>-1)-cells of A are called its <em class="dfn">items</em>. The prefix of the shape (n₀, n₁, ... nₙ₋₁₋ₖ) that is not taken up by the k-cell is called the k-<em class="dfn">frame</em>.
</p>
<p>An obvious way to store an array in linearly addressed memory is to place its items one after another. So we would store a 3-array as
</p>
<blockquote class="quotation">
<p>A: [A(0), A(1), ...]
</p></blockquote>

<p>and the items of A(i₀), etc. are in turn stored in the same way, so
</p>
<blockquote class="quotation">
<p>A: [A(0): [A(0, 0), A(0, 1) ...], ...]
</p></blockquote>

<p>and the same for the items of A(i₀, i₁), etc.
</p>
<blockquote class="quotation">
<p>A: [[A(0, 0): [A(0, 0, 0), A(0, 0, 1) ...], A(0, 1): [A(0, 1, 0), A(0, 1, 1) ...]], ...]
</p></blockquote>

<a class="index-entry-id" id="index-order_002c-row_002dmajor"></a>
<p>This way to lay out an array in memory is called <em class="dfn">row-major order</em> or <em class="dfn">C-order</em>, since it&rsquo;s the default order for built-in arrays in C (see <a class="pxref" href="#Other-libraries">Other array libraries</a>). A row-major array A with shape (n₀, n₁, ... nᵣ₋₁) can be looked up like this:
</p>
<a class="anchor" id="x_002dsteps"></a><blockquote class="quotation">
<p>A(i₀, i₁, ...) = (storage-of-A) [(((i₀n₁ + i₁)n₂ + i₂)n₃ + ...)+iᵣ₋₁] = (storage-of-A) [o + s₀i₀ + s₁i₁ +  ...]
</p></blockquote>

<a class="index-entry-id" id="index-step"></a>
<a class="index-entry-id" id="index-stride"></a>
<p>where the numbers (s₀, s₁, ...) are called the <em class="dfn">steps</em><a class="footnote" id="DOCF2" href="#FOOT2"><sup>2</sup></a>. Note that the ‘linear’ or ‘raveled’ address [o + s₀i₀ + s₁i₁ +  ...] is an affine function of (i₀, i₁, ...). If we represent an array as a tuple
</p>
<blockquote class="quotation">
<p>A ≡ ((storage-of-A), o, (s₀, s₁, ...))
</p></blockquote>

<p>then any affine transformation of the indices can be achieved simply by modifying the numbers (o, (s₀, s₁, ...)), with no need to touch the storage. This includes common operations such as: <a class="ref" href="#x_002dtranspose">transposing</a> axes, <a class="ref" href="#x_002dreverse">reversing</a> the order along an axis, most cases of <a class="ref" href="#Slicing">slicing</a>, and sometimes even reshaping or tiling the array.
</p>
<p>A basic example is obtaining the i₀-th item of A:
</p>
<blockquote class="quotation">
<p>A(i₀) ≡ ((storage-of-A), o+s₀i₀, (s₁, ...))
</p></blockquote>

<p>Note that we can iterate over these items by simply bumping the pointer o+s₀i₀. This means that iterating over (k&gt;0)-cells doesn&rsquo;t cost any  more than iterating over 0-cells (see <a class="pxref" href="#Cell-iteration">Cell iteration</a>).
</p>
<hr>
</div>
<div class="section-level-extent" id="Drag-along-and-beating">
<div class="nav-panel">
<p>
Next: <a href="#Why-C_002b_002b" accesskey="n" rel="next">Why C++</a>, Previous: <a href="#Rank-polymorphism" accesskey="p" rel="prev">Rank polymorphism</a>, Up: <a href="#Overview" accesskey="u" rel="up">Overview</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Drag-along-and-beating-1">1.2 Drag along and beating</h3>

<p>These two fundamental array optimizations are described in [<a class="ref" href="#Sources">Abr70</a>]
.
</p>
<p><em class="dfn">Drag-along</em> is the process that delays evaluation of array operations. Expression templates can be seen as an implementation of drag-along. Drag-along isn&rsquo;t an optimization in and of itself; it simply preserves the necessary information up to the point where the expression can be executed efficiently.
</p>
<p><em class="dfn">Beating</em> is the implementation of certain array operations on the array <a class="ref" href="#Containers-and-views">view</a> descriptor instead of on the array contents. For example, if <code class="code">A</code> is a 1-array, one can implement <a class="ref" href="#x_002dreverse"><code class="code">reverse(A, 0)</code></a> by negating the <a class="ref" href="#x_002dsteps">step</a> and moving the offset to the other end of the array, without having to move any elements. More generally, beating applies to any function-of-indices (generator) that can take the place of an array in an array expression. For instance, an expression such as <a class="ref" href="#x_002diota"><code class="code">1+iota(3, 0)</code></a> can be beaten into <code class="code">iota(3, 1)</code>, and this can enable further optimizations.
</p>
<hr>
</div>
<div class="section-level-extent" id="Why-C_002b_002b">
<div class="nav-panel">
<p>
Next: <a href="#Guidelines" accesskey="n" rel="next">Guidelines</a>, Previous: <a href="#Drag-along-and-beating" accesskey="p" rel="prev">Drag along and beating</a>, Up: <a href="#Overview" accesskey="u" rel="up">Overview</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Why-C_002b_002b-1">1.3 Why C++</h3>

<p>Of course the main reason is that (this being a personal project) I&rsquo;m more familiar with C++ than with other languages to which the following might apply.
</p>
<p>C++ supports the low level control that is necessary for interoperation with external libraries and languages, but still has the abstraction power to create the features we want even though the language has no native support for most of them.
</p>
<a class="index-entry-id" id="index-APL"></a>
<a class="index-entry-id" id="index-J"></a>
<p>The classic array languages, APL [<a class="ref" href="#Sources">FI73</a>]
 and J [<a class="ref" href="#Sources">Ric08</a>]
, have array support baked in. The same is true for other languages with array facilities such as Fortran or Octave/Matlab. Array libraries for general purpose languages usually depend heavily on C extensions. In Numpy&rsquo;s case [<a class="ref" href="#Sources">num17</a>]
 this is both for reasons of flexibility (e.g. to obtain predictable memory layout and machine types) and of performance.
</p>
<p>On the other extreme, an array library for C would be hampered by the limited means of abstraction in the language (no polymorphism, no metaprogramming, etc.) so the natural choice of C programmers is to resort to code generators, which eventually turn into new languages.
</p>
<p>In C++, a library is enough.
</p>
<hr>
</div>
<div class="section-level-extent" id="Guidelines">
<div class="nav-panel">
<p>
Next: <a href="#Other-libraries" accesskey="n" rel="next">Other array libraries</a>, Previous: <a href="#Why-C_002b_002b" accesskey="p" rel="prev">Why C++</a>, Up: <a href="#Overview" accesskey="u" rel="up">Overview</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Guidelines-1">1.4 Guidelines</h3>

<p><code class="code">ra::</code> attempts to be general, consistent, and transparent.
</p>
<p>Generality is achieved by removing arbitrary restrictions and by adopting the rank extension mechanism of J. <code class="code">ra::</code> supports array operations with an arbitrary number of arguments. Any of the arguments in an array expression can be read from or written to. Arrays or array expressions can be of any rank. Slicing operations work for subscripts of any rank, as in APL. You can use your own types as array elements.
</p>
<p>Consistency is achieved by having a clear set of concepts and having the realizations of those concepts adhere to the concept as closely as possible. <code class="code">ra::</code> offers a few different types of views and containers, but it should be possible to use them interchangeably whenever the properties that justify their existence are not involved. When this isn&rsquo;t possible, it&rsquo;s a bug. For example, it used to be the case that you couldn&rsquo;t create a higher rank iterator on a <code class="code">SmallView</code>, even though you could do it on a <code class="code">View</code>; this was a bug.
</p>
<p>Sometimes consistency requires a choice. For example, given array views A and B, <code class="code">A=B</code> copies the contents of view B into view A. To change view A instead (to treat A as a pointer) would be the default meaning of A=B for C++ types, and result in better consistency with the rest of the language, but I have decided that having consistency between views and containers (which ‘are’ their contents in a sense that views aren&rsquo;t) is more important.<a class="footnote" id="DOCF3" href="#FOOT3"><sup>3</sup></a>
</p>
<p>Transparency is achieved by avoiding unnecessary abstraction. An array view consists of a pointer and a list of steps and I see no point in hiding that. Manipulating the steps directly is often useful. A container consists of storage and a view and that isn&rsquo;t hidden either. Some of the types have an obscure implementation but I consider that a defect. Ideally you should be able to rewrite expressions on the fly, or plug in your own traversal methods or storage handling.
</p>
<p>That isn&rsquo;t to mean that you need to be in command of a lot of internal detail to be able to use the library. I hope to have provided a high level interface to most operations and a reasonably usable syntax. However, transparency is critical to achieve interoperation with external libraries and languages. When you need to, you&rsquo;ll be able to guarantee that an array is stored in compact columns, or that the real parts are interleaved with the imaginary parts.
</p>
<hr>
</div>
<div class="section-level-extent" id="Other-libraries">
<div class="nav-panel">
<p>
Previous: <a href="#Guidelines" accesskey="p" rel="prev">Guidelines</a>, Up: <a href="#Overview" accesskey="u" rel="up">Overview</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Other-array-libraries">1.5 Other array libraries</h3>

<p>Here I try to list the C++ array libraries that I know of, or libraries that I think deserve a mention for the way they deal with arrays. It is not an extensive review, since I have only used a few of these libraries myself. Please follow the links if you want to be properly informed.
</p>
<p>Since the C++ standard library doesn&rsquo;t offer a standard multidimensional array type, some libraries for specific tasks (linear algebra operations, finite elements, optimization) offer an accessory array library, which may be more or less general. Other libraries have generic array interfaces without needing to provide an array type. FFTW is a good example, maybe because it isn&rsquo;t C++!
</p>
<ul class="mini-toc">
<li><a href="#Standard-C_002b_002b" accesskey="1">Standard C++</a></li>
<li><a href="#Blitz_002b_002b" accesskey="2">Blitz++</a></li>
<li><a href="#Other-C_002b_002b-libraries" accesskey="3">Other C++ libraries</a></li>
<li><a href="#Other-languages" accesskey="4">Other languages</a></li>
</ul>
<div class="subsection-level-extent" id="Standard-C_002b_002b">
<h4 class="subsection">1.5.1 Standard C++</h4>

<p>The C++ language offers multidimensional arrays as a legacy feature from C, e.g. <code class="code">int a[3][4]</code>. These decay to pointers when you do nearly anything with them, don&rsquo;t know their own shape or rank at runtime, and are generally too limited.
</p>
<p>The C++ standard library also offers a number of contiguous storage containers that can be used as 1-arrays: <code class="code">&lt;array&gt;</code>, <code class="code">&lt;vector&gt;</code> and <code class="code">&lt;valarray&gt;</code>. Neither supports higher ranks out of the box, but <code class="code">&lt;valarray&gt;</code> offers array operations for 1-arrays. <code class="code">ra::</code> makes use of <code class="code">&lt;array&gt;</code> and <code class="code">&lt;vector&gt;</code> for storage and bootstrapping.
</p>
<p><code class="code">ra::</code> accepts built-in arrays and standard library types as array objects (see <a class="pxref" href="#Compatibility">Compatibility</a>).
</p>
</div>
<div class="subsection-level-extent" id="Blitz_002b_002b">
<h4 class="subsection">1.5.2 Blitz++</h4>
<a class="index-entry-id" id="index-Blitz_002b_002b-1"></a>
<p>Blitz++ [<a class="ref" href="#Sources">bli17</a>]
 pioneered the use of expression templates in C++. It supported higher rank arrays, as high as it was practical in C++98, but not runtime rank. It also supported small arrays with compile time shape (<code class="code">Tiny</code>), and convenience features such as Fortran-order constructors and arbitrary lower bounds for the array indices (both of which <code class="code">ra::</code> chooses not to support). It placed a strong emphasis on performance, with array traversal methods such as blocking, space filling curves, etc.
</p>
<p>However, the implementation had to fight the limitations of C++98, and it offered no general rank extension mechanism.
</p>
<p>One important difference between Blitz++ and <code class="code">ra::</code> is that Blitz++&rsquo;s arrays were reference counted. <code class="code">ra::</code> doesn&rsquo;t do any memory management on its own: the default container (data-owning) types are values, and views are distinct types. You can select your own storage for the data-owning objects, including reference-counted storage (<code class="code">ra::</code> declares a type using <code class="code">std::shared_ptr</code>), but this is not the default.
</p>
</div>
<div class="subsection-level-extent" id="Other-C_002b_002b-libraries">
<h4 class="subsection">1.5.3 Other C++ libraries</h4>

<p>TODO
</p>
</div>
<div class="subsection-level-extent" id="Other-languages">
<h4 class="subsection">1.5.4 Other languages</h4>

<p>TODO Maybe review other languages, at least the big ones (Fortran / APL / J / Matlab / Python-Numpy).
</p>
<hr>
</div>
</div>
</div>
<div class="chapter-level-extent" id="Usage">
<div class="nav-panel">
<p>
Next: <a href="#Extras" accesskey="n" rel="next">Extras</a>, Previous: <a href="#Overview" accesskey="p" rel="prev">Overview</a>, Up: <a href="#Top" accesskey="u" rel="up"><code class="code">ra::</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Usage-1">2 Usage</h2>

<p>This is an extended exposition of the features of <code class="code">ra::</code> and is probably best read in order. For details on specific functions or types, please see <a class="pxref" href="#Reference">Reference</a>.
</p>

<ul class="mini-toc">
<li><a href="#Using-the-library" accesskey="1">Using <code class="code">ra::</code></a></li>
<li><a href="#Containers-and-views" accesskey="2">Containers and views</a></li>
<li><a href="#Array-operations" accesskey="3">Array operations</a></li>
<li><a href="#Rank-extension" accesskey="4">Rank extension</a></li>
<li><a href="#Cell-iteration" accesskey="5">Cell iteration</a></li>
<li><a href="#Slicing" accesskey="6">Slicing</a></li>
<li><a href="#Special-objects" accesskey="7">Special objects</a></li>
<li><a href="#The-rank-conjunction" accesskey="8">The rank conjunction</a></li>
<li><a href="#Compatibility" accesskey="9">Compatibility</a></li>
<li><a href="#Extension">Extension</a></li>
<li><a href="#Functions">Functions</a></li>
<li><a href="#Error-handling">Error handling</a></li>
</ul>
<hr>
<div class="section-level-extent" id="Using-the-library">
<div class="nav-panel">
<p>
Next: <a href="#Containers-and-views" accesskey="n" rel="next">Containers and views</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Using-ra_003a_003a">2.1 Using <code class="code">ra::</code></h3>

<p><code class="code">ra::</code> is a header only library with no dependencies other than the standard library, so you just need to place the &lsquo;<samp class="samp">ra/</samp>&rsquo; folder somewhere in your include path and add <code class="code">#include &quot;ra/ra.hh&quot;</code> at the top of your sources.
</p>
<p>A compiler with C++20 support is required. At the time of writing this means <b class="b">gcc 11</b> or with <samp class="option">-std=c++20</samp>. Some C++23 features are available with <samp class="option">-std=c++2b</samp>. Check the top README.md for more up-to-date information.
</p>
<p>Here is a minimal program<a class="footnote" id="DOCF4" href="#FOOT4"><sup>4</sup></a>:
</p>
<div class="example">
<pre class="verbatim">#include &quot;ra/ra.hh&quot;
#include &lt;iostream&gt;

int main()
{
    ra::Big&lt;char, 2&gt; A({2, 5}, &quot;helloworld&quot;);
    std::cout &lt;&lt; ra::noshape &lt;&lt; format_array(transpose&lt;1, 0&gt;(A), &quot;|&quot;) &lt;&lt; std::endl;
}
</pre><pre class="example-preformatted">-| h|w
   e|o
   l|r
   l|l
   d|d
</pre></div>

<p>The following headers are <em class="emph">not</em> included by default:
</p><ul class="itemize mark-bullet">
<li><code class="code">&quot;ra/dual.hh&quot;</code>: A dual number type for simple uses of automatic differentiation.

</li><li><code class="code">&quot;ra/mpdebug.hh&quot;</code>: Functions to help in debugging template tangles.

</li><li><code class="code">&quot;ra/test.hh&quot;</code>, <code class="code">&quot;ra/bench.hh&quot;</code>: Used by the test and benchmark suites.
</li></ul>

<p>The header <code class="code">&quot;ra/bootstrap.hh&quot;</code> can be used to configure <a class="ref" href="#Error-handling">Error handling</a>. You don&rsquo;t need to modify the header, but the configuration depends on including <code class="code">&quot;ra/bootstrap.hh&quot;</code> before the rest of <code class="code">ra::</code>.
</p>
<p>All other headers are for internal use by <code class="code">ra::</code><a class="footnote" id="DOCF5" href="#FOOT5"><sup>5</sup></a>
</p>
<img class="image" src="headers.png" alt="headers">

<a class="index-entry-id" id="index-container"></a>
<hr>
</div>
<div class="section-level-extent" id="Containers-and-views">
<div class="nav-panel">
<p>
Next: <a href="#Array-operations" accesskey="n" rel="next">Array operations</a>, Previous: <a href="#Using-the-library" accesskey="p" rel="prev">Using <code class="code">ra::</code></a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Containers-and-views-1">2.2 Containers and views</h3>

<p><code class="code">ra::</code> offers two kinds of data objects. The first kind, the <em class="dfn">container</em>, owns its data. Creating a container uses up memory and destroying it causes that memory to be freed.
</p>
<a class="index-entry-id" id="index-compile_002dtime"></a>
<a class="index-entry-id" id="index-ct"></a>
<a class="index-entry-id" id="index-runtime"></a>
<a class="index-entry-id" id="index-rt"></a>
<p>There are three kinds of containers (ct: compile-time, rt: runtime): 1) ct size, 2) ct rank/rt shape, and 3) rt rank; rt rank implies rt shape. Some rt size arrays can be resized but rt rank arrays cannot normally have their rank changed. Instead, you create a new container or view with the rank you want.
</p>
<p>For example:
</p>
<div class="example">
<pre class="verbatim">{
    ra::Small&lt;double, 2, 3&gt; a(0.);     // a ct size 2x3 array
    ra::Big&lt;double, 2&gt; b({2, 3}, 0.);  // a rt size 2x3 array
    ra::Big&lt;double&gt; c({2, 3}, 0.);     // a rt rank 2x3 array
    // a, b, c destroyed at end of scope
}
</pre></div>

<p>Using the right kind of container can result in better performance. Ct shapes do not need to be stored in memory, which matters when you have many small arrays. Ct shape or ct rank arrays are also safer to use; sometimes <code class="code">ra::</code> will be able to detect errors in the shapes or ranks of array operands at compile time, if the appropriate types are used.
</p>
<p>Container constructors come in two forms. The first form takes a single argument which is copied into the new container. This argument provides shape information if the container type requires it.<a class="footnote" id="DOCF6" href="#FOOT6"><sup>6</sup></a>
</p>
<div class="example">
<pre class="verbatim">using ra::Small, ra::Big;
Small&lt;int, 2, 2&gt; a = {{1, 2}, {3, 4}};  // explicit contents
Big&lt;int, 2&gt; a1 = {{1, 2}, {3, 4}};      // explicit contents
Small&lt;int, 2, 2&gt; a2 = {{1, 2}};         // error: bad shape
Small&lt;int, 2, 2&gt; b = 7;                 // 7 is copied into b
Small&lt;int, 2, 2&gt; c = a;                 // the contents of a are copied into c
Big&lt;int&gt; d = a;                         // d takes the shape of a and a is copied into d
Big&lt;int&gt; e = 0;                         // e is a 0-array with one element f()==0.
</pre></div>

<p>The second form takes two arguments, one giving the shape, the second the contents.
</p>
<a class="index-entry-id" id="index-none"></a>
<a class="index-entry-id" id="index-uninitialized-container"></a>
<div class="example">
<pre class="verbatim">ra::Big&lt;double, 2&gt; a({2, 3}, 1.);     // a has shape [2 3], filled with 1.
ra::Big&lt;double&gt; b({2, 3}, ra::none);  // b has shape [2 3], default initialized
ra::Big&lt;double&gt; c({2, 3}, a);         // c has shape [2 3], a is copied into c
</pre></div>

<p>The last example may result in an error if the shape of <code class="code">a</code> and (2,&nbsp;<!-- /@w -->3) don&rsquo;t match. Here the shape of <code class="code">1.</code> [which is ()] matches (2,&nbsp;<!-- /@w -->3) by a mechanism of rank extension (see <a class="pxref" href="#Rank-extension">Rank extension</a>). The special value <code class="code">ra::none</code> can be used to request <a class="url" href="https://en.cppreference.com/w/cpp/language/default_initialization">default initialization</a> of the container&rsquo;s elements.
</p>
<p>The shape argument can have rank 0 only for rank 1 arrays.
</p>
<a class="index-entry-id" id="index-none-1"></a>
<a class="index-entry-id" id="index-uninitialized-container-1"></a>
<div class="example">
<pre class="verbatim">ra::Big&lt;int&gt; c(3, 0);      // ok {0, 0, 0}, same as ra::Big&lt;int&gt; c({3}, 0)
ra::Big&lt;int, 1&gt; c(3, 0);   // ok {0, 0, 0}, same as ra::Big&lt;int, 1&gt; c({3}, 0)
ra::Big&lt;int, 2&gt; c({3}, 0); // error: bad length for shape
ra::Big&lt;int, 2&gt; c(3, 0);   // error: bad length for shape
</pre></div>

<p>When the content argument is a pointer or a 1D brace list, it&rsquo;s handled especially, not for shape<a class="footnote" id="DOCF7" href="#FOOT7"><sup>7</sup></a>, but only as the (row-major) ravel of the content. The pointer constructor is unsafe —use at your own risk!<a class="footnote" id="DOCF8" href="#FOOT8"><sup>8</sup></a>
</p>
<a class="index-entry-id" id="index-order_002c-column_002dmajor"></a>
<div class="example">
<pre class="verbatim">Small&lt;int, 2, 2&gt; aa = {1, 2, 3, 4}; // ravel of the content

ra::Big&lt;double, 2&gt; a({2, 3}, {1, 2, 3, 4, 5, 6}); // same as a = {{1, 2, 3}, {4, 5, 6}}
</pre></div>

<div class="example">
<pre class="verbatim">double bx[6] = {1, 2, 3, 4, 5, 6}
ra::Big&lt;double, 2&gt; b({3, 2}, bx); // {{1, 2}, {3, 4}, {5, 6}}

double cx[4] = {1, 2, 3, 4}
ra::Big&lt;double, 2&gt; c({3, 2}, cx); // *** WHO NOSE ***
</pre></div>

<div class="example">
<pre class="verbatim">using lens = mp::int_list&lt;2, 3&gt;;
using steps = mp::int_list&lt;1, 2&gt;;
ra::SmallArray&lt;double, lens, steps&gt; a {{1, 2, 3}, {4, 5, 6}}; // stored column-major: 1 4 2 5 3 6
</pre></div>

<p>These produce compile time errors:
</p>
<div class="example">
<pre class="verbatim">Big&lt;int, 2&gt; b = {1, 2, 3, 4};           // error: shape cannot be deduced from ravel
Small&lt;int, 2, 2&gt; b = {1, 2, 3, 4 5};    // error: bad size
Small&lt;int, 2, 2&gt; b = {1, 2, 3};         // error: bad size
</pre></div>

<a class="anchor" id="x_002dscalar_002dchar_002dstar"></a><p>Sometimes the pointer constructor gets in the way (see <a class="ref" href="#x_002dscalar"><code class="code">scalar</code></a>): </p>
<div class="example">
<pre class="verbatim">ra::Big&lt;char const *, 1&gt; A({3}, &quot;hello&quot;); // error: try to convert char to char const *
ra::Big&lt;char const *, 1&gt; A({3}, ra::scalar(&quot;hello&quot;)); // ok, &quot;hello&quot; is a single item
cout &lt;&lt; ra::noshape &lt;&lt; format_array(A, &quot;|&quot;) &lt;&lt; endl;
</pre><pre class="example-preformatted">-| hello|hello|hello
</pre></div>

<a class="index-entry-id" id="index-view"></a>
<p>A <em class="dfn">view</em> is similar to a container in that it points to actual data in memory. However, the view doesn&rsquo;t own that data and destroying the view won&rsquo;t affect it. For example:
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double&gt; c({2, 3}, 0.);     // a rt rank 2x3 array
{
    auto c1 = c(1);                // the second row of array c
    // c1 is destroyed here
}
cout &lt;&lt; c(1, 1) &lt;&lt; endl;           // ok
</pre></div>

<p>The data accessed through a view is the data of the ‘root’ container, so modifying the former will be reflected in the latter.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double&gt; c({2, 3}, 0.);
auto c1 = c(1);
c1(2) = 9.;                        // c(1, 2) = 9.
</pre></div>

<p>Just as for containers, there are separate types of views depending on whether the shape is known at compile time, the rank is known at compile time but the shape is not, or neither the shape nor the rank are known at compile time. <code class="code">ra::</code> has functions to create the most common kinds of views:
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double&gt; c {{1, 2, 3}, {4, 5, 6}};
auto ct = transpose&lt;1, 0&gt;(c); // {{1, 4}, {2, 5}, {3, 6}}
auto cr = reverse(c, 0); // {{4, 5, 6}, {1, 2, 3}}
</pre></div>

<p>However, views can point to anywhere in memory and that memory doesn&rsquo;t have to belong to an <code class="code">ra::</code> container. For example:
</p>
<div class="example">
<pre class="verbatim">int raw[6] = {1, 2, 3, 4, 5, 6};
ra::View&lt;int&gt; v1({{2, 3}, {3, 1}}, raw); // view with shape [2, 3] steps [3, 1]
ra::View&lt;int&gt; v2({2, 3}, raw);           // same, default C (row-major) steps
</pre></div>

<p>Containers can be treated as views of the same kind (rt or ct) . If you declare a function
</p>
<div class="example">
<pre class="verbatim">void f(ra::View&lt;int, 3&gt; &amp; v);
</pre></div>

<p>you may pass it an object of type <code class="code">ra::Big&lt;int, 3&gt;</code>.
</p>

<hr>
</div>
<div class="section-level-extent" id="Array-operations">
<div class="nav-panel">
<p>
Next: <a href="#Rank-extension" accesskey="n" rel="next">Rank extension</a>, Previous: <a href="#Containers-and-views" accesskey="p" rel="prev">Containers and views</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Array-operations-1">2.3 Array operations</h3>

<p>To apply an operation to each element of an array, use the function <code class="code">for_each</code>. The array is traversed in an order that is decided by the library.
</p>
<div class="example">
<pre class="verbatim">ra::Small&lt;double, 2, 3&gt; a = {{1, 2, 3}, {4, 5, 6}};
double s = 0.;
for_each([&amp;s](auto &amp;&amp; a) { s+=a; }, a);
</pre><pre class="example-preformatted">&rArr; s = 21.
</pre></div>

<p>To construct an array expression but stop short of traversing it, use the function <code class="code">map</code>. The expression will be traversed when it is assigned to a view, printed out, etc.
</p>
<div class="example">
<pre class="verbatim">using T = ra::Small&lt;double, 2, 2&gt;;
T a = {{1, 2}, {3, 4}};
T b = {{10, 20}, {30, 40}};
T c = map([](auto &amp;&amp; a, auto &amp;&amp; b) { return a+b; }, a, b); // (1)
</pre><pre class="example-preformatted">&rArr; c = {{11, 22}, {33, 44}}
</pre></div>

<p>Expressions may take any number of arguments and be nested arbitrarily.
</p>
<div class="example">
<pre class="verbatim">T d = 0;
for_each([](auto &amp;&amp; a, auto &amp;&amp; b, auto &amp;&amp; d) { d = a+b; },
         a, b, d); // same as (1)
for_each([](auto &amp;&amp; ab, auto &amp;&amp; d) { d = ab; },
         map([](auto &amp;&amp; a, auto &amp;&amp; b) { return a+b; },
             a, b),
         d); // same as (1)
</pre></div>

<p>The operator of an expression may return a reference and you may assign to an expression in that case. <code class="code">ra::</code> will complain if the expression is somehow not assignable.
</p>
<div class="example">
<pre class="verbatim">T d = 0;
map([](auto &amp; d) -&gt; decltype(auto) { return d; }, d) // just pass d along
  = map([](auto &amp;&amp; a, auto &amp;&amp; b) { return a+b; }, a, b); // same as (1)
</pre></div>

<p><code class="code">ra::</code> defines many shortcuts for common array operations. You can of course just do:
</p>
<div class="example">
<pre class="verbatim">T c = a+b; // same as (1)
</pre></div>

<hr>
</div>
<div class="section-level-extent" id="Rank-extension">
<div class="nav-panel">
<p>
Next: <a href="#Cell-iteration" accesskey="n" rel="next">Cell iteration</a>, Previous: <a href="#Array-operations" accesskey="p" rel="prev">Array operations</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Rank-extension-1">2.4 Rank extension</h3>

<p>Rank extension is the mechanism that allows <code class="code">R+S</code> to be defined even when <code class="code">R</code>, <code class="code">S</code> may have different ranks. The idea is an interpolation of the following basic cases.
</p>
<p>Suppose first that <code class="code">R</code> and <code class="code">S</code> have the same rank. We require that the shapes be the same. Then the shape of <code class="code">R+S</code> will be the same as the shape of either <code class="code">R</code> or <code class="code">S</code> and the elements of <code class="code">R+S</code> will be
</p>
<blockquote class="quotation">
<p><code class="code">(R+S)(i₀ i₁ ... i₍ᵣ₋₁₎) = R(i₀ i₁ ... i₍ᵣ₋₁₎) + S(i₀ i₁ ... i₍ᵣ₋₁₎)</code>
</p></blockquote>

<p>where <code class="code">r</code> is the rank of <code class="code">R</code>.
</p>
<p>Now suppose that <code class="code">S</code> has rank 0. The shape of <code class="code">R+S</code> is the same as the shape of <code class="code">R</code> and the elements of <code class="code">R+S</code> will be
</p>
<blockquote class="quotation">
<p><code class="code">(R+S)(i₀ i₁ ... i₍ᵣ₋₁₎) = R(i₀ i₁ ... i₍ᵣ₋₁₎) + S()</code>.
</p></blockquote>

<p>The two rules above are supported by all primitive array languages, e.g. Matlab [<a class="ref" href="#Sources">Mat</a>]
. But suppose that <code class="code">S</code> has rank <code class="code">s</code>, where <code class="code">0&lt;s&lt;r</code>. Looking at the expressions above, it seems natural to define <code class="code">R+S</code> by
</p>
<blockquote class="quotation">
<p><code class="code">(R+S)(i₀ i₁ ... i₍ₛ₋₁₎ ... i₍ᵣ₋₁₎) = R(i₀ i₁ ... i₍ₛ₋₁₎ ... i₍ᵣ₋₁₎) + S(i₀ i₁ ... i₍ₛ₋₁₎)</code>.
</p></blockquote>

<p>That is, after we run out of indices in <code class="code">S</code>, we simply repeat the elements. We have aligned the shapes so:
</p>
<blockquote class="quotation">
<pre class="verbatim">[n₀ n₁ ... n₍ₛ₋₁₎ ... n₍ᵣ₋₁₎]
[n₀ n₁ ... n₍ₛ₋₁₎]
</pre></blockquote>

<a class="index-entry-id" id="index-shape-agreement_002c-prefix"></a>
<a class="index-entry-id" id="index-shape-agreement_002c-suffix"></a>
<a class="index-entry-id" id="index-Numpy"></a>
<p>This rank extension rule is used by the J language [<a class="ref" href="#Sources">J S</a>]
 and is known as <em class="dfn">prefix agreement</em>. The opposite rule of <em class="dfn">suffix agreement</em> is used, for example, in Numpy [<a class="ref" href="#Sources">num17</a>]
<a class="footnote" id="DOCF9" href="#FOOT9"><sup>9</sup></a>.
</p>
<p>As you can verify, the prefix agreement rule is distributive. Therefore it can be applied to nested expressions or to expressions with any number of arguments. It is applied systematically throughout <code class="code">ra::</code>, even in assignments. For example,
</p>
<div class="example">
<pre class="verbatim">ra::Small&lt;int, 3&gt; x {3, 5, 9};
ra::Small&lt;int, 3, 2&gt; a = x; // assign x(i) to each a(i, j)
</pre><pre class="example-preformatted">&rArr; a = {{3, 3}, {5, 5}, {9, 9}}
</pre></div>

<div class="example">
<pre class="verbatim">ra::Small&lt;int, 3&gt; x(0.);
ra::Small&lt;int, 3, 2&gt; a = {{1, 2}, {3, 4}, {5, 6}};
x += a; // sum the rows of a
</pre><pre class="example-preformatted">&rArr; x = {3, 7, 11}
</pre></div>

<div class="example">
<pre class="verbatim">ra::Big&lt;double, 3&gt; a({5, 3, 3}, ra::_0);
ra::Big&lt;double, 1&gt; b({5}, 0.);
b += transpose&lt;0, 1, 1&gt;(a); // b(i) = ∑ⱼ a(i, j, j)
</pre><pre class="example-preformatted">&rArr; b = {0, 3, 6, 9, 12}
</pre></div>

<a class="index-entry-id" id="index-Numpy-1"></a>
<a class="index-entry-id" id="index-broadcasting_002c-singleton_002c-newaxis"></a>
<p>An weakness of prefix agreement is that the axes you want to match aren&rsquo;t always the prefix axes. Other array systems offer a feature similar to rank extension called ‘broadcasting’ that is a bit more flexible. For example, in the way it&rsquo;s implemented in Numpy [<a class="ref" href="#Sources">num17</a>]
, an array of shape [A B 1 D] will match an array of shape [A B C D]. The process of broadcasting consists in inserting so-called ‘singleton dimensions’ (axes with length one) to align the axes that one wishes to match. You can think of prefix agreement as a particular case of broadcasting where the singleton dimensions are added to the end of the shorter shapes automatically.
</p>
<p>A drawback of singleton broadcasting is that it muddles the distinction between a scalar and a vector of length 1. Sometimes, an axis of length 1 is no more than that, and if 2≠3 is a size mismatch, it isn&rsquo;t obvious why 1≠2 shouldn&rsquo;t be. To avoid this problem, <code class="code">ra::</code> supports broadcasting with undefined length axes (see <a class="ref" href="#x_002dinsert"><code class="code">insert</code></a>).
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double, 3&gt; a({5, 3}, ra::_0);
ra::Big&lt;double, 1&gt; b({3}, 0.);
ra::Big&lt;double, 3&gt; c({1, 3}, ra::_0);

// b(?, i) += a(j, i) → b(i) = ∑ⱼ a(j, i) (sum columns)
b(ra::insert&lt;1&gt;) += a;

c = a; // 1 ≠ 5, still an agreement error
</pre></div>

<p>Still another way to align array axes is provided by the <a class="ref" href="#The-rank-conjunction">rank conjunction</a>.
</p>
<p>Even with axis insertion, it is still necessary that the axes one wishes to match are in the same order in all the arguments.
<a class="ref" href="#x_002dtranspose">Transposing</a> the axes before extension is a possible workaround.
</p>
<hr>
</div>
<div class="section-level-extent" id="Cell-iteration">
<div class="nav-panel">
<p>
Next: <a href="#Slicing" accesskey="n" rel="next">Slicing</a>, Previous: <a href="#Rank-extension" accesskey="p" rel="prev">Rank extension</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Cell-iteration-1">2.5 Cell iteration</h3>

<p><code class="code">map</code> and <code class="code">for_each</code> apply their operators to each element of their arguments; in other words, to the 0-cells of the arguments. But it is possible to specify directly the rank of the cells that one iterates over:
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double, 3&gt; a({5, 4, 3}, ra::_0);
for_each([](auto &amp;&amp; b) { /* b has shape (5 4 3) */ }, iter&lt;3&gt;(a));
for_each([](auto &amp;&amp; b) { /* b has shape (4 3) */ }, iter&lt;2&gt;(a));
for_each([](auto &amp;&amp; b) { /* b has shape (3) */ }, iter&lt;1&gt;(a));
for_each([](auto &amp;&amp; b) { /* b has shape () */ }, iter&lt;0&gt;(a)); // elements
for_each([](auto &amp;&amp; b) { /* b has shape () */ }, a); // same as iter&lt;0&gt;(a); default
</pre></div>

<p>One may specify the <em class="emph">frame</em> rank instead:
</p>
<div class="example">
<pre class="verbatim">for_each([](auto &amp;&amp; b) { /* b has shape () */ }, iter&lt;-3&gt;(a)); // same as iter&lt;0&gt;(a)
for_each([](auto &amp;&amp; b) { /* b has shape (3) */ }, iter&lt;-2&gt;(a)); // same as iter&lt;1&gt;(a)
for_each([](auto &amp;&amp; b) { /* b has shape (4 3) */ }, iter&lt;-1&gt;(a)); // same as iter&lt;2&gt;(a)
</pre></div>

<p>In this way it is possible to match shapes in various ways. Compare
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double, 2&gt; a = {{1, 2, 3}, {4, 5, 6}};
ra::Big&lt;double, 1&gt; b = {10, 20};
ra::Big&lt;double, 2&gt; c = a * b; // multiply (each item of a) by (each item of b)
</pre><pre class="example-preformatted">&rArr; a = {{10, 20, 30}, {80, 100, 120}}
</pre></div>

<p>with
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double, 2&gt; a = {{1, 2, 3}, {4, 5, 6}};
ra::Big&lt;double, 1&gt; b = {10, 20, 30};
ra::Big&lt;double, 2&gt; c({2, 3}, 0.);
iter&lt;1&gt;(c) = iter&lt;1&gt;(a) * iter&lt;1&gt;(b); // multiply (each item of a) by (b)
</pre><pre class="example-preformatted">&rArr; a = {{10, 40, 90}, {40, 100, 180}}
</pre></div>

<p>Note that in this case we cannot construct <code class="code">c</code> directly from <code class="code">iter&lt;1&gt;(a) * iter&lt;1&gt;(b)</code>, since the constructor for <code class="code">ra::Big</code> matches its argument using (the equivalent of) <code class="code">iter&lt;0&gt;(*this)</code>. See <a class="ref" href="#x_002diter"><code class="code">iter</code></a> for more examples.
</p>
<p>Cell iteration is appropriate when the operations take naturally operands of rank &gt; 0; for instance, the operation ‘determinant of a matrix’ is naturally of rank 2. When the operation is of rank 0, such as <code class="code">*</code> above, there may be faster ways to rearrange shapes for matching (see <a class="pxref" href="#The-rank-conjunction">The rank conjunction</a>).
</p>
<p>FIXME More examples.
</p>
<hr>
</div>
<div class="section-level-extent" id="Slicing">
<div class="nav-panel">
<p>
Next: <a href="#Special-objects" accesskey="n" rel="next">Special objects</a>, Previous: <a href="#Cell-iteration" accesskey="p" rel="prev">Cell iteration</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Slicing-1">2.6 Slicing</h3>

<p>Slicing is an array extension of the subscripting operation. However, tradition and convenience have given it a special status in most array languages, together with some peculiar semantics that <code class="code">ra::</code> supports.
</p>
<p>The form of the scripting operator <code class="code">A(i₀, i₁, ...)</code> makes it plain that <code class="code">A</code> is a function of <code class="code">rank(A)</code> integer arguments<a class="footnote" id="DOCF10" href="#FOOT10"><sup>10</sup></a>. An array extension is immediately available through <code class="code">map</code>. For example:
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double, 1&gt; a = {1., 2., 3., 4.};
ra::Big&lt;int, 1&gt; i = {1, 3};
map(a, i) = 77.;
</pre><pre class="example-preformatted">&rArr; a = {1., 77., 3, 77.}
</pre></div>

<p>Just as with any use of <code class="code">map</code>, array arguments are subject to the prefix agreement rule.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double, 2&gt; a({2, 2}, {1., 2., 3., 4.});
ra::Big&lt;int, 1&gt; i = {1, 0};
ra::Big&lt;double, 1&gt; b = map(a, i, 0);
</pre><pre class="example-preformatted">&rArr; b = {3., 1.} // {a(1, 0), a(0, 0)}
</pre></div>

<div class="example">
<pre class="verbatim">ra::Big&lt;int, 1&gt; j = {0, 1};
b = map(a, i, j);
</pre><pre class="example-preformatted">&rArr; b = {3., 2.} // {a(1, 0), a(0, 1)}
</pre></div>

<p>The latter is a form of sparse subscripting.
</p>
<p>Most array operations (e.g. <code class="code">+</code>) are defined through <code class="code">map</code> in this way. For example, <code class="code">A+B+C</code> is defined as <code class="code">map(+, A, B, C)</code> (or the equivalent <code class="code">map(+, map(+, A, B), C)</code>). Not so for the subscripting operation:
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double, 2&gt; A {{1., 2.}, {3., 4.}};
ra::Big&lt;int, 1&gt; i = {1, 0};
ra::Big&lt;int, 1&gt; j = {0, 1};
// {{A(i₀, j₀), A(i₀, j₁)}, {A(i₁, j₀), A(i₁, j₁)}}
ra::Big&lt;double, 2&gt; b = A(i, j);
</pre><pre class="example-preformatted">&rArr; b = {{3., 4.}, {1., 2.}}
</pre></div>

<a class="anchor" id="x_002dsubscript_002douter_002dproduct"></a><p><code class="code">A(i, j, ...)</code> is defined as the <em class="emph">outer product</em> of the indices <code class="code">(i, j, ...)</code> with operator <code class="code">A</code>, because this operation sees much more use in practice than <code class="code">map(A, i, j ...)</code>.
</p>
<a class="index-entry-id" id="index-elision_002c-index"></a>
<p>You may give fewer subscripts than the rank of the array. The full extent is assumed for the missing subscripts (cf <a class="ref" href="#x_002dall"><code class="code">all</code></a> below):
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 3&gt; a({2, 2, 2}, {1, 2, 3, 4, 5, 6, 7, 8});
auto a0 = a(0); // same as a(0, ra::all, ra::all)
auto a10 = a(1, 0); // same as a(1, 0, ra::all)
</pre><pre class="example-preformatted">&rArr; a0 = {{1, 2}, {3, 4}}
&rArr; a10 = {5, 6}
</pre></div>

<p>This supports the notion (see <a class="pxref" href="#Rank-polymorphism">Rank polymorphism</a>) that a 3-array is also an 2-array where the elements are 1-arrays themselves, or a 1-array where the elements are 2-arrays. This important property is directly related to the mechanism of rank extension (see <a class="pxref" href="#Rank-extension">Rank extension</a>).
</p>
<p>Besides, when the subscripts <code class="code">i, j, ...</code> are scalars or integer sequences of the form <code class="code">(o, o+s, ..., o+s*(n-1))</code> (<em class="dfn">linear ranges</em>), the subscripting can be performed inmediately at constant cost, and without needing to construct an expression object. This optimization is called <a class="ref" href="#Drag-along-and-beating"><em class="dfn">beating</em></a>.
</p>
<p><code class="code">ra::</code> isn&rsquo;t smart enough to know when an arbitrary expression might be a linear range, so the following special objects are provided:
</p>
<a class="anchor" id="x_002diota"></a><dl class="first-deffn">
<dt class="deffn" id="index-iota"><span class="category-def">Special&nbsp;object<!-- /@w -->: </span><span><strong class="def-name">iota</strong> <var class="def-var-arguments">count [start:0 [step:1]]</var><a class="copiable-link" href='#index-iota'> &para;</a></span></dt>
<dd><p>Create a linear range <code class="code">start, start+step, ... start+step*(count-1)</code>.
</p>
<p>This can used anywhere an array expression is expected.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 1&gt; a = ra::iota(4, 3 -2);
</pre><pre class="example-preformatted">&rArr; a = {3, 1, -1, -3}
</pre></div>

<p>Here, <code class="code">b</code> and <code class="code">c</code> are <code class="code">View</code>s (see <a class="pxref" href="#Containers-and-views">Containers and views</a>).
</p><div class="example">
<pre class="verbatim">ra::Big&lt;int, 1&gt; a = {1, 2, 3, 4, 5, 6};
auto b = a(iota(3));
auto c = a(iota(3, 3));
</pre><pre class="example-preformatted">&rArr; a = {1, 2, 3}
&rArr; a = {4, 5, 6}
</pre></div>

</dd></dl>

<a class="anchor" id="x_002dall"></a><dl class="first-deffn">
<dt class="deffn" id="index-all"><span class="category-def">Special&nbsp;object<!-- /@w -->: </span><span><strong class="def-name">all</strong><a class="copiable-link" href='#index-all'> &para;</a></span></dt>
<dd><p>Create a linear range <code class="code">0, 1, ... (nᵢ-1)</code> when used as a subscript at the <var class="var">i</var>-th place of a subscripting expression. This might not be the <var class="var">i</var>-th argument; see <a class="ref" href="#x_002dinsert"><code class="code">insert</code></a>, <a class="ref" href="#x_002ddots"><code class="code">dots</code></a>.
</p>
<p>This object cannot stand alone as an array expression. All the examples below result in <code class="code">View</code> objects:
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 2&gt; a({3, 2}, {1, 2, 3, 4, 5, 6});
auto b = a(ra::all, ra::all); // (1) a view of the whole of a
auto c = a(iota(3), iota(2)); // same as (1)
auto d = a(iota(3), ra::all); // same as (1)
auto e = a(ra:all, iota(2)); // same as (1)
auto f = a(0, ra::all); // first row of a
auto g = a(ra::all, 1); // second column of a
auto g = a(ra::all, ra::dots&lt;0&gt;, 1); // same
</pre></div>

<p><code class="code">all</code> is a special case (<code class="code">dots&lt;1&gt;</code>) of the more general object <code class="code">dots</code>.
</p>
</dd></dl>

<a class="anchor" id="x_002ddots"></a><dl class="first-deffn">
<dt class="deffn" id="index-dots_003cn_003e"><span class="category-def">Special&nbsp;object<!-- /@w -->: </span><span><strong class="def-name">dots&lt;n&gt;</strong><a class="copiable-link" href='#index-dots_003cn_003e'> &para;</a></span></dt>
<dd><p>Equivalent to as many instances of <code class="code">ra::all</code> as indicated by <code class="code">n</code>, which must not be negative. Each instance takes the place of one argument to the subscripting operation.
</p>
<p>If <var class="var">n</var> is defaulted (<code class="code">dots&lt;&gt;</code>), all available places will be used; this can only be done once in a given subscript list.
</p>
<p>This object cannot stand alone as an array expression. All the examples below result in <code class="code">View</code> objects:
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 3&gt; a({3, 2, 4}, ...);
auto h = a(); // all of a

auto b = a(ra::all, ra::all, ra::all); // (1) all of a
auto c = a(ra::dots&lt;3&gt;); // same as (1)
auto d = a(ra::all, ra::dots&lt;2&gt;); // same as (1)
auto e = a(ra::dots&lt;2&gt;, ra::all); // same as (1)
auto f = a(ra::dots&lt;&gt;); // same as (1)

auto j0 = a(0, ra::dots&lt;2&gt;); // first page of a
auto j1 = a(0); // same
auto j2 = a(0, ra::dots&lt;&gt;); // same

auto k0 = a(ra::all, 0); // first row of a
auto k1 = a(ra::all, 0, ra::all); // same
auto k2 = a(ra::all, 0, ra::dots&lt;&gt;); // same
auto k3 = a(ra::dots&lt;&gt;, 0, ra::all); // same
// auto k = a(ra::dots&lt;&gt;, 0, ra::dots&lt;&gt;); // error

auto l0 = a(ra::all, ra::all, 0); // first column of a
auto l1 = a(ra::dots&lt;2&gt;, 0); // same
auto l2 = a(ra::dots&lt;&gt;, 0); // same
</pre></div>

<p>This is useful when writing rank-generic code, see <code class="code">examples/maxwell.cc</code> in the distribution for an example.
</p>
</dd></dl>

<p>The following special objects aren&rsquo;t related to linear ranges, but they are meant to be used in a subscript context.
</p>
<a class="index-entry-id" id="index-insert"></a>
<a class="anchor" id="x_002dinsert"></a><dl class="first-deffn">
<dt class="deffn" id="index-insert_003cn_003e"><span class="category-def">Special&nbsp;object<!-- /@w -->: </span><span><strong class="def-name">insert&lt;n&gt;</strong><a class="copiable-link" href='#index-insert_003cn_003e'> &para;</a></span></dt>
<dd><p>Inserts <code class="code">n</code> new axes at the subscript position. <code class="code">n</code> must not be negative.
</p>
<p>The new axes have step 0 and undefined length, so they will match any length on those axes by repeating items. <code class="code">insert</code> objects cannot stand alone as an array expression. The examples below result in <code class="code">View</code> objects:
</p>
<div class="example">
<pre class="verbatim">auto h = a(insert&lt;0&gt;); // same as (1)
auto k = a(insert&lt;1&gt;); // shape [undefined, 3, 2]
</pre></div>

<a class="index-entry-id" id="index-broadcasting_002c-singleton_002c-Numpy"></a>
<p><code class="code">insert&lt;n&gt;</code> main use is to prepare arguments for broadcasting. In other array systems (e.g. Numpy) broadcasting is done with singleton dimensions, that is, dimensions of length one match dimensions of any length. In <code class="code">ra::</code> singleton dimensions aren&rsquo;t special, so broadcasting requires the use of <code class="code">insert</code>. For example: </p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 1&gt; x = {1, 10};
// match shapes [2, U, U] with [U, 3, 2] to produce [2, 3, 2]
cout &lt;&lt; x(ra::all, ra::insert&lt;2&gt;) * a(insert&lt;1&gt;) &lt;&lt; endl;
</pre><pre class="example-preformatted">-| 2 3 2
1 2
3 4
5 6

10 20
30 40
50 60
</pre></div>

</dd></dl>

<a class="index-entry-id" id="index-len"></a>
<a class="index-entry-id" id="index-end_002c-Octave_002fMatlab"></a>
<a class="anchor" id="x_002dlen"></a><dl class="first-deffn">
<dt class="deffn" id="index-len-1"><span class="category-def">Special&nbsp;object<!-- /@w -->: </span><span><strong class="def-name">len</strong><a class="copiable-link" href='#index-len-1'> &para;</a></span></dt>
<dd><p>Represents the length of the <var class="var">i</var>-th axis of a subscripted expression, when used at the <var class="var">i</var>-th place of a subscripting expression.
</p>
<p>This works like <code class="code">end</code> in Octave/Matlab, but note that the last element of a vector <code class="code">a</code> is <code class="code">a(ra::len-1)</code>.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 2&gt; a({10, 10}, 100 + ra::_0 - ra::_1);
auto a0 = a(ra::len-1); // last row of a; ra::len is a.len(0)
auto a1 = a(ra::all, ra::len-1); // last column a; ra::len is a.len(1)
auto a2 = a(ra::len-1, ra::len-1); // last element of last row; the first ra::len is a.len(0) and the second one is a.len(1)
auto a3 = a(ra::all, ra::iota(2, ra::len-2)); // last two columns of a
auto a4 = a(ra::iota(ra::len/2, 1, 2)); // odd rows of a
a(ra::len - std::array {1, 3, 4}) = 0; // set to 0 the 1st, 3rd and 4th rows of a, counting from the end
</pre></div>

<div class="example">
<pre class="verbatim">ra::Big&lt;int, 3&gt; b({2, 3, 4}, ...);
auto b0 = b(ra::dots&lt;2&gt;, ra::len-1); // ra::len is a.len(2)
auto b1 = b(ra::insert&lt;1&gt;, ra::len-1); // ra::len is a.len(0)
</pre></div>

<p>Using <code class="code">ra::len</code> outside of a subscript context will result in a compile time error.<a class="footnote" id="DOCF11" href="#FOOT11"><sup>11</sup></a>
</p>
</dd></dl>

<p>We were speaking earlier of the outer product of the subscripts with operator <code class="code">A</code>. Here&rsquo;s a way to perform the actual outer product (with operator <code class="code">*</code>) of two <code class="code">Views</code>, through broadcasting. All three lines are equivalent. See <a class="ref" href="#x_002dfrom"><code class="code">from</code></a> for a more general way to compute outer products.
</p><div class="example">
<pre class="verbatim">cout &lt;&lt; (A(ra::dots&lt;A.rank()&gt;, ra::insert&lt;B.rank()&gt;) * B(ra::insert&lt;A.rank()&gt;, ra::dots&lt;B.rank()&gt;)) &lt;&lt; endl;
cout &lt;&lt; (A(ra::dots&lt;&gt;, ra::insert&lt;B.rank()&gt;) * B(ra::insert&lt;A.rank()&gt;, ra::dots&lt;&gt;)) &lt;&lt; endl; // default dots&lt;&gt;
cout &lt;&lt; (A * B(ra::insert&lt;A.rank()&gt;)) &lt;&lt; endl; // index elision + prefix matching
</pre></div>

<ul class="mini-toc">
<li><a href="#Subscripting-and-rank_002d0-views" accesskey="1">Subscripting and rank-0 views</a></li>
</ul>
<div class="subsection-level-extent" id="Subscripting-and-rank_002d0-views">
<h4 class="subsection">2.6.1 Subscripting and rank-0 views</h4>

<a class="index-entry-id" id="index-view_002c-rank-0"></a>
<a class="index-entry-id" id="index-rank_002c-runtime"></a>
<a class="index-entry-id" id="index-rank_002c-compile_002dtime"></a>
<p>When the result of the subscripting operation would have rank 0, the type returned is the type of the view <em class="emph">element</em> and not a rank-0 view as long as the rank of the result can be determined at compile time. When that&rsquo;s not possible (for instance, the subscripted view has rt rank) then a rank-0 view is returned instead. An automatic conversion is defined for rank-0 views, but manual conversion may be needed in some contexts.
</p>
<div class="example">
<pre class="verbatim">using T = std::complex&lt;double&gt;;
int f(T &amp;);
Big&lt;T, 2&gt; a({2, 3}, 0); // ct rank
Big&lt;T&gt; b({2, 3}, 0); // rt rank

cout &lt;&lt; a(0, 0).real_part() &lt;&lt; endl; // ok, a(0, 0) returns complex &amp;
// cout &lt;&lt; b(0, 0).real_part() &lt;&lt; endl; // error, View&lt;T&gt; has no member real_part
cout &lt;&lt; ((T &amp;)(b(0, 0))).real_part() &lt;&lt; endl; // ok, manual conversion to T &amp;

cout &lt;&lt; f(b(0, 0)) &lt;&lt; endl; // ok, automatic conversion from View&lt;T&gt; to T &amp;
// cout &lt;&lt; f(a(0)) &lt;&lt; endl; // compile time error, conversion failed since ct rank of a(0) is not 0
// cout &lt;&lt; f(b(0)) &lt;&lt; endl; // runtime error, conversion failed since rt rank of b(0) is not 0
</pre></div>


<hr>
</div>
</div>
<div class="section-level-extent" id="Special-objects">
<div class="nav-panel">
<p>
Next: <a href="#The-rank-conjunction" accesskey="n" rel="next">The rank conjunction</a>, Previous: <a href="#Slicing" accesskey="p" rel="prev">Slicing</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Special-objects-1">2.7 Special objects</h3>

<dl class="first-deffn">
<dt class="deffn" id="index-TensorIndex_003cn_002c"><span class="category-def">Special&nbsp;object<!-- /@w -->: </span><span><strong class="def-name">TensorIndex&lt;n,</strong> <var class="def-var-arguments">integer_type=ra::dim_t&gt;</var><a class="copiable-link" href='#index-TensorIndex_003cn_002c'> &para;</a></span></dt>
<dd><p><code class="code">TensorIndex&lt;n&gt;</code> represents the <code class="code">n</code>-th index of an array expression. <code class="code">TensorIndex&lt;n&gt;</code> is itself an array expression of rank <code class="code">n</code>-1 and length undefined. It must be used with other terms whose dimensions are defined, so that the overall shape of the array expression can be determined.
</p>
<p><code class="code">ra::</code> offers the shortcut <code class="code">ra::_0</code> for <code class="code">ra::TensorIndex&lt;0&gt;{}</code>, etc.
</p></dd></dl>

<div class="example">
<pre class="verbatim">ra::Big&lt;int, 1&gt; v = {1, 2, 3};
cout &lt;&lt; (v - ra::_0) &lt;&lt; endl; // { 1-0, 2-1, 3-2 }
// cout &lt;&lt; (ra::_0) &lt;&lt; endl; // error: TensorIndex cannot drive array expression
// cout &lt;&lt; (v - ra::_1) &lt;&lt; endl; // error: TensorIndex cannot drive array expression
ra::Big&lt;int, 2&gt; a({3, 2}, 0);
cout &lt;&lt; (a + ra::_0 - ra::_1) &lt;&lt; endl; // {{0, -1, -2}, {1, 0, -1}, {2, 1, 0}}
</pre></div>


<hr>
</div>
<div class="section-level-extent" id="The-rank-conjunction">
<div class="nav-panel">
<p>
Next: <a href="#Compatibility" accesskey="n" rel="next">Compatibility</a>, Previous: <a href="#Special-objects" accesskey="p" rel="prev">Special objects</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="The-rank-conjunction-1">2.8 The rank conjunction</h3>

<p>We have seen in <a class="ref" href="#Cell-iteration">Cell iteration</a> that it is possible to treat an r-array as an array of lower rank with subarrays as its elements. With the <a class="ref" href="#x_002diter"><code class="code">iter&lt;cell rank&gt;</code></a> construction, this ‘exploding’ is performed (notionally) on the argument; the operation of the array expression is applied blindly to these cells, whatever they turn out to be.
</p>
<div class="example">
<pre class="verbatim">for_each(my_sort, iter&lt;1&gt;(A)); // (in ra::) my_sort is a regular function, cell rank must be given
for_each(my_sort, iter&lt;0&gt;(A)); // (in ra::) error, bad cell rank
</pre></div>

<p>The array language J has instead the concept of <em class="dfn">verb rank</em>. Every function (or <em class="dfn">verb</em>) has an associated cell rank for each of its arguments. Therefore <code class="code">iter&lt;cell rank&gt;</code> is not needed.
</p>
<div class="example">
<pre class="verbatim">for_each(sort_rows, A); // (not in ra::) will iterate over 1-cells of A, sort_rows knows
</pre></div>

<p><code class="code">ra::</code> doesn&rsquo;t have ‘verb ranks’ yet. In practice one can think of <code class="code">ra::</code>&rsquo;s operations as having a verb rank of 0. However, <code class="code">ra::</code> supports a limited form of J&rsquo;s <em class="dfn">rank conjunction</em> with the function <a class="ref" href="#x_002dwrank"><code class="code">wrank</code></a>.
</p>
<p>This is an operator that takes one verb (such operators are known as <em class="dfn">adverbs</em> in J) and produces another verb with different ranks. These ranks are used for rank extension through prefix agreement, but then the original verb is used on the cells that result. The rank conjunction can be nested, and this allows repeated rank extension before the innermost operation is applied.
</p>
<p>A standard example is ‘outer product’.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 1&gt; a = {1, 2, 3};
ra::Big&lt;int, 1&gt; b = {40, 50};
ra::Big&lt;int, 2&gt; axb = map(ra::wrank&lt;0, 1&gt;([](auto &amp;&amp; a, auto &amp;&amp; b) { return a*b; }),
                            a, b)
</pre><pre class="example-preformatted">&rArr; axb = {{40, 80, 120}, {50, 100, 150}}
</pre></div>

<p>It works like this. The verb <code class="code">ra::wrank&lt;0, 1&gt;([](auto &amp;&amp; a, auto &amp;&amp; b) { return a*b; })</code> has verb ranks (0, 1), so the 0-cells of <code class="code">a</code> are paired with the 1-cells of <code class="code">b</code>. In this case <code class="code">b</code> has a single 1-cell. The frames and the cell shapes of each operand are:
</p>
<div class="example">
<pre class="verbatim">a: 3 |
b:   | 2
</pre></div>

<p>Now the frames are rank-extended through prefix agreement.
</p>
<div class="example">
<pre class="verbatim">a: 3 |
b: 3 | 2
</pre></div>

<p>Now we need to perform the operation on each cell. The verb <code class="code">[](auto &amp;&amp; a, auto &amp;&amp; b) { return a*b; }</code> has verb ranks (0, 0). This results in the 0-cells of <code class="code">a</code> (which have shape ()) being rank-extended to the shape of the 1-cells of <code class="code">b</code> (which is (2)).
</p>
<div class="example">
<pre class="verbatim">a: 3 | 2
b: 3 | 2
</pre></div>

<p>This use of the rank conjunction is packaged in <code class="code">ra::</code> as the <a class="ref" href="#x_002dfrom"><code class="code">from</code></a> operator. It supports any number of arguments, not only two.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 1&gt; a = {1, 2, 3};
ra::Big&lt;int, 1&gt; b = {40, 50};
ra::Big&lt;int, 2&gt; axb = from([](auto &amp;&amp; a, auto &amp;&amp; b) { return a*b; }), a, b)
</pre><pre class="example-preformatted">&rArr; axb = {{40, 80, 120}, {50, 100, 150}}
</pre></div>

<p>Another example is matrix multiplication. For 2-array arguments C, A and B with shapes C: (m, n) A: (m, p) and B: (p, n), we want to perform the operation C(i, j) += A(i, k)*B(k, j). The axis alignment gives us the ranks we need to use.
</p>
<div class="example">
<pre class="verbatim">C: m |   | n
A: m | p |
B:   | p | n
</pre></div>

<p>First we&rsquo;ll align the first axes of C and A using the cell ranks (1, 1, 2). The cell shapes are:
</p>
<div class="example">
<pre class="verbatim">C: m | n
A: m | p
B:   | p n
</pre></div>

<p>Then we&rsquo;ll use the ranks (1, 0, 1) on the cells:
</p>
<div class="example">
<pre class="verbatim">C: m |   | n
A: m | p |
B:   | p | n
</pre></div>

<p>The final operation is a standard operation on arrays of scalars. In actual <code class="code">ra::</code> syntax:
</p>
<div class="example">
<pre class="verbatim">ra::Big A({3, 2}, {1, 2, 3, 4, 5, 6});
ra::Big B({2, 3}, {7, 8, 9, 10, 11, 12});
ra::Big C({3, 3}, 0.);
for_each(ra::wrank&lt;1, 1, 2&gt;(ra::wrank&lt;1, 0, 1&gt;([](auto &amp;&amp; c, auto &amp;&amp; a, auto &amp;&amp; b) { c += a*b; })), C, A, B);
</pre><pre class="example-preformatted">&rArr; C = {{27, 30, 33}, {61, 68, 75}, {95, 106, 117}}
</pre></div>

<p>Note that <code class="code">wrank</code> cannot be used to transpose axes in general.
</p>
<p>I hope that in the future something like <code class="code">C(i, j) += A(i, k)*B(k, j)</code>, where <code class="code">i, j, k</code> are special objects, can be automatically translated to the requisite combination of <code class="code">wrank</code> and perhaps also <a class="ref" href="#x_002dtranspose"><code class="code">transpose</code></a>. For the time being, you have to align or transpose the axes yourself.
</p>
<hr>
</div>
<div class="section-level-extent" id="Compatibility">
<div class="nav-panel">
<p>
Next: <a href="#Extension" accesskey="n" rel="next">Extension</a>, Previous: <a href="#The-rank-conjunction" accesskey="p" rel="prev">The rank conjunction</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Compatibility-1">2.9 Compatibility</h3>

<ul class="mini-toc">
<li><a href="#Using-other-C-and-C_002b_002b-types-with-ra_003a_003a" accesskey="1">Using other C and C++ types with <code class="code">ra::</code></a></li>
<li><a href="#Using-ra_003a_003a-types-with-the-STL" accesskey="2">Using <code class="code">ra::</code> types with the STL</a></li>
<li><a href="#Using-ra_003a_003a-types-with-other-libraries" accesskey="3">Using <code class="code">ra::</code> types with other libraries</a></li>
</ul>
<div class="subsection-level-extent" id="Using-other-C-and-C_002b_002b-types-with-ra_003a_003a">
<h4 class="subsection">2.9.1 Using other C and C++ types with <code class="code">ra::</code></h4>

<a class="index-entry-id" id="index-foreign-type"></a>
<p><code class="code">ra::</code> accepts certain types from outside <code class="code">ra::</code> (<em class="dfn">foreign types</em>) as array expressions. Generally it is enough to mix the foreign type with a type from <code class="code">ra::</code> and let deduction work.
</p>
<div class="example">
<pre class="verbatim">std::vector&lt;int&gt; x = {1, 2, 3};
ra::Small&lt;int, 3&gt; y = {6, 5, 4};
cout &lt;&lt; (x-y) &lt;&lt; endl;
</pre><pre class="example-preformatted">-| -5 -3 -1
</pre></div>

<a class="index-entry-id" id="index-start"></a>
<p>Foreign types can be brought into <code class="code">ra::</code> explicitly with the function <a class="ref" href="#x_002dstart"><code class="code">start</code></a>.
</p>
<div class="example">
<pre class="verbatim">std::vector&lt;int&gt; x = {1, 2, 3};
// cout &lt;&lt; sum(x) &lt;&lt; endl; // error, sum not found
cout &lt;&lt; sum(ra::start(x)) &lt;&lt; endl;
cout &lt;&lt; ra::sum(x) &lt;&lt; endl;
</pre><pre class="example-preformatted">-| 6
</pre></div>

<p>The following types are accepted as foreign types:
</p>
<ul class="itemize mark-bullet">
<li>Built-in arrays <a class="index-entry-id" id="index-built_002din-array"></a>
produce an expression of positive rank and ct size.
</li><li><code class="code">std::array</code>
produces an expression of rank 1 and ct size.
</li><li>Other types conforming to <code class="code">std::ranges::random_access_range</code>, including <code class="code">std::vector</code>, <code class="code">std::string</code>, etc.
produce an expression of rank 1 and rt size.
</li></ul>

<p>Raw pointers must be brought into <code class="code">ra::</code> explicitly using the function <a class="ref" href="#x_002dptr"><code class="code">ptr</code></a>, which produces an expression of rank 1 and <em class="emph">undefined</em> size.
</p>
<p>Compare:
</p>
<div class="example">
<pre class="verbatim">int p[] = {1, 2, 3};
int * z = p;
ra::Big&lt;int, 1&gt; q {1, 2, 3};
q += p; // ok, q is ra::, p is foreign object with shape info
ra::start(p) += q; // can't redefine operator+=(int[]), foreign needs ra::start()
// z += q; // error: raw pointer needs ra::ptr()
ra::ptr(z) += p; // ok, shape is determined by foreign object p
</pre></div>

<a class="anchor" id="x_002dis_002dscalar"></a><p>Some types are accepted automatically as scalars. These include:
</p><ul class="itemize mark-bullet">
<li>Any type <code class="code">T</code> for which <code class="code">std::is_scalar_v&lt;T&gt;</code> is true, <em class="emph">except</em> pointers. These include <code class="code">char</code>, <code class="code">int</code>, <code class="code">double</code>, etc.
</li><li><code class="code">std::complex&lt;T&gt;</code>, if you import <code class="code">ra/complex.hh</code>.
</li></ul>

<p>You can add your own types as scalar types with the following declaration (see <code class="code">ra/complex.hh</code>):
</p>
<pre class="verbatim">    namespace ra { template &lt;&gt; constexpr bool is_scalar_def&lt;MYTYPE&gt; = true; }
</pre>
<p>Otherwise, you can bring a scalar object into <code class="code">ra::</code> on the spot, with the function <a class="ref" href="#x_002dscalar"><code class="code">scalar</code></a>.
</p>
</div>
<div class="subsection-level-extent" id="Using-ra_003a_003a-types-with-the-STL">
<h4 class="subsection">2.9.2 Using <code class="code">ra::</code> types with the STL</h4>

<p>General <code class="code">ra::</code> <a class="ref" href="#Containers-and-views">views</a> provide STL compatible <code class="code">ForwardIterator</code>s through the members <code class="code">begin()</code> and <code class="code">end()</code>. These iterators traverse the elements of the array (0-cells) in row major order, regardless of the storage order of the view.
</p>
<p>For <a class="ref" href="#Containers-and-views">containers</a> <code class="code">begin()</code> provides <code class="code">RandomAccessIterator</code>s, which is handy for certain functions such as <code class="code">sort</code>. There&rsquo;s no reason why all views couldn&rsquo;t provide <code class="code">RandomAccessIterator</code>, but these wouldn&rsquo;t be efficient for ranks above 1, and I haven&rsquo;t implemented them. The container <code class="code">RandomAccessIterator</code>s that are provided are in fact raw pointers.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int&gt; x {3, 2, 1}; // x is a Container
auto y = x(); // y is a View on x
// std::sort(y.begin(), y.end()); // error: y.begin() is not RandomAccessIterator
std::sort(x.begin(), x.end()); // ok, we know x is stored in row-major order
</pre><pre class="example-preformatted">&rArr; x = {1, 2, 3}
</pre></div>

<a class="index-entry-id" id="index-other-libraries_002c-interfacing-with"></a>
</div>
<div class="subsection-level-extent" id="Using-ra_003a_003a-types-with-other-libraries">
<h4 class="subsection">2.9.3 Using <code class="code">ra::</code> types with other libraries</h4>

<p>When you have to pass arrays back and forth between your program and an external library, perhaps even another language, it is necessary for both sides to agree on memory layout. <code class="code">ra::</code> gives you access to its own memory layout and allows you to obtain an <code class="code">ra::</code> view on any type of memory.
</p>
<ul class="mini-toc">
<li><a href="#The-good-array-citizen" accesskey="1">The good array citizen</a></li>
<li><a href="#The-bad-array-citizen" accesskey="2">The bad array citizen</a></li>
</ul>
<div class="subsubsection-level-extent" id="The-good-array-citizen">
<h4 class="subsubsection">2.9.3.1 The good array citizen</h4>


<a class="index-entry-id" id="index-BLIS"></a>
<p>The good array citizen describes its arrays with the same parameters as <code class="code">ra::</code>: a pointer, plus a length and a step per dimension. You don&rsquo;t have to worry about special cases. Say <a class="url" href="https://github.com/flame/blis">BLIS</a>:
</p>
<blockquote class="quotation">
<pre class="verbatim">#include &lt;blis.h&gt;

ra::Big&lt;double, 2&gt; A({M, K}, ...);
ra::Big&lt;double, 2&gt; B({K, N}, ...);
ra::Big&lt;double, 2&gt; C({M, N}, ...);
double alpha = ...;
double beta = ...;

// C := βC + αAB
bli_dgemm(BLIS_NO_TRANSPOSE, BLIS_NO_TRANSPOSE, M, N, K, &amp;alpha,
          A.data(), A.step(0), A.step(1),
          B.data(), B.step(0), B.step(1),
          &amp;beta, C.data(), C.step(0), C.step(1));
</pre></blockquote>

<a class="index-entry-id" id="index-FFTW"></a>
<p>Another good array citizen, <a class="url" href="http://fftw.org">FFTW</a> handles arbitrary rank:
</p>
<blockquote class="quotation">
<pre class="verbatim">#include &lt;fftw3.h&gt;

...

using complex = std::complex&lt;double&gt;;
static_assert(sizeof(complex)==sizeof(fftw_complex));

// forward DFT over the last r axes of a -&gt; b
void fftw(int r, ra::View&lt;complex&gt; const a, ra::View&lt;complex&gt; b)
{
    int const rank = a.rank();
    assert(r&gt;0 &amp;&amp; r&lt;=rank);
    assert(every(shape(a)==shape(b)));
    fftw_iodim dims[r];
    fftw_iodim howmany_dims[rank-r];
    for (int i=0; i!=rank; ++i) {
        if (i&gt;=rank-r) {
            dims[i-rank+r].n = a.len(i);
            dims[i-rank+r].is = a.step(i);
            dims[i-rank+r].os = b.step(i);
        } else {
            howmany_dims[i].n = a.len(i);
            howmany_dims[i].is = a.step(i);
            howmany_dims[i].os = b.step(i);
        }
    }
    fftw_plan p;
    p = fftw_plan_guru_dft(r, dims, rank-r, howmany_dims,
                           (fftw_complex *)(a.data()), (fftw_complex *)(b.data()),
                           FFTW_FORWARD, FFTW_ESTIMATE);
    fftw_execute(p);
    fftw_destroy_plan(p);
}
</pre></blockquote>

<a class="index-entry-id" id="index-Guile"></a>
<p>Translating array descriptors from a foreign language should be fairly simple. For example, this is how to convert a <a class="url" href="https://www.gnu.org/software/guile/manual/html_node/Accessing-Arrays-from-C.html#Accessing-Arrays-from-C">Guile</a> array view into an <code class="code">ra::</code> view:
</p>
<blockquote class="quotation">
<pre class="verbatim">    SCM a; // say a is #nf64(...)

    ...

    scm_t_array_handle h;
    scm_array_get_handle(a, &amp;h);
    scm_t_array_dim const * dims = scm_array_handle_dims(&amp;h);
    View&lt;double&gt; v(map([](int i) { return ra::Dim { dims[i].ubnd-dims[i].lbnd+1, dims[i].inc }; },
                       ra::iota(scm_array_handle_rank(&amp;h))),
                   scm_array_handle_f64_writable_elements(&amp;h));

    ...

    scm_array_handle_release(&amp;h);
</pre></blockquote>

<a class="index-entry-id" id="index-Numpy-2"></a>
<a class="index-entry-id" id="index-Python"></a>
<p>Numpy&rsquo;s C API has the type <a class="url" href="https://docs.scipy.org/doc/numpy/reference/c-api.array.html"><code class="code">PyArrayObject</code></a> which can be used in the same way as Guile&rsquo;s <code class="code">scm_t_array_handle</code> in the example above.
</p>
<p>It is usually simpler to let the foreign language handle the memory, even though there should be ways to transfer ownership (e.g. Guile has <a class="url" href="https://www.gnu.org/software/guile/manual/html_node/SRFI_002d4-API.html#index-scm_005ftake_005ff64vector"><code class="code">scm_take_xxx</code></a>).
</p>
</div>
<div class="subsubsection-level-extent" id="The-bad-array-citizen">
<h4 class="subsubsection">2.9.3.2 The bad array citizen</h4>

<p>Unfortunately there are many libraries that don&rsquo;t accept arbitrary array parameters, or that do strange things with particular values of lengths and/or steps.
</p>
<p>The most common case is that a library doesn&rsquo;t handle steps at all, and it only accepts unit step for rank 1 arrays, or packed row-major or column-major storage for higher rank arrays. In that case, you might be forced to copy your array before passing it along.
</p>

<p>Other libraries do accept steps, but not arbitrary ones. For example <a class="url" href="https://www.netlib.org/blas">https://www.netlib.org/blas</a>&rsquo; <code class="code">cblas_dgemm</code> has this prototype:
</p>
<blockquote class="quotation">
<pre class="verbatim">cblas_dgemm(order, transA, transB, m, n, k, alpha, A, lda, B, ldb, beta, C, ldc);
</pre></blockquote>

<p><code class="code">A</code>, <code class="code">B</code>, <code class="code">C</code> are (pointers to) 2-arrays, but the routine accepts only one step argument for each (<code class="code">lda</code>, etc.). CBLAS also doesn&rsquo;t understand <code class="code">lda</code> as a arbitrary step, but rather as the dimension of a larger array that you&rsquo;re slicing <code class="code">A</code> from, and some implementations will mishandle negative or zero <code class="code">lda</code>.
</p>
<p>Sometimes you can work around this by fiddling with <code class="code">transA</code> and <code class="code">transB</code>, but in general you need to check your array parameters and you may need to make copies.
</p>
<a class="index-entry-id" id="index-OpenGL"></a>
<p>OpenGL is another library that requires <a class="url" href="https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glVertexAttribPointer.xhtml">contortions:</a>
</p>
<blockquote class="quotation">
<pre class="verbatim">void glVertexAttribPointer(GLuint index,
                           GLint size,
                           GLenum type,
                           GLboolean normalized,
                           GLsizei step,
                           const GLvoid * pointer);
</pre>
<p>[...]
</p>
<p><em class="emph">step</em>
</p>
<blockquote class="quotation">
<p>Specifies the byte offset between consecutive generic vertex attributes. If step is 0, the generic vertex attributes are understood to be tightly packed in the array. The initial value is 0.
    </p></blockquote>
</blockquote>

<p>It isn&rsquo;t clear whether negative steps are legal, either. So just as with CBLAS, passing arbitrary array views may require copies.
</p>
<hr>
</div>
</div>
</div>
<div class="section-level-extent" id="Extension">
<div class="nav-panel">
<p>
Next: <a href="#Functions" accesskey="n" rel="next">Functions</a>, Previous: <a href="#Compatibility" accesskey="p" rel="prev">Compatibility</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Extension-1">2.10 Extension</h3>

<ul class="mini-toc">
<li><a href="#New-scalar-types" accesskey="1">New scalar types</a></li>
<li><a href="#New-array-operations" accesskey="2">New array operations</a></li>
</ul>
<div class="subsection-level-extent" id="New-scalar-types">
<h4 class="subsection">2.10.1 New scalar types</h4>

<p><code class="code">ra::</code> will let you construct arrays of arbitrary types out of the box. This is the same functionality you get with e.g. <code class="code">std::vector</code>.
</p>
<div class="example">
<pre class="verbatim">struct W { int x; }
ra::Big&lt;W, 2&gt; w = {{ {4}, {2} }, { {1}, {3} }};
cout &lt;&lt; W(1, 1).x &lt;&lt; endl;
cout &lt;&lt; amin(map([](auto &amp;&amp; x) { return w.x; }, w)) &lt;&lt; endl;
</pre><pre class="example-preformatted">-| 3
   1
</pre></div>

<p>However, if you want to mix arbitrary types in array operations, you&rsquo;ll need to tell <code class="code">ra::</code> that that is actually what you want. This is to avoid conflicts with other libraries.
</p>
<div class="example">
<pre class="verbatim">namespace ra { template &lt;&gt; constexpr bool is_scalar_def&lt;W&gt; = true; }
...
W ww {11};
for_each([](auto &amp;&amp; x, auto &amp;&amp; y) { cout &lt;&lt; (x.x + y.y) &lt;&lt; &quot; &quot;; }, w, ww); // ok
</pre><pre class="example-preformatted">-| 15 13 12 14
</pre></div>

<p>but
</p>
<div class="example">
<pre class="verbatim">struct U { int x; }
U uu {11};
for_each([](auto &amp;&amp; x, auto &amp;&amp; y) { cout &lt;&lt; (x.x + y.y) &lt;&lt; &quot; &quot;; }, w, uu); // error: can't find ra::start(U)
</pre></div>

<a class="anchor" id="x_002dnew_002darray_002doperations"></a></div>
<div class="subsection-level-extent" id="New-array-operations">
<h4 class="subsection">2.10.2 New array operations</h4>

<p><code class="code">ra::</code> provides array extensions for standard operations such as <code class="code">+</code>, <code class="code">*</code>, <code class="code">cos</code> <a class="ref" href="#x_002dscalar_002dops">and so on</a>. You can add array extensions for your own operations in the obvious way, with <a class="ref" href="#x_002dmap"><code class="code">map</code></a> (but note the namespace qualifiers):
</p>
<div class="example">
<pre class="verbatim">return_type my_fun(...) { };
...
namespace ra {
template &lt;class ... A&gt; inline auto
my_fun(A &amp;&amp; ... a)
{
    return map(::my_fun, std::forward&lt;A&gt;(a) ...);
}
} // namespace ra
</pre></div>

<a class="index-entry-id" id="index-Blitz_002b_002b-2"></a>
<p>If you compare this with what Blitz++ had to do, modern C++ sure has made our lives easier.
</p>
<a class="index-entry-id" id="index-overload-set"></a>
<p>If <code class="code">my_fun</code> is an overload set, you can use<a class="footnote" id="DOCF12" href="#FOOT12"><sup>12</sup></a>
</p>
<div class="example">
<pre class="verbatim">namespace ra {
template &lt;class ... A&gt; inline auto
my_fun(A &amp;&amp; ... a)
{
    return map([](auto &amp;&amp; ... a) { return ::my_fun(a ...); }, std::forward&lt;A&gt;(a) ...);
}
} // namespace ra
</pre></div>

<hr>
</div>
</div>
<div class="section-level-extent" id="Functions">
<div class="nav-panel">
<p>
Next: <a href="#Error-handling" accesskey="n" rel="next">Error handling</a>, Previous: <a href="#Extension" accesskey="p" rel="prev">Extension</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Functions-1">2.11 Functions</h3>

<p>You don&rsquo;t need to use <a class="ref" href="#Array-operations"><code class="code">map</code></a> every time you want to do something with arrays in <code class="code">ra::</code>. A number of array functions are already defined.
</p>
<a class="anchor" id="x_002dscalar_002dops"></a><ul class="mini-toc">
<li><a href="#Standard-scalar-operations" accesskey="1">Standard scalar operations</a></li>
<li><a href="#Conditional-operations" accesskey="2">Conditional operations</a></li>
<li><a href="#Special-operations" accesskey="3">Special operations</a></li>
<li><a href="#Elementwise-reductions" accesskey="4">Elementwise reductions</a></li>
<li><a href="#Special-reductions" accesskey="5">Special reductions</a></li>
<li><a href="#Shortcut-reductions" accesskey="6">Shortcut reductions</a></li>
</ul>
<div class="subsection-level-extent" id="Standard-scalar-operations">
<h4 class="subsection">2.11.1 Standard scalar operations</h4>

<p><code class="code">ra::</code> defines array extensions for <code class="code">+</code>, <code class="code">-</code> (both unary and binary), <code class="code">*</code>, <code class="code">/</code>, <code class="code">!</code>, <code class="code">&amp;&amp;</code>, <code class="code">||</code><a class="footnote" id="DOCF13" href="#FOOT13"><sup>13</sup></a>, <code class="code">&gt;</code>, <code class="code">&lt;</code>, <code class="code">&gt;=</code>, <code class="code">&lt;=</code>, <code class="code">&lt;=&gt;</code>, <code class="code">==</code>, <code class="code">!=</code>, <code class="code">pow</code>, <code class="code">sqr</code>, <code class="code">abs</code>, <code class="code">cos</code>, <code class="code">sin</code>, <code class="code">exp</code>, <code class="code">expm1</code>, <code class="code">sqrt</code>, <code class="code">log</code>, <code class="code">log1p</code>, <code class="code">log10</code>, <code class="code">isfinite</code>, <code class="code">isnan</code>, <code class="code">isinf</code>, <code class="code">max</code>, <code class="code">min</code>, <code class="code">asin</code>, <code class="code">acos</code>, <code class="code">atan</code>, <code class="code">atan2</code>, <code class="code">cosh</code>, <code class="code">sinh</code>, <code class="code">tanh</code>, and <code class="code">lerp</code>.
Extending other scalar operations is straightforward; see <a class="ref" href="#x_002dnew_002darray_002doperations">New array operations</a>. <code class="code">ra::</code> also defines (and extends) the non-standard functions <code class="code">odd</code>, <a class="ref" href="#x_002dsqr"><code class="code">sqr</code></a>, <a class="ref" href="#x_002dsqrm"><code class="code">sqrm</code></a>, <a class="ref" href="#x_002dconj"><code class="code">conj</code></a>, <a class="ref" href="#x_002drel_002derror"><code class="code">rel_error</code></a>, and <a class="ref" href="#x_002dxI"><code class="code">xI</code></a>.
</p>
<p>For example:
</p><div class="example">
<pre class="verbatim">cout &lt;&lt; exp(ra::Small&lt;double, 3&gt; {4, 5, 6}) &lt;&lt; endl;
</pre><pre class="example-preformatted">  -| 54.5982 148.413 403.429
</pre></div>

</div>
<div class="subsection-level-extent" id="Conditional-operations">
<h4 class="subsection">2.11.2 Conditional operations</h4>

<p><a class="ref" href="#x_002dmap"><code class="code">map</code></a> evaluates all of its arguments before passing them along to its operator. This isn&rsquo;t always what you want. The simplest example is <code class="code">where(condition, iftrue, iffalse)</code>, which returns an expression that will evaluate <code class="code">iftrue</code> when <code class="code">condition</code> is true and <code class="code">iffalse</code> otherwise.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double&gt; x ...
ra::Big&lt;double&gt; y = where(x&gt;0, expensive_expr_1(x), expensive_expr_2(x));
</pre></div>

<p>Here <code class="code">expensive_expr_1</code> and <code class="code">expensive_expr_2</code> are array expressions. So the computation of the other arm would be wasted if one were to do instead
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;double&gt; y = map([](auto &amp;&amp; w, auto &amp;&amp; t, auto &amp;&amp; f) -&gt; decltype(auto) { return w ? t : f; }
                        x&gt;0, expensive_expr_1(x), expensive_function_2(x));
</pre></div>

<p>If the expressions have side effects, then <code class="code">map</code> won&rsquo;t even give the right result.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 1&gt; o = {};
ra::Big&lt;int, 1&gt; e = {};
ra::Big&lt;int, 1&gt; n = {1, 2, 7, 9, 12};
ply(where(odd(n), map([&amp;o](auto &amp;&amp; x) { o.push_back(x); }, n), map([&amp;e](auto &amp;&amp; x) { e.push_back(x); }, n)));
cout &lt;&lt; &quot;o: &quot; &lt;&lt; ra::noshape &lt;&lt; o &lt;&lt; &quot;, e: &quot; &lt;&lt; ra::noshape &lt;&lt; e &lt;&lt; endl;
</pre><pre class="example-preformatted">-| o: 1 7 9, e: 2 12
</pre></div>

<p>FIXME Artificial example.
FIXME Do we want to expose ply(); this is the only example in the manual that uses it.
</p>
<p>When the choice is between more than two expressions, there&rsquo;s <a class="ref" href="#x_002dpick"><code class="code">pick</code></a>, which operates similarly, but accepts an integer instead of a boolean selector.
</p>
</div>
<div class="subsection-level-extent" id="Special-operations">
<h4 class="subsection">2.11.3 Special operations</h4>

<p>Some operations are essentially scalar operations, but require special syntax and would need a lambda wrapper to be used with <code class="code">map</code>. <code class="code">ra::</code> comes with a few of these already defined.
</p>
<p>FIXME
</p>
</div>
<div class="subsection-level-extent" id="Elementwise-reductions">
<h4 class="subsection">2.11.4 Elementwise reductions</h4>

<p><code class="code">ra::</code> defines the whole-array one-argument reductions <code class="code">any</code>, <code class="code">every</code>, <code class="code">amax</code>, <code class="code">amin</code>, <code class="code">sum</code>, <code class="code">prod</code> and the two-argument reductions <code class="code">dot</code> and <code class="code">cdot</code>. Note that <code class="code">max</code> and <code class="code">min</code> are two-argument scalar operations with array extensions, while <code class="code">amax</code> and <code class="code">amin</code> are reductions. <code class="code">any</code> and <code class="code">every</code> are short-circuiting.
</p>
<p>You can define reductions the same way <code class="code">ra::</code> does:
</p>
<div class="example">
<pre class="verbatim">template &lt;class A&gt;
inline auto op_reduce(A &amp;&amp; a)
{
    T c = op_default;
    for_each([&amp;c](auto &amp;&amp; a) { c = op(c, a); }, a);
    return c;
}
</pre></div>

<p>Often enough you need to reduce over particular axes. This is possible by combining assignment operators with the <a class="ref" href="#Rank-extension">rank extension</a> mechanism, or using the <a class="ref" href="#The-rank-conjunction">rank conjunction</a>, or iterating over <a class="ref" href="#Cell-iteration">cells of higher rank</a>. For example:
</p>
<div class="example">
<pre class="verbatim">    ra::Big&lt;double, 2&gt; a({m, n}, ...);

    ra::Big&lt;double, 1&gt; sum_rows({n}, 0.);
    iter&lt;1&gt;(sum_rows) += iter&lt;1&gt;(a);
    // for_each(ra::wrank&lt;1, 1&gt;([](auto &amp; c, auto &amp;&amp; a) { c += a; }), sum_rows, a) // alternative
    // sum_rows += transpose&lt;1, 0&gt;(a); // another

    ra::Big&lt;double, 1&gt; sum_cols({m}, 0.);
    sum_cols += a;
</pre></div>

<p>FIXME example with assignment op
</p>
<p>A few common operations of this type are already packaged in <code class="code">ra::</code>.
</p>
</div>
<div class="subsection-level-extent" id="Special-reductions">
<h4 class="subsection">2.11.5 Special reductions</h4>

<p><code class="code">ra::</code> defines the following special reductions.
</p>
<p>FIXME
</p>
</div>
<div class="subsection-level-extent" id="Shortcut-reductions">
<h4 class="subsection">2.11.6 Shortcut reductions</h4>

<p>Some reductions do not need to traverse the whole array if a certain condition is encountered early. The most obvious ones are the reductions of <code class="code">&amp;&amp;</code> and <code class="code">||</code>, which <code class="code">ra::</code> defines as <code class="code">every</code> and <code class="code">any</code>.
</p>
<p>FIXME
</p>
<p>These operations are defined on top of another function <code class="code">early</code>.
</p>
<p>FIXME early
</p>
<p>The following is often useful.
</p>
<p>FIXME lexicographical compare etc.
</p>
<a class="index-entry-id" id="index-error"></a>
<a class="index-entry-id" id="index-assert"></a>
<hr>
</div>
</div>
<div class="section-level-extent" id="Error-handling">
<div class="nav-panel">
<p>
Previous: <a href="#Functions" accesskey="p" rel="prev">Functions</a>, Up: <a href="#Usage" accesskey="u" rel="up">Usage</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Error-handling-1">2.12 Error handling</h3>

<p>Error handling in <code class="code">ra::</code> is controlled by two macros:
</p>
<ul class="itemize mark-bullet">
<li><code class="code">RA_DO_CHECK</code>
is a binary flag that controls runtime checks. The default is 1 which means to check for errors. 0 means not to check. The checks themselves are done with <code class="code">RA_ASSERT</code>.
</li><li><code class="code">RA_ASSERT(cond, ...)</code>
is a function-like macro. <code class="code">cond</code> is an expression that evaluates to true (in the <code class="code">ra::</code> namespace) if the check passes. The other arguments are informative and do not need to be used. The default defintion of <code class="code">RA_ASSERT(cond, ...)</code> prints those arguments to <code class="code">std::cerr</code> and aborts.
</li></ul>

<p><code class="code">ra::</code> contains uses of <code class="code">assert</code> for checking invariants or for sanity checks that are separate from uses of <code class="code">RA_ASSERT</code>. Those can be disabled in the usual way with <samp class="option">-DNDEBUG</samp>.
</p>
<p>You can redefine <code class="code">RA_ASSERT</code> to something that is more appropriate for your program. <code class="code">examples/throw.cc</code> in the distribution shows how to throw a user-defined exception instead.
</p>
<hr>
</div>
</div>
<div class="chapter-level-extent" id="Extras">
<div class="nav-panel">
<p>
Next: <a href="#Hazards" accesskey="n" rel="next">Hazards</a>, Previous: <a href="#Usage" accesskey="p" rel="prev">Usage</a>, Up: <a href="#Top" accesskey="u" rel="up"><code class="code">ra::</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Extras-1">3 Extras</h2>


<hr>
</div>
<div class="chapter-level-extent" id="Hazards">
<div class="nav-panel">
<p>
Next: <a href="#Internals" accesskey="n" rel="next">Internals</a>, Previous: <a href="#Extras" accesskey="p" rel="prev">Extras</a>, Up: <a href="#Top" accesskey="u" rel="up"><code class="code">ra::</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Hazards-1">4 Hazards</h2>

<p>Some of these issues arise because <code class="code">ra::</code> applies its principles systematically, which can have surprising results. Still others are the result of unfortunate compromises. And a few are just bugs.
</p>
<ul class="mini-toc">
<li><a href="#Reuse-of-expression-objects" accesskey="1">Reuse of expression objects</a></li>
<li><a href="#Assignment-to-views" accesskey="2">Assignment to views</a></li>
<li><a href="#View-of-const-vs-const-view" accesskey="3">View of const vs const view</a></li>
<li><a href="#Rank-extension-in-assignments" accesskey="4">Rank extension in assignments</a></li>
<li><a href="#Performance-pitfalls-of-rank-extension" accesskey="5">Performance pitfalls of rank extension</a></li>
<li><a href="#Chained-assignment" accesskey="6">Chained assignment</a></li>
<li><a href="#Unregistered-scalar-types" accesskey="7">Unregistered scalar types</a></li>
</ul>
<div class="section-level-extent" id="Reuse-of-expression-objects">
<h3 class="section">4.1 Reuse of expression objects</h3>

<p>Expression objects are meant to be used once. This applies to anything produced with <code class="code">ra::map</code>, <code class="code">ra::iter</code>, <code class="code">ra::start</code>, <code class="code">ra::vector</code>, or <code class="code">ra::ptr</code>. Reuse errors are <em class="emph">not</em> checked. For example:
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 2&gt; B({3, 3}, ra::_1 + ra::_0*3); // {{0 1 2} {3 4 5} {6 7 8}}
std::array&lt;int, 2&gt; l = { 1, 2 };
cout &lt;&lt; B(ra::vector(l), ra::vector(l)) &lt;&lt; endl; // ok =&gt; {{4 5} {7 8}}
auto ll = ra::vector(l);
cout &lt;&lt; B(ll, ll) &lt;&lt; endl; // ?? take cover
</pre></div>

</div>
<div class="section-level-extent" id="Assignment-to-views">
<h3 class="section">4.2 Assignment to views</h3>

<p>FIXME
With rt-shape containers (e.g. <code class="code">Big</code>), <code class="code">operator=</code> replaces the left hand side instead of writing over its contents. This behavior is inconsistent with <code class="code">View::operator=</code> and is there only so that istream <code class="code">&gt;&gt;</code> container may work; do not rely on it.
</p>
</div>
<div class="section-level-extent" id="View-of-const-vs-const-view">
<h3 class="section">4.3 View of const vs const view</h3>


<p>FIXME
Passing view arguments by reference
</p>
</div>
<div class="section-level-extent" id="Rank-extension-in-assignments">
<h3 class="section">4.4 Rank extension in assignments</h3>

<p>Assignment of an expression onto another expression of lower rank may not do what you expect. This example matches <code class="code">a</code> and 3 [both of shape ()] with a vector of shape (3). This is equivalent to <code class="code">{a=3+4; a=3+5; a=3+6;}</code>. You may get a different result depending on traversal order.
</p>
<div class="example">
<pre class="verbatim">int a = 0;
ra::scalar(a) = 3 + ra::Small&lt;int, 3&gt; {4, 5, 6}; // ?
</pre><pre class="example-preformatted">  &rArr; a = 9
</pre></div>

<p>Compare with
</p>
<div class="example">
<pre class="verbatim">int a = 0;
ra::scalar(a) += 3 + ra::Small&lt;int, 3&gt; {4, 5, 6}; // 0 + 3 + 4 + 5 + 6
</pre><pre class="example-preformatted">  &rArr; a = 18
</pre></div>

</div>
<div class="section-level-extent" id="Performance-pitfalls-of-rank-extension">
<h3 class="section">4.5 Performance pitfalls of rank extension</h3>

<p>In the following example where <code class="code">b</code> has its shape extended from (3) to (3, 4), <code class="code">f</code> is called 12 times, even though only 3 calls are needed if <code class="code">f</code> doesn&rsquo;t have side effects. In such cases it might be preferrable to write the outer loop explicitly, or to do some precomputation.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 2&gt; a = {{1, 2, 3, 4}, {5, 6, 7, 8} {9, 10, 11, 12}};
ra::Big&lt;int, 1&gt; b = {1, 2, 3};
ra::Big&lt;int, 2&gt; c = map(f, b) + a;
</pre></div>

</div>
<div class="section-level-extent" id="Chained-assignment">
<h3 class="section">4.6 Chained assignment</h3>

<p>FIXME
When <code class="code">a=b=c</code> works, it operates as <code class="code">b=c; a=b;</code> and not as an array expression.
</p>
</div>
<div class="section-level-extent" id="Unregistered-scalar-types">
<h3 class="section">4.7 Unregistered scalar types</h3>

<p>FIXME
<code class="code">View&lt;T, N&gt; x; x = T()</code> fails if <code class="code">T</code> isn&rsquo;t registered as <code class="code">is_scalar</code>.
</p>
<ol class="enumerate">
<li> Item 0
</li><li> Item 1
</li><li> Item 2
</li></ol>

<hr>
</div>
</div>
<div class="chapter-level-extent" id="Internals">
<div class="nav-panel">
<p>
Next: <a href="#The-future" accesskey="n" rel="next">The future</a>, Previous: <a href="#Hazards" accesskey="p" rel="prev">Hazards</a>, Up: <a href="#Top" accesskey="u" rel="up"><code class="code">ra::</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Internals-1">5 Internals</h2>

<p><code class="code">ra::</code> has two main components: a set of container classes, and the expression template mechanism. The container classes provide leaves for the expression template trees, and the container classes also make some use of the expression template mechanism internally (e.g. in the selection operator, or for initialization).
</p>

<ul class="mini-toc">
<li><a href="#Type-hierarchy" accesskey="1">Type hierarchy</a></li>
<li><a href="#Term-agreement" accesskey="2">Term agreement</a></li>
<li><a href="#Loop-types" accesskey="3">Loop types</a></li>
<li><a href="#Introspection" accesskey="4">Introspection</a></li>
<li><a href="#Compiling-and-running" accesskey="5">Compiling and running</a></li>
</ul>
<hr>
<div class="section-level-extent" id="Type-hierarchy">
<div class="nav-panel">
<p>
Next: <a href="#Term-agreement" accesskey="n" rel="next">Term agreement</a>, Up: <a href="#Internals" accesskey="u" rel="up">Internals</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Type-hierarchy-1">5.1 Type hierarchy</h3>

<p>Some of the categories below are actually C++20 ‘concepts’, some are still informal.
</p>
<ul class="itemize mark-bullet">
<li><b class="b">Container</b> &mdash; <code class="code">Big</code>, <code class="code">Shared</code>, <code class="code">Unique</code>, <code class="code">Small</code>

<p>These are array types that own their data in one way or another. Creating or destroying these objects may allocate or deallocate memory, respectively.
</p>
</li><li><b class="b">View</b> &mdash; <code class="code">View</code>, <code class="code">SmallView</code>

<p>These are array views into data in memory, which may be writable. Any of the <b class="b">Container</b> types can be treated as a <b class="b">View</b>, but one may also create <b class="b">View</b>s that aren&rsquo;t associated with any <b class="b">Container</b>, for example into memory allocated by a different library. Creating and destroying <b class="b">View</b>s doesn&rsquo;t allocate or deallocate memory for array elements.
</p>
</li><li><b class="b">Iterator</b> &mdash; <code class="code">CellBig</code>, <code class="code">CellSmall</code>, <code class="code">Iota</code>, <code class="code">Ptr</code>, <code class="code">Scalar</code>, <code class="code">Expr</code>, <code class="code">Pick</code>

<p>This is a traversable object. <b class="b">Iterator</b>s are accepted by all the array functions such as <code class="code">map</code>, <code class="code">for_each</code>, etc. <code class="code">map</code> produces an <b class="b">Iterator</b> itself, so most array expressions are <b class="b">Iterator</b>s. <b class="b">Iterator</b>s are created from <b class="b">View</b>s and from certain foreign array-like types primarily through the function <code class="code">start</code>. This is done automatically when those types are used in array expressions.
</p>
<p><b class="b">Iterator</b>s provide a <code class="code">flat()</code> method to obtain a linearized view of a section of the array. Together with the methods <code class="code">len()</code>, <code class="code">step()</code>, <code class="code">keep_step()</code> and <code class="code">adv()</code>, a loop involving <b class="b">Iterator</b>s can have its inner loop unfolded and traversed using <b class="b">Flat</b> objects. This is faster than a multidimensional loop, especially if the inner dimensions of the loop are small.
</p>
<p><b class="b">Iterator</b>s also provide an <code class="code">at(i ...)</code> method for random access to any element of the expression.
</p>
</li><li><b class="b">Flat</b> <code class="code">Iota::Flat</code>, <code class="code">Scalar</code>, <code class="code">Expr::Flat</code>, <code class="code">Pick::Flat</code>, <code class="code">CellFlat</code>

<p>These are types that support ‘forward iterator’ traversal. They have methods <code class="code">operator+=</code> (to advance) and <code class="code">operator*</code> (to derreference). <b class="b">Flat</b> objects are obtained from <b class="b">Iterator</b> objects through a method <code class="code">flat()</code>. <code class="code">Scalar</code> is its own <b class="b">Flat</b>.
</p>
</li></ul>


<hr>
</div>
<div class="section-level-extent" id="Term-agreement">
<div class="nav-panel">
<p>
Next: <a href="#Loop-types" accesskey="n" rel="next">Loop types</a>, Previous: <a href="#Type-hierarchy" accesskey="p" rel="prev">Type hierarchy</a>, Up: <a href="#Internals" accesskey="u" rel="up">Internals</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Term-agreement-1">5.2 Term agreement</h3>

<p>The execution of an expression template begins with the determination of its shape — the length of each of its dimensions. This is done recursively by traversing the terms of the expression. For a given dimension <code class="code">k</code>≥0, terms that have rank less or equal than <code class="code">k</code> are ignored, following the prefix matching principle. Likewise terms where dimension <code class="code">k</code> has undefined length (such as <code class="code">iota()</code> or view axes created with <code class="code">insert</code>) are ignored. All the other terms must match.
</p>
<p>Then we select a traversal method depending on the types of the arguments. <code class="code">ra::</code> has two traversal methods, both based on pointer-like iterators. <code class="code">ply_ravel</code> is used for rt-size expressions and <code class="code">plyf</code> for ct-size expressions.
</p>
<p>Finally we select an order of traversal. <code class="code">ra::</code> supports ‘array’ orders, meaning that the dimensions are sorted in a certain way from outermost to innermost and a full dimension is traversed before one advances on the dimension outside. However, currently (v21) there is no heuristic to choose a dimension order, so traversal always happens in row-major order (which shouldn&rsquo;t be relied upon). <code class="code">ply_ravel</code> will unroll as many innermost dimensions as it can, and in some cases traversal will be executed as a flat loop.
</p>
<hr>
</div>
<div class="section-level-extent" id="Loop-types">
<div class="nav-panel">
<p>
Next: <a href="#Introspection" accesskey="n" rel="next">Introspection</a>, Previous: <a href="#Term-agreement" accesskey="p" rel="prev">Term agreement</a>, Up: <a href="#Internals" accesskey="u" rel="up">Internals</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Loop-types-1">5.3 Loop types</h3>

<p>TODO
</p>
<hr>
</div>
<div class="section-level-extent" id="Introspection">
<div class="nav-panel">
<p>
Next: <a href="#Compiling-and-running" accesskey="n" rel="next">Compiling and running</a>, Previous: <a href="#Loop-types" accesskey="p" rel="prev">Loop types</a>, Up: <a href="#Internals" accesskey="u" rel="up">Internals</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Introspection-1">5.4 Introspection</h3>

<hr>
</div>
<div class="section-level-extent" id="Compiling-and-running">
<div class="nav-panel">
<p>
Previous: <a href="#Introspection" accesskey="p" rel="prev">Introspection</a>, Up: <a href="#Internals" accesskey="u" rel="up">Internals</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h3 class="section" id="Compiling-and-running-1">5.5 Compiling and running</h3>

<p>The following <code class="code">#define</code>s affect the behavior of <code class="code">ra::</code>.
</p>
<ul class="itemize mark-bullet">
<li><code class="code">RA_DO_CHECK</code> (default 1):  Check shape agreement (e.g. <code class="code">Big&lt;int, 1&gt; {2, 3} + Big&lt;int, 1&gt; {1, 2, 3}</code>) and random array accesses (e.g. <code class="code">Small&lt;int, 2&gt; a = 0; int i = 10; a[i] = 0;</code>). See <a class="ref" href="#Error-handling">Error handling</a>.
</li><li><code class="code">RA_DO_OPT</code> (default 1): Sets the default for all <code class="code">RA_DO_OPT_XXX</code> flags.
</li><li><code class="code">RA_DO_OPT_IOTA</code> (default 1): Perform immediately (beat) certain operations on <code class="code">ra::Iota</code> objects. For example, <code class="code">ra::iota(3, 0) + 1</code> becomes <code class="code">ra::iota(3, 1)</code> instead of a two-operand expression template.
</li><li><code class="code">RA_DO_OPT_SMALLVECTOR</code> (default 0): Perform immediately certain operations on <code class="code">ra::Small</code> objects, using small vector intrinsics. Currently this only works on <b class="b">gcc</b> and doesn&rsquo;t necessarily result in improved performance.
</li></ul>

<p><code class="code">ra::</code> comes with three kinds of tests: examples, proper tests, and benchmarks. <code class="code">ra::</code> uses its own test and benchmark suites. Run <code class="code">CXXFLAGS=-O3 scons</code> from the top directory of the distribution to build and run them all.  Alternatively, you can use <code class="code">CXXFLAGS=-O3 cmake . &amp;&amp; make &amp;&amp; make test</code>. Like most expression template libraries, <code class="code">ra::</code> is highly dependent on optimization by the compiler and will be orders of magnitude slower with <samp class="option">-O0</samp> compared to <samp class="option">-O2</samp>.
</p>
<p>The following environment variables affect the test suite under SCons:
</p>
<ul class="itemize mark-bullet">
<li><code class="code">RA_USE_BLAS</code> (default 0): Use BLAS for <code class="code">gemm</code> and <code class="code">gemv</code> benchmarks.
</li></ul>


<hr>
</div>
</div>
<div class="chapter-level-extent" id="The-future">
<div class="nav-panel">
<p>
Next: <a href="#Reference" accesskey="n" rel="next">Reference</a>, Previous: <a href="#Internals" accesskey="p" rel="prev">Internals</a>, Up: <a href="#Top" accesskey="u" rel="up"><code class="code">ra::</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="The-future-1">6 The future</h2>

<ul class="mini-toc">
<li><a href="#Error-messages" accesskey="1">Error messages</a></li>
<li><a href="#Reductions" accesskey="2">Reductions</a></li>
<li><a href="#Etc" accesskey="3">Etc</a></li>
</ul>
<div class="section-level-extent" id="Error-messages">
<h3 class="section">6.1 Error messages</h3>

<p>FIXME
</p>
</div>
<div class="section-level-extent" id="Reductions">
<h3 class="section">6.2 Reductions</h3>

<p>FIXME
</p>
</div>
<div class="section-level-extent" id="Etc">
<h3 class="section">6.3 Etc</h3>

<p>FIXME
</p>
<hr>
</div>
</div>
<div class="chapter-level-extent" id="Reference">
<div class="nav-panel">
<p>
Next: <a href="#Sources" accesskey="n" rel="next">Sources</a>, Previous: <a href="#The-future" accesskey="p" rel="prev">The future</a>, Up: <a href="#Top" accesskey="u" rel="up"><code class="code">ra::</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Reference-1">7 Reference</h2>

<a class="index-entry-id" id="index-agree"></a>
<a class="anchor" id="x_002dagree"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-agree-1"><span class="category-def">Function: </span><span><strong class="def-name">agree</strong> <var class="def-var-arguments">arg ...</var><a class="copiable-link" href='#index-agree-1'> &para;</a></span></dt>
<dd><p>Return true if the shapes of arguments <var class="var">arg...</var> match (see <a class="ref" href="#Rank-extension">Rank extension</a>), else return false.
</p>
<p>This is useful when <a class="ref" href="#Error-handling">error checking</a> is enabled and one wants to avoid the failure response.
</p><div class="example">
<pre class="verbatim">    ra::Small&lt;int, 2, 3&gt; A;
    ra::Small&lt;int, 2&gt; B;
    ra::Small&lt;int, 3&gt; C;

    agree(A, B); // -&gt; true
    static_assert(agree(A, B)); // ok for ct shapes
    cout &lt;&lt; (A+B) &lt;&lt; endl; // ok

    agree(A, C); // -&gt; false
    cout &lt;&lt; (A+C) &lt;&lt; endl; // error. Maybe abort, maybe throw - cf Error Handling
</pre></div>
</dd></dl>

<a class="index-entry-id" id="index-agree_005fop"></a>
<a class="anchor" id="x_002dagree_005fop"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-agree_005fop-1"><span class="category-def">Function: </span><span><strong class="def-name">agree_op</strong> <var class="def-var-arguments">op arg ...</var><a class="copiable-link" href='#index-agree_005fop-1'> &para;</a></span></dt>
<dd><p>Return true if the shapes of arguments <var class="var">arg...</var> match (see <a class="ref" href="#Rank-extension">Rank extension</a>) relative to operator <var class="var">op</var>, else return false.
</p>
<p>This differs from <a class="ref" href="#x_002dagree"><code class="code">agree</code></a> when <var class="var">op</var> has non-zero argument ranks. For example:
</p><div class="example">
<pre class="verbatim">    ra::Big&lt;real, 1&gt; a({3}, 0.);
    ra::Big&lt;real, 2&gt; b({2, 3}, 0.n);

    agree(a, b); // -&gt; false
    cout &lt;&lt; (a+b) &lt;&lt; endl; // error

    agree_op(ra::wrank&lt;1, 1&gt;(std::plus()), a, b); // -&gt; true
    cout &lt;&lt; map(ra::wrank&lt;1, 1&gt;(std::plus()), a, b) &lt;&lt; endl; // ok
</pre></div>
</dd></dl>

<a class="index-entry-id" id="index-at"></a>
<a class="anchor" id="x_002dat"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-at-1"><span class="category-def">Function: </span><span><strong class="def-name">at</strong> <var class="def-var-arguments">expr indices</var><a class="copiable-link" href='#index-at-1'> &para;</a></span></dt>
<dd><p>Look up <var class="var">expr</var> at each element of <var class="var">indices</var>, which shall be a multi-index into <var class="var">expr</var>.
</p>
<p>This can be used for sparse subscripting. For example:
</p><div class="example">
<pre class="verbatim">    ra::Big&lt;int, 2&gt; A = {{100, 101}, {110, 111}, {120, 121}};
    ra::Big&lt;ra::Small&lt;int, 2&gt;, 2&gt; i = {{{0, 1}, {2, 0}}, {{1, 0}, {2, 1}}};
    ra::Big&lt;int, 2&gt; B = at(A, i);
</pre><pre class="example-preformatted">  &rArr; B = {{101, 120}, {110, 121}}
</pre></div>

</dd></dl>

<a class="index-entry-id" id="index-cast"></a>
<a class="anchor" id="x_002dcast"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-cast-1"><span class="category-def">Function: </span><span><strong class="def-name">cast</strong> <var class="def-var-arguments">&lt;type&gt; expr</var><a class="copiable-link" href='#index-cast-1'> &para;</a></span></dt>
<dd><p>Create an array expression that casts <var class="var">expr</var> into <var class="var">type</var>.
</p></dd></dl>

<a class="index-entry-id" id="index-collapse"></a>
<a class="anchor" id="x_002dcollapse"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-collapse-1"><span class="category-def">Function: </span><span><strong class="def-name">collapse</strong><a class="copiable-link" href='#index-collapse-1'> &para;</a></span></dt>
<dd><p>TODO
See also <a class="ref" href="#x_002dexplode"><code class="code">explode</code></a>.
</p></dd></dl>

<a class="index-entry-id" id="index-concrete"></a>
<a class="anchor" id="x_002dconcrete"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-concrete-1"><span class="category-def">Function: </span><span><strong class="def-name">concrete</strong> <var class="def-var-arguments">a</var><a class="copiable-link" href='#index-concrete-1'> &para;</a></span></dt>
<dd><p>Convert the argument to a container of the same shape as <var class="var">a</var>.
</p>
<p>If the argument has rt or ct shape, it is the same for the result. The main use of this function is to obtain modifiable copy of an array expression without having to prepare a container beforehand, or compute the appropiate type.
</p>

</dd></dl>

<a class="index-entry-id" id="index-diag"></a>
<a class="anchor" id="x_002ddiag"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-diag-1"><span class="category-def">Function: </span><span><strong class="def-name">diag</strong> <var class="def-var-arguments">view</var><a class="copiable-link" href='#index-diag-1'> &para;</a></span></dt>
<dd><p>Equivalent to <code class="code">transpose&lt;0, 0&gt;(view)</code>.
</p></dd></dl>

<a class="index-entry-id" id="index-explode"></a>
<a class="anchor" id="x_002dexplode"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-explode-1"><span class="category-def">Function: </span><span><strong class="def-name">explode</strong><a class="copiable-link" href='#index-explode-1'> &para;</a></span></dt>
<dd><p>TODO
</p>
<p>See also <a class="ref" href="#x_002dcollapse"><code class="code">collapse</code></a>.
</p></dd></dl>

<a class="index-entry-id" id="index-for_005feach"></a>
<a class="anchor" id="x_002dfor_005feach"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-for_005feach-1"><span class="category-def">Function: </span><span><strong class="def-name">for_each</strong> <var class="def-var-arguments">op expr ...</var><a class="copiable-link" href='#index-for_005feach-1'> &para;</a></span></dt>
<dd><p>Create an array expression that applies <var class="var">op</var> to <var class="var">expr</var> ..., and traverse it.
</p>
<p><var class="var">op</var> is run for effect; whatever it returns is discarded. For example:
</p><div class="example">
<pre class="verbatim">double s = 0.;
for_each([&amp;s](auto &amp;&amp; a) { s+=a; }, ra::Small&lt;double, 1&gt; {1., 2., 3})
</pre><pre class="example-preformatted">&rArr; s = 6.
</pre></div>

<p>See also <a class="ref" href="#x_002dmap"><code class="code">map</code></a>.
</p>
</dd></dl>

<a class="index-entry-id" id="index-format_005farray"></a>
<a class="anchor" id="x_002dformat_005farray"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-format_005farray-1"><span class="category-def">Function: </span><span><strong class="def-name">format_array</strong> <var class="def-var-arguments">expr [last_axis_separator [second_last_axis_separator ...]]</var><a class="copiable-link" href='#index-format_005farray-1'> &para;</a></span></dt>
<dd><p>Formats an array for character output.
</p>
<p>For example:
</p>
<div class="example">
<pre class="verbatim">ra::Small&lt;int, 2, 2&gt; A = {{1, 2}, {3, 4}};
cout &lt;&lt; &quot;case a:\n&quot; &lt;&lt; A &lt;&lt; endl;
cout &lt;&lt; &quot;case b:\n&quot; &lt;&lt; format_array(A) &lt;&lt; endl;
cout &lt;&lt; &quot;case c:\n&quot; &lt;&lt;  format_array(A, &quot;|&quot;, &quot;-&quot;) &lt;&lt; endl;
</pre><pre class="example-preformatted">-| case a:
1 2
3 4
case b:
1 2
3 4
case c:
1|2-3|4
</pre></div>

<p>The shape that might be printed before the expression itself (depending on its type) is not subject to these separators.
</p>
<p>See also <a class="ref" href="#x_002dnoshape"><code class="code">noshape</code></a>, <a class="ref" href="#x_002dwithshape"><code class="code">withshape</code></a>.
</p>
</dd></dl>

<a class="index-entry-id" id="index-from"></a>
<a class="anchor" id="x_002dfrom"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-from-1"><span class="category-def">Function: </span><span><strong class="def-name">from</strong> <var class="def-var-arguments">op expr ...</var><a class="copiable-link" href='#index-from-1'> &para;</a></span></dt>
<dd><p>Create outer product expression. This is defined as
</p>
<div class="display">
<pre class="display-preformatted">E = from(op, e₀, e₁ ...) ⇒ E(i₀₀, i₀₁ ..., i₁₀, i₁₁, ..., ...) = op[expr₀(i₀₀, i₀₁, ...), expr₁(i₁₀, i₁₁, ...), ...].
</pre></div>

<p>For example:
</p><div class="example">
<pre class="verbatim">    ra::Big&lt;double, 1&gt; a {1, 2, 3};
    ra::Big&lt;double, 1&gt; b {10, 20, 30};
    ra::Big&lt;double, 2&gt; axb = from([](auto &amp;&amp; a, auto &amp;&amp; b) { return a*b; }, a, b)
</pre><pre class="example-preformatted">  &rArr; axb = {{10, 20, 30}, {20, 40, 60}, {30, 60, 90}}
</pre></div>

<div class="example">
<pre class="verbatim">    ra::Big&lt;int, 1&gt; i {2, 1};
    ra::Big&lt;int, 1&gt; j {0, 1};
    ra::Big&lt;double, 2&gt; A = {{1, 2}, {3, 4}, {5, 6}};
    ra::Big&lt;double, 2&gt; Aij = from(A, i, j)
</pre><pre class="example-preformatted">  &rArr; Aij = {{6, 5}, {4, 3}}
</pre></div>

<p>The last example is more or less how <code class="code">A(i, j)</code> is implemented for arbitrary subscripts (see <a class="pxref" href="#The-rank-conjunction">The rank conjunction</a>).
</p>
</dd></dl>

<a class="index-entry-id" id="index-imag_005fpart"></a>
<a class="anchor" id="x_002dimag_005fpart"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-imag_005fpart-1"><span class="category-def">Function: </span><span><strong class="def-name">imag_part</strong><a class="copiable-link" href='#index-imag_005fpart-1'> &para;</a></span></dt>
<dd><p>Take imaginary part of a complex number. This can be used as reference.
</p>
<p>For example: </p>
<div class="example">
<pre class="verbatim">ra::Small&lt;std::complex&lt;double&gt;, 2, 2&gt; A = {{1., 2.}, {3., 4.}};
imag_part(A) = -2*real_part(A);
cout &lt;&lt; A &lt;&lt; endl;
</pre><pre class="example-preformatted">-|
(1, -2) (2, -4)
(3, -6) (4, -8)
</pre></div>

<p>See also <a class="ref" href="#x_002dreal_005fpart"><code class="code">real_part</code></a>.
</p></dd></dl>

<a class="index-entry-id" id="index-map"></a>
<a class="anchor" id="x_002dmap"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-map-1"><span class="category-def">Function: </span><span><strong class="def-name">map</strong> <var class="def-var-arguments">op expr ...</var><a class="copiable-link" href='#index-map-1'> &para;</a></span></dt>
<dd><p>Create an array expression that applies callable <var class="var">op</var> to <var class="var">expr</var> ...
</p>
<p>For example:
</p><div class="example">
<pre class="verbatim">ra::Big&lt;double, 1&gt; x = map(cos, std::array {0.});
</pre><pre class="example-preformatted">&rArr; x = { 1. }
</pre></div>

<p><var class="var">op</var> can return a reference. For example:
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 2&gt; x = {{3, 3}, 0.};
ra::Big&lt;int, 2&gt; i = {0, 1, 1, 2};
ra::Big&lt;int, 2&gt; j = {1, 0, 2, 1};
map(x, i, j) = 1;
</pre><pre class="example-preformatted">&rArr; x = {{0, 1, 0}, {1, 0, 1}, {0, 1, 0}}
</pre></div>

<p>Note that <code class="code">map(x, i, j)</code> is <a class="ref" href="#x_002dsubscript_002douter_002dproduct">not the same</a> as <code class="code">x(i, j)</code>.
</p>
<p><var class="var">op</var> can be any callable. For example:
</p><div class="example">
<pre class="verbatim">struct A { int a, b; };
std::vector&lt;A&gt; v = {{1, 2}, {3, 4}};
ra::map(&amp;A::a, v) = -ra::map(&amp;A::b, v); // pointer to member
</pre><pre class="example-preformatted">&rArr; v = {{-2, 2}, {-4, 4}}
</pre></div>

<p>See also <a class="ref" href="#x_002dfor_005feach"><code class="code">for_each</code></a>.
</p>
</dd></dl>

<a class="index-entry-id" id="index-pack"></a>
<a class="anchor" id="x_002dpack"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-pack-1"><span class="category-def">Function: </span><span><strong class="def-name">pack</strong> <var class="def-var-arguments">&lt;type&gt; expr ...</var><a class="copiable-link" href='#index-pack-1'> &para;</a></span></dt>
<dd><p>Create an array expression that brace-constructs <var class="var">type</var> from <var class="var">expr</var> ...
</p></dd></dl>

<a class="index-entry-id" id="index-pick"></a>
<a class="anchor" id="x_002dpick"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-pick-1"><span class="category-def">Function: </span><span><strong class="def-name">pick</strong> <var class="def-var-arguments">select_expr expr ...</var><a class="copiable-link" href='#index-pick-1'> &para;</a></span></dt>
<dd><p>Create an array expression that selects the first of <var class="var">expr</var> ... if <var class="var">select_expr</var> is 0, the second if <var class="var">select_expr</var> is 1, and so on. The expressions that are not selected are not looked up.
</p>
<p>This function cannot be defined using <a class="ref" href="#x_002dmap"><code class="code">map</code></a>, because <code class="code">map</code> looks up each one of its argument expressions before calling <var class="var">op</var>.
</p>
<p>For example:
</p><div class="example">
<pre class="verbatim">    ra::Small&lt;int, 3&gt; s {2, 1, 0};
    ra::Small&lt;double, 3&gt; z = pick(s, s*s, s+s, sqrt(s));
</pre><pre class="example-preformatted">  &rArr; z = {1.41421, 2, 0}
</pre></div>

</dd></dl>

<a class="index-entry-id" id="index-ply"></a>
<a class="anchor" id="x_002dply"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ply-1"><span class="category-def">Function: </span><span><strong class="def-name">ply</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-ply-1'> &para;</a></span></dt>
<dd><p>Traverse <var class="var">expr</var>. <code class="code">ply</code> returns <code class="code">void</code> so <var class="var">expr</var> should be run for effect.
</p>
<p>It is rarely necessary to use <code class="code">ply</code>. Expressions are traversed automatically when they are assigned to views, for example, or printed out. <a class="ref" href="#x_002dfor_005feach"><code class="code">for_each</code></a><code class="code">(...)</code>, which is equivalent to <code class="code">ply(map(...))</code>, should cover most other uses.
</p>
<div class="example">
<pre class="verbatim">double s = 0.;
ply(map([&amp;s](auto &amp;&amp; a) { s+=a; }, ra::Small&lt;double, 1&gt; {1., 2., 3})) // same as for_each
</pre><pre class="example-preformatted">&rArr; s = 6.
</pre></div>

</dd></dl>

<a class="index-entry-id" id="index-real_005fpart"></a>
<a class="anchor" id="x_002dreal_005fpart"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-real_005fpart-1"><span class="category-def">Function: </span><span><strong class="def-name">real_part</strong><a class="copiable-link" href='#index-real_005fpart-1'> &para;</a></span></dt>
<dd><p>Take real part of a complex number. This can be used as reference.
</p>
<p>See also <a class="ref" href="#x_002dimag_005fpart"><code class="code">imag_part</code></a>.
</p></dd></dl>

<a class="index-entry-id" id="index-reverse"></a>
<a class="anchor" id="x_002dreverse"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-reverse-1"><span class="category-def">Function: </span><span><strong class="def-name">reverse</strong> <var class="def-var-arguments">view axis</var><a class="copiable-link" href='#index-reverse-1'> &para;</a></span></dt>
<dd><p>Create a new view by reversing axis <var class="var">k</var> of <var class="var">view</var>.
</p>
<p>This is equivalent to <code class="code">view(ra::dots&lt;k&gt;, ra::iota(ra::len, ra::len-1, -1))</code>.
</p>
<p>This operation does not work on arbitrary array expressions yet. TODO FILL
</p>
</dd></dl>

<a class="index-entry-id" id="index-shape-1"></a>
<a class="anchor" id="x_002dshape"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-shape-2"><span class="category-def">Function: </span><span><strong class="def-name">shape</strong> <var class="def-var-arguments">a</var><a class="copiable-link" href='#index-shape-2'> &para;</a></span></dt>
<dd><p>Get the shape of an <code class="code">ra::</code> object.
</p>
<p>The shape of a rt rank array is a rank-1 object with rt size, and the shape of a ct rank array is a rank-1 object with ct size.
</p>
<p>This function may return an expression object or an array object. If you need to operate on the result, it might be necessary to use <code class="code">concrete</code>.
</p>
</dd></dl>


<a class="index-entry-id" id="index-size"></a>
<a class="anchor" id="x_002dsize"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-size-1"><span class="category-def">Function: </span><span><strong class="def-name">size</strong> <var class="def-var-arguments">a</var><a class="copiable-link" href='#index-size-1'> &para;</a></span></dt>
<dd><p>Get the total size of an <code class="code">ra::</code> object: the product of all its lengths.
</p></dd></dl>


<a class="index-entry-id" id="index-stencil"></a>
<a class="anchor" id="x_002dstencil"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-stencil-1"><span class="category-def">Function: </span><span><strong class="def-name">stencil</strong> <var class="def-var-arguments">view lo hi</var><a class="copiable-link" href='#index-stencil-1'> &para;</a></span></dt>
<dd><p>Create a stencil on <var class="var">view</var> with lower bounds <var class="var">lo</var> and higher bounds <var class="var">hi</var>.
</p>
<p><var class="var">lo</var> and <var class="var">hi</var> are expressions of rank 1 indicating the extent of the stencil on each dimension. Scalars are rank extended, that is, <var class="var">lo</var>=0 is equivalent to <var class="var">lo</var>=(0, 0, ..., 0) with length equal to the rank <code class="code">r</code> of <var class="var">view</var>. The stencil view has twice as many axes as <var class="var">view</var>. The first <code class="code">r</code> dimensions are the same as those of <var class="var">view</var> except that they have their lengths reduced by <var class="var">lo</var>+<var class="var">hi</var>. The last <code class="code">r</code> dimensions correspond to the stencil around each element of <var class="var">view</var>; the center element is at <code class="code">s(i0, i1, ..., lo(0), lo(1), ...)</code>.
</p>
<p>This operation does not work on arbitrary array expressions yet. TODO FILL
</p>
</dd></dl>

<a class="index-entry-id" id="index-swap"></a>
<a class="anchor" id="x_002dswap"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-swap-1"><span class="category-def">Function: </span><span><strong class="def-name">swap</strong> <var class="def-var-arguments">a b</var><a class="copiable-link" href='#index-swap-1'> &para;</a></span></dt>
<dd><p>Swap the contents of containers <var class="var">a</var> and <var class="var">b</var>.
</p>
<p>Both containers must be of the same storage type. The containers may have different shapes, but if at least one of them is of ct rank, then both of them must have the same rank.
</p>
<p>This function reuses <code class="code">std::swap</code> for same-rank overloads, so it must not be qualified (i.e. use <code class="code">swap(a, b)</code>, not <code class="code">ra::swap(a, b)</code>).
</p></dd></dl>

<div class="example">
<pre class="verbatim">    ra::Big&lt;int&gt; a ({2, 3}, 1 + ra::_0 - ra::_1); // (1)
    ra::Big&lt;int&gt; b ({2, 3, 4}, 1 - ra::_0 + ra::_1 + ra::_2); // (2)
    swap(a, b);
    // as if (1) had b and (2) had a
</pre></div>

<a class="index-entry-id" id="index-transpose"></a>
<a class="anchor" id="x_002dtranspose"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-transpose-1"><span class="category-def">Function: </span><span><strong class="def-name">transpose</strong> <var class="def-var-arguments">&lt;axes ...&gt; (view) | (axes, view)</var><a class="copiable-link" href='#index-transpose-1'> &para;</a></span></dt>
<dd><p>Create a new view by transposing the axes of <var class="var">view</var>. The number of <var class="var">axes</var> must match the rank of <var class="var">view</var>.
</p>
<p>For example:
</p>
<div class="example">
<pre class="verbatim">    ra::Unique&lt;double, 2&gt; a = {{1, 2, 3}, {4, 5, 6}};
    cout &lt;&lt; transpose&lt;1, 0&gt;(a) &lt;&lt; endl;
</pre><pre class="example-preformatted">  -|
  3 2
  1 4
  2 5
  3 6
</pre></div>

<p>The rank of the result is <code class="code">maxᵢ(axesᵢ)+1</code> and it may be smaller or larger than that of <var class="var">view</var>. If an axis is repeated, the smallest of the dimensions of <var class="var">view</var> is used. For example:
</p>
<div class="example">
<pre class="verbatim">    ra::Unique&lt;double, 2&gt; a = {{1, 2, 3}, {4, 5, 6}};
    cout &lt;&lt; transpose&lt;0, 0&gt;(a) &lt;&lt; endl; // { a(0, 0), a(1, 1) }
</pre><pre class="example-preformatted">  -|
  2
  1 5
</pre></div>

<p>If one of the destination axes isn&rsquo;t mentioned in <var class="var">axes</var>, then it becomes a ‘dead’ axis similar to those produced by <a class="ref" href="#x_002dinsert"><code class="code">insert</code></a>. For example:
</p>
<div class="example">
<pre class="verbatim">    ra::Unique&lt;double, 1&gt; a = {1, 2, 3};
    cout &lt;&lt; ((a*10) + transpose&lt;1&gt;(a)) &lt;&lt; endl;
</pre><pre class="example-preformatted">  -|
  3 3
  11 21 31
  12 22 32
  13 23 33
</pre></div>

<p>The two argument form lets you specify the axis list at runtime. In that case the result will have rt rank as well. For example: </p>
<div class="example">
<pre class="verbatim">    ra::Small&lt;int, 2&gt; axes = {0, 1};
    ra::Unique&lt;double, 2&gt; a = {{1, 2, 3}, {4, 5, 6}};
    cout &lt;&lt; &quot;A: &quot; &lt;&lt; transpose(axes, a) &lt;&lt; endl;
    axes = {1, 0};
    cout &lt;&lt; &quot;B: &quot; &lt;&lt; transpose(axes, a) &lt;&lt; endl;
</pre><pre class="example-preformatted">  -|
  A: 2
  2 3
  1 2 3
  4 5 6
  B: 2
  3 2
  1 4
  2 5
  3 6
</pre></div>

<p>This operation does not work on arbitrary array expressions yet. TODO FILL
</p>
</dd></dl>

<a class="index-entry-id" id="index-where"></a>
<a class="anchor" id="x_002dwhere"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-where-1"><span class="category-def">Function: </span><span><strong class="def-name">where</strong> <var class="def-var-arguments">pred_expr true_expr false_expr</var><a class="copiable-link" href='#index-where-1'> &para;</a></span></dt>
<dd><p>Create an array expression that selects <var class="var">true_expr</var> if <var class="var">pred_expr</var> is <code class="code">true</code>, and <var class="var">false_expr</var> if <var class="var">pred_expr</var> is <code class="code">false</code>. The expression that is not selected is not looked up.
</p>
<p>For example:
</p><div class="example">
<pre class="verbatim">    ra::Big&lt;double, 1&gt; s {1, -1, 3, 2};
    s = where(s&gt;=2, 2, s); // saturate s
</pre><pre class="example-preformatted">  &rArr; s = {1, -1, 2, 2}
</pre></div>

</dd></dl>

<a class="index-entry-id" id="index-wrank"></a>
<a class="anchor" id="x_002dwrank"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-wrank-1"><span class="category-def">Function: </span><span><strong class="def-name">wrank</strong> <var class="def-var-arguments">&lt;input_rank ...&gt; op</var><a class="copiable-link" href='#index-wrank-1'> &para;</a></span></dt>
<dd><p>Wrap <var class="var">op</var> using a rank conjunction (see <a class="pxref" href="#The-rank-conjunction">The rank conjunction</a>).
</p>
<p>For example: TODO
</p><div class="example">
<pre class="verbatim"></pre><pre class="example-preformatted">  &rArr; x = 0
</pre></div>

</dd></dl>


<a class="index-entry-id" id="index-noshape"></a>
<a class="index-entry-id" id="index-withshape"></a>
<a class="anchor" id="x_002dnoshape"></a><a class="anchor" id="x_002dwithshape"></a><dl class="first-deffn">
<dt class="deffn" id="index-withshape-noshape"><span class="category-def">Special&nbsp;object<!-- /@w -->: </span><span><strong class="def-name">withshape noshape</strong><a class="copiable-link" href='#index-withshape-noshape'> &para;</a></span></dt>
<dd><p>If either of these objects is sent to <code class="code">std::ostream</code> before an expression object, the shape of that object will or will not be printed.
</p>
<p>If the object has ct shape, the default is not to print the shape, so <code class="code">noshape</code> isn&rsquo;t necessary, and conversely for <code class="code">withshape</code> if the object has rt shape. Note that the array readers [<code class="code">operator&gt;&gt;(std::istream &amp;, ...)</code>] expect the shape to be present or not according to the default.
</p>
<p>For example:
</p>
<div class="example">
<pre class="verbatim">ra::Small&lt;int, 2, 2&gt; A = {77, 99};
cout &lt;&lt; &quot;case a:\n&quot; &lt;&lt; A &lt;&lt; endl;
cout &lt;&lt; &quot;case b:\n&quot; &lt;&lt; ra::noshape &lt;&lt; A &lt;&lt; endl;
cout &lt;&lt; &quot;case c:\n&quot; &lt;&lt; ra::withshape &lt;&lt; A &lt;&lt; endl;
</pre><pre class="example-preformatted">-| case a:
77 99
case b:
77 99
case c:
2
77 99
</pre></div>

<p>but:
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int&gt; A = {77, 99};
cout &lt;&lt; &quot;case a:\n&quot; &lt;&lt; A &lt;&lt; endl;
cout &lt;&lt; &quot;case b:\n&quot; &lt;&lt; ra::noshape &lt;&lt; A &lt;&lt; endl;
cout &lt;&lt; &quot;case c:\n&quot; &lt;&lt; ra::withshape &lt;&lt; A &lt;&lt; endl;
</pre><pre class="example-preformatted">-| case a:
1
2
77 99
case b:
77 99
case c:
1
2
77 99
</pre></div>

<p>Note that in the last example the very shape of <code class="code">ra::Big&lt;int&gt;</code> has rt length, so that length (the rank of <code class="code">A</code>, that is 1) is printed as part of the shape of <code class="code">A</code>.
</p>
<p>See also <a class="ref" href="#x_002dformat_005farray"><code class="code">format_array</code></a>.
</p>
</dd></dl>

<a class="index-entry-id" id="index-ptr"></a>
<a class="anchor" id="x_002dptr"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-ptr-1"><span class="category-def">Function: </span><span><strong class="def-name">ptr</strong> <var class="def-var-arguments">random_access_iterator [len]</var><a class="copiable-link" href='#index-ptr-1'> &para;</a></span></dt>
<dd><p>Create rank-1 expression from <var class="var">random_access_iterator</var>, which can be a raw pointer.
</p>
<p>If <code class="code">len</code> is not given, the expression has undefined length, and it will need to be matched with other expressions whose length is defined. <code class="code">ra::</code> doesn&rsquo;t know what is actually accessible through the iterator, so be careful. For instance:
</p>
<div class="example">
<pre class="verbatim">int p[] = {1, 2, 3};
ra::Big&lt;int, 1&gt; v3 {1, 2, 3};
ra::Big&lt;int, 1&gt; v4 {1, 2, 3, 4};
v3 += ra::ptr(p); // ok, shape (3): v3 = {2, 4, 6}
v4 += ra::ptr(p); // undefined, shape (4): bad access to p[3]
// cout &lt;&lt; (ra::ptr(p)+ra::TensorIndex&lt;0&gt;{}) &lt;&lt; endl; // ct error, expression has undefined shape
cout &lt;&lt; (ra::ptr(p, 3)+ra::TensorIndex&lt;0&gt;{}) &lt;&lt; endl; // ok, prints { 1, 3, 5 }
cout &lt;&lt; (ra::ptr(p, 4)+ra::TensorIndex&lt;0&gt;{}) &lt;&lt; endl; // undefined, bad access at p[4]
</pre></div>

<p>Of course in this example one could simply have used <code class="code">p</code> instead of <code class="code">ra::ptr(p)</code>, since the array type retains shape information.
</p>
<div class="example">
<pre class="verbatim">v3 += p; // ok
v4 += p; // error checked by ra::, shape clash (4) += (3)
cout &lt;&lt; (p + ra::TensorIndex&lt;0&gt;{}) &lt;&lt; endl; // ok
</pre></div>

<p><code class="code">ptr</code> isn&rsquo;t meant to be used with STL containers, which are converted to rank-1 expressions automatically of the right size automatically. See also <a class="ref" href="#x_002dstart"><code class="code">start</code></a>.
</p>
</dd></dl>

<a class="index-entry-id" id="index-start-1"></a>
<a class="anchor" id="x_002dstart"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-start-2"><span class="category-def">Function: </span><span><strong class="def-name">start</strong> <var class="def-var-arguments">foreign_object</var><a class="copiable-link" href='#index-start-2'> &para;</a></span></dt>
<dd><p>Create array expression from <var class="var">foreign_object</var>.
</p>
<p><var class="var">foreign_object</var> can be a built-in array (e.g. <code class="code">int[3][2]</code>), a <code class="code">std::random_access_range</code> type (including <code class="code">std::vector</code> or <code class="code">std::array</code>, see <a class="pxref" href="#Compatibility">Compatibility</a>), an initializer list, or any object that <code class="code">ra::</code> accepts as scalar (see <a class="ref" href="#x_002dis_002dscalar"><code class="code">here</code></a>). The resulting expresion has shape according to the original object. Compare this with <a class="ref" href="#x_002dscalar"><code class="code">scalar</code></a>, which will always produce an expression of rank 0.
</p>
<p>Generally one can mix these types with <code class="code">ra::</code> expressions without needing <code class="code">ra::start</code>, but sometimes this isn&rsquo;t possible, for example for operators that must be class members.
</p>
<div class="example">
<pre class="verbatim">std::vector&lt;int&gt; x = {1, 2, 3};
ra::Big&lt;int, 1&gt; y = {10, 20, 30};
cout &lt;&lt; (x+y) &lt;&lt; endl; // same as ra::start(x)+y
// x += y; // error: no match for operator+=
ra::start(x) += y; // ok
</pre><pre class="example-preformatted">-| 3
  11 22 33
  &rArr; x = { 11, 22, 33 }
</pre></div>

</dd></dl>

<a class="index-entry-id" id="index-scalar"></a>
<a class="anchor" id="x_002dscalar"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-scalar-1"><span class="category-def">Function: </span><span><strong class="def-name">scalar</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-scalar-1'> &para;</a></span></dt>
<dd><p>Create scalar expression from <var class="var">expr</var>.
</p>
<p>The primary use of this function is to bring a scalar object into the <code class="code">ra::</code> namespace. A somewhat artificial example:
</p>
<div class="example">
<pre class="verbatim">struct W { int x; }
ra::Big&lt;W, 1&gt; w { {1}, {2}, {3} };

// error: no matching function for call to start(W)
// for_each([](auto &amp;&amp; a, auto &amp;&amp; b) { cout &lt;&lt; (a.x + b.x) &lt;&lt; endl; }, w, W {7});

// bring W into ra:: with ra::scalar
for_each([](auto &amp;&amp; a, auto &amp;&amp; b) { cout &lt;&lt; (a.x + b.x) &lt;&lt; endl; }, w, ra::scalar(W {7}));
</pre><pre class="example-preformatted">-| 8
   9
   10
</pre></div>

<p>See also <a class="ref" href="#x_002dscalar_002dchar_002dstar"><code class="code">this example</code></a>.
</p>
<p>Since <code class="code">scalar</code> produces an object with rank 0, it&rsquo;s also useful when dealing with nested arrays, even for objects that are already in <code class="code">ra::</code>. Consider:
</p><div class="example">
<pre class="verbatim">using Vec2 = ra::Small&lt;double, 2&gt;;
Vec2 x {-1, 1};
ra::Big&lt;Vec2, 1&gt; c { {1, 2}, {2, 3}, {3, 4} };
// c += x // error: x has shape (2) and c has shape (3)
c += ra::scalar(x); // ok: scalar(x) has shape () and matches c.
</pre><pre class="example-preformatted">  &rArr; c = { {0, 3}, {1, 4}, {2, 5} }
</pre></div>
<p>The result is {c(0)+x, c(1)+x, c(2)+x}. Compare this with
</p><div class="example">
<pre class="verbatim">c(ra::iota(2)) += x; // c(ra::iota(2)) with shape (2) matches x with shape (2)
</pre><pre class="example-preformatted">  &rArr; c = { {-1, 2}, {2, 5}, {2, 5} }
</pre></div>
<p>where the result is {c(0)+x(0), c(1)+x(1), c(2)}.
</p>
</dd></dl>

<a class="index-entry-id" id="index-iter"></a>
<a class="anchor" id="x_002diter"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-iter-1"><span class="category-def">Function: </span><span><strong class="def-name">iter</strong> <var class="def-var-arguments">&lt;k&gt; (view)</var><a class="copiable-link" href='#index-iter-1'> &para;</a></span></dt>
<dd><p>Create iterator over the <var class="var">k</var>-cells of <var class="var">view</var>. If <var class="var">k</var> is negative, it is interpreted as the negative of the frame rank. In the current version of <code class="code">ra::</code>, <var class="var">view</var> may have rt or ct shape.
</p>
<div class="example">
<pre class="verbatim">ra::Big&lt;int, 2&gt; c {{1, 3, 2}, {7, 1, 3}};
cout &lt;&lt; &quot;max of each row: &quot; &lt;&lt; map([](auto &amp;&amp; a) { return amax(a); }, iter&lt;1&gt;(c)) &lt;&lt; endl;
ra::Big&lt;int, 1&gt; m({3}, 0);
scalar(m) = max(scalar(m), iter&lt;1&gt;(c));
cout &lt;&lt; &quot;max of each column: &quot; &lt;&lt; m &lt;&lt; endl;
m = 0;
for_each([&amp;m](auto &amp;&amp; a) { m = max(m, a); }, iter&lt;1&gt;(c));
cout &lt;&lt; &quot;max of each column again: &quot; &lt;&lt; m &lt;&lt; endl;
</pre><pre class="example-preformatted">-| max of each row: 2
   3 7
   max of each column: 3
   7 3 3
   max of each column again: 3
   7 3 3
</pre></div>

<p>In the following example, <code class="code">iter</code> emulates <code class="code">scalar</code>. Note that the shape () of <code class="code">iter&lt;1&gt;(m)</code> matches the shape (3) of <code class="code">iter&lt;1&gt;(c)</code>. Thus, each of the 1-cells of <code class="code">c</code> matches against the single 1-cell of <code class="code">m</code>.
</p>
<div class="example">
<pre class="verbatim">m = 0;
iter&lt;1&gt;(m) = max(iter&lt;1&gt;(m), iter&lt;1&gt;(c));
cout &lt;&lt; &quot;max of each column yet again: &quot; &lt;&lt; m &lt;&lt; endl;
</pre><pre class="example-preformatted">-| max of each column again: 3
   7 3 3
</pre></div>

<p>The following example computes the trace of each of the items [(-1)-cells] of <code class="code">c</code>. </p>
<div class="example">
<pre class="verbatim">ra::Small&lt;int, 3, 2, 2&gt; c = ra::_0 - ra::_1 - 2*ra::_2;
cout &lt;&lt; &quot;c: &quot; &lt;&lt; c &lt;&lt; endl;
cout &lt;&lt; &quot;s: &quot; &lt;&lt; map([](auto &amp;&amp; a) { return sum(diag(a)); }, iter&lt;-1&gt;(c)) &lt;&lt; endl;
</pre><pre class="example-preformatted">-| c: 0 -2
   -1 -3
   1 -1
   0 -2
   2 0
   1 -1
   s: -3 -1 -1
</pre></div>

</dd></dl>

<a class="index-entry-id" id="index-sum"></a>
<a class="anchor" id="x_002dsum"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-sum-1"><span class="category-def">Function: </span><span><strong class="def-name">sum</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-sum-1'> &para;</a></span></dt>
<dd><p>Return the sum (+) of the elements of <var class="var">expr</var>, or 0 if expr is empty. This sum is performed in unspecified order.
</p></dd></dl>

<a class="index-entry-id" id="index-prod"></a>
<a class="anchor" id="x_002dprod"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-prod-1"><span class="category-def">Function: </span><span><strong class="def-name">prod</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-prod-1'> &para;</a></span></dt>
<dd><p>Return the product (*) of the elements of <var class="var">expr</var>, or 1 if expr is empty. This product is performed in unspecified order.
</p></dd></dl>

<a class="index-entry-id" id="index-amax"></a>
<a class="anchor" id="x_002damax"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-amax-1"><span class="category-def">Function: </span><span><strong class="def-name">amax</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-amax-1'> &para;</a></span></dt>
<dd><p>Return the maximum of the elements of <var class="var">expr</var>. If <var class="var">expr</var> is empty, return <code class="code">-std::numeric_limits&lt;T&gt;::infinity()</code> if the type supports it, otherwise <code class="code">std::numeric_limits&lt;T&gt;::lowest()</code>, where <code class="code">T</code> is the value type of the elements of <var class="var">expr</var>.
</p></dd></dl>

<a class="index-entry-id" id="index-amin"></a>
<a class="anchor" id="x_002damin"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-amin-1"><span class="category-def">Function: </span><span><strong class="def-name">amin</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-amin-1'> &para;</a></span></dt>
<dd><p>Return the minimum of the elements of <var class="var">expr</var>. If <var class="var">expr</var> is empty, return <code class="code">+std::numeric_limits&lt;T&gt;::infinity()</code> if the type supports it, otherwise <code class="code">std::numeric_limits&lt;T&gt;::max()</code>, where <code class="code">T</code> is the value type of the elements of <var class="var">expr</var>.
</p></dd></dl>

<a class="index-entry-id" id="index-early"></a>
<a class="anchor" id="x_002dearly"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-early-1"><span class="category-def">Function: </span><span><strong class="def-name">early</strong> <var class="def-var-arguments">expr default</var><a class="copiable-link" href='#index-early-1'> &para;</a></span></dt>
<dd><p><var class="var">expr</var> shall be an array expression that returns <code class="code">std::tuple&lt;bool, T&gt;</code>. <var class="var">expr</var> is traversed as by <code class="code">for_each</code>; if the expression ever returns <code class="code">true</code> in the first element of the tuple, traversal stops and the second element is returned. If this never happens, <var class="var">default</var> is returned instead.
</p>
<p>The following definition of elementwise <code class="code">lexicographical_compare</code> relies on <code class="code">early</code>.
</p>
<div class="example">
<pre class="verbatim">template &lt;class A, class B&gt;
inline bool lexicographical_compare(A &amp;&amp; a, B &amp;&amp; b)
{
    return early(map([](auto &amp;&amp; a, auto &amp;&amp; b)
                     { return a==b ? std::make_tuple(false, true) : std::make_tuple(true, a&lt;b); },
                     a, b),
                 false);
}
</pre></div>

</dd></dl>

<a class="index-entry-id" id="index-any"></a>
<a class="anchor" id="x_002dany"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-any-1"><span class="category-def">Function: </span><span><strong class="def-name">any</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-any-1'> &para;</a></span></dt>
<dd><p>Return <code class="code">true</code> if any element of <var class="var">expr</var> is true, <code class="code">false</code> otherwise. The traversal of the array expression will stop as soon as possible, but the traversal order is not specified.
</p></dd></dl>

<a class="index-entry-id" id="index-every"></a>
<a class="anchor" id="x_002devery"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-every-1"><span class="category-def">Function: </span><span><strong class="def-name">every</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-every-1'> &para;</a></span></dt>
<dd><p>Return <code class="code">true</code> if every element of <var class="var">expr</var> is true, <code class="code">false</code> otherwise. The traversal of the array expression will stop as soon as possible, but the traversal order is not specified.
</p></dd></dl>

<a class="index-entry-id" id="index-sqr"></a>
<a class="anchor" id="x_002dsqr"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-sqr-1"><span class="category-def">Function: </span><span><strong class="def-name">sqr</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-sqr-1'> &para;</a></span></dt>
<dd><p>Compute the square of <var class="var">expr</var>.
</p></dd></dl>

<a class="index-entry-id" id="index-sqrm"></a>
<a class="anchor" id="x_002dsqrm"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-sqrm-1"><span class="category-def">Function: </span><span><strong class="def-name">sqrm</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-sqrm-1'> &para;</a></span></dt>
<dd><p>Compute the square of the norm-2 of <var class="var">expr</var>, that is, <code class="code">conj(expr)*expr</code>.
</p></dd></dl>

<a class="index-entry-id" id="index-conj"></a>
<a class="anchor" id="x_002dconj"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-conj-1"><span class="category-def">Function: </span><span><strong class="def-name">conj</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-conj-1'> &para;</a></span></dt>
<dd><p>Compute the complex conjugate of <var class="var">expr</var>.
</p></dd></dl>

<a class="index-entry-id" id="index-xI"></a>
<a class="anchor" id="x_002dxI"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-xI-1"><span class="category-def">Function: </span><span><strong class="def-name">xI</strong> <var class="def-var-arguments">expr</var><a class="copiable-link" href='#index-xI-1'> &para;</a></span></dt>
<dd><p>Compute <code class="code">(0+1j)</code> times <var class="var">expr</var>.
</p></dd></dl>

<a class="index-entry-id" id="index-rel_005ferror"></a>
<a class="anchor" id="x_002drel_002derror"></a><dl class="first-deffn first-defun-alias-first-deffn">
<dt class="deffn defun-alias-deffn" id="index-rel_005ferror-1"><span class="category-def">Function: </span><span><strong class="def-name">rel_error</strong> <var class="def-var-arguments">a b</var><a class="copiable-link" href='#index-rel_005ferror-1'> &para;</a></span></dt>
<dd><p><var class="var">a</var> and <var class="var">b</var> are arbitrary array expressions. Compute the error of <var class="var">a</var> relative to <var class="var">b</var> as
</p>
<p><code class="code">(a==0. &amp;&amp; b==0.) ? 0. : 2.*abs(a, b)/(abs(a)+abs(b))</code>
</p>
</dd></dl>

<a class="index-entry-id" id="index-none-2"></a>
<a class="anchor" id="x_002dnone"></a><dl class="first-deffn">
<dt class="deffn" id="index-none-3"><span class="category-def">Special&nbsp;object<!-- /@w -->: </span><span><strong class="def-name">none</strong><a class="copiable-link" href='#index-none-3'> &para;</a></span></dt>
<dd><p>Pass <code class="code">none</code> to container constructors to indicate that the contents shouldn&rsquo;t be initialized. This is appropriate when the initialization you have in mind wouldn&rsquo;t fit in a constructor argument. For example:
</p>
<div class="example">
<pre class="verbatim">void old_style_initializer(int m, int n, double *);
ra::Big&lt;double&gt; b({2, 3}, ra::none);
old_style_initializer(2, 3, b.data());
</pre></div>

</dd></dl>

<hr>
</div>
<div class="chapter-level-extent" id="Sources">
<div class="nav-panel">
<p>
Next: <a href="#Indices" accesskey="n" rel="next">Indices</a>, Previous: <a href="#Reference" accesskey="p" rel="prev">Reference</a>, Up: <a href="#Top" accesskey="u" rel="up"><code class="code">ra::</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="chapter" id="Sources-1">8 Sources</h2>

<table class="multitable">
<tbody><tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="Abr70"></a>[Abr70]</td><td width="90%">Philip S. Abrams. An APL machine. Technical report SLAC-114 UC-32 (MISC), Stanford Linear Accelerator Center, Stanford University, Stanford, CA, USA, February 1970.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="Ber87"></a>[Ber87]</td><td width="90%">Robert Bernecky. An introduction to function rank. ACM SIGAPL APL Quote Quad, 18(2):39–43, December 1987.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="bli17"></a>[bli17]</td><td width="90%">The Blitz++ meta-template library. <a class="url" href="http://blitz.sourceforge.net">http://blitz.sourceforge.net</a>, November 2017.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="Cha86"></a>[Cha86]</td><td width="90%">Gregory J. Chaitin. Physics in APL2, June 1986.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="FI68"></a>[FI68]</td><td width="90%">Adin D. Falkoff and Kenneth Eugene Iverson. APL\360 User’s manual. IBM Thomas J. Watson Research Center, August 1968.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="FI73"></a>[FI73]</td><td width="90%">Adin D. Falkoff and Kenneth Eugene Iverson. The design of APL. IBM Journal of Research and Development, 17(4):5–14, July 1973.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="FI78"></a>[FI78]</td><td width="90%">Adin D. Falkoff and Kenneth Eugene Iverson. The evolution of APL. ACM SIGAPL APL, 9(1):30– 44, 1978.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="J-S"></a>[J S]</td><td width="90%">J Primer. J Software, <a class="url" href="https://www.jsoftware.com/help/primer/contents.htm">https://www.jsoftware.com/help/primer/contents.htm</a>, November 2017.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="Mat"></a>[Mat]</td><td width="90%">MathWorks. MATLAB documentation, <a class="url" href="https://www.mathworks.com/help/matlab/">https://www.mathworks.com/help/matlab/</a>, November 2017.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="num17"></a>[num17]</td><td width="90%">NumPy. <a class="url" href="http://www.numpy.org">http://www.numpy.org</a>, November 2017.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="Ric08"></a>[Ric08]</td><td width="90%">Henry Rich. J for C programmers, February 2008.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="SSM14"></a>[SSM14]</td><td width="90%">Justin Slepak, Olin Shivers, and Panagiotis Manolios. An array-oriented language with static rank polymorphism. In Z. Shao, editor, ESOP 2014, LNCS 8410, pages 27–46, 2014.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="Vel01"></a>[Vel01]</td><td width="90%">Todd Veldhuizen. Blitz++ user’s guide, February 2001.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><a class="anchor" id="Wad90"></a>[Wad90]</td><td width="90%">Philip Wadler. Deforestation: transforming programs to eliminate trees. Theoretical Computer Science, 73(2): 231&ndash;248, June 1990. <a class="url" href="https://doi.org/10.1016/0304-3975%2890%2990147-A">https://doi.org/10.1016/0304-3975%2890%2990147-A</a></td></tr>
</tbody>
</table>

<hr>
</div>
<div class="unnumbered-level-extent" id="Indices">
<div class="nav-panel">
<p>
Next: <a href="#Notes" accesskey="n" rel="next">Notes</a>, Previous: <a href="#Sources" accesskey="p" rel="prev">Sources</a>, Up: <a href="#Top" accesskey="u" rel="up"><code class="code">ra::</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="unnumbered" id="Indices-1">Indices</h2>

<div class="printindex cp-printindex">
<table class="cp-letters-header-printindex"><tr><th>Jump to: &nbsp; </th><td><a class="summary-letter-printindex" href="#Indices_cp_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-E"><b>E</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-J"><b>J</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-L"><b>L</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-R"><b>R</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-U"><b>U</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-V"><b>V</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-W"><b>W</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-X"><b>X</b></a>
 &nbsp; 
</td></tr></table>
<table class="cp-entries-printindex" border="0">
<tr><td></td><th class="entries-header-printindex">Index Entry</th><td>&nbsp;</td><th class="sections-header-printindex"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-A">A</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-agree"><code class="code">agree</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-agree_005fop"><code class="code">agree_op</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-amax"><code class="code">amax</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-amin"><code class="code">amin</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-any"><code class="code">any</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-APL">APL</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Why-C_002b_002b">Why C++</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-assert">assert</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Functions">Functions</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-at"><code class="code">at</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-B">B</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-BLIS">BLIS</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Compatibility">Compatibility</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-Blitz_002b_002b">Blitz++</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Overview">Overview</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-Blitz_002b_002b-1">Blitz++</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Other-libraries">Other libraries</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-Blitz_002b_002b-2">Blitz++</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Extension">Extension</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-broadcasting_002c-singleton_002c-newaxis">broadcasting, singleton, newaxis</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Rank-extension">Rank extension</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-broadcasting_002c-singleton_002c-Numpy">broadcasting, singleton, Numpy</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Slicing">Slicing</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-built_002din-array">built-in array</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Compatibility">Compatibility</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-C">C</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-cast"><code class="code">cast</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-cell">cell</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Rank-polymorphism">Rank polymorphism</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-collapse"><code class="code">collapse</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-compile_002dtime">compile-time</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Containers-and-views">Containers and views</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-concrete"><code class="code">concrete</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-conj"><code class="code">conj</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-container">container</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Using-the-library">Using the library</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-ct">ct</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Containers-and-views">Containers and views</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-D">D</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-diag"><code class="code">diag</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-E">E</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-early"><code class="code">early</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-elision_002c-index">elision, index</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Slicing">Slicing</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-end_002c-Octave_002fMatlab"><code class="code">end</code>, Octave/Matlab</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Slicing">Slicing</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-error">error</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Functions">Functions</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-every"><code class="code">every</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-explode"><code class="code">explode</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-F">F</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-FFTW">FFTW</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Compatibility">Compatibility</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-foreign-type">foreign type</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Compatibility">Compatibility</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-format_005farray"><code class="code">format_array</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-for_005feach"><code class="code">for_each</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-frame">frame</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Rank-polymorphism">Rank polymorphism</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-from"><code class="code">from</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-G">G</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-Guile">Guile</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Compatibility">Compatibility</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-I">I</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-imag_005fpart"><code class="code">imag_part</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-insert"><code class="code">insert</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Slicing">Slicing</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-iter"><code class="code">iter</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-J">J</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-J">J</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Why-C_002b_002b">Why C++</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-L">L</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-len"><code class="code">len</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Slicing">Slicing</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-length">length</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Overview">Overview</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-M">M</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-map"><code class="code">map</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-N">N</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-none"><code class="code">none</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Containers-and-views">Containers and views</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-none-1"><code class="code">none</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Containers-and-views">Containers and views</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-none-2"><code class="code">none</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-noshape"><code class="code">noshape</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-Numpy">Numpy</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Rank-extension">Rank extension</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-Numpy-1">Numpy</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Rank-extension">Rank extension</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-Numpy-2">Numpy</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Compatibility">Compatibility</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-O">O</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-OpenGL">OpenGL</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Compatibility">Compatibility</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-order_002c-column_002dmajor">order, column-major</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Containers-and-views">Containers and views</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-order_002c-row_002dmajor">order, row-major</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Rank-polymorphism">Rank polymorphism</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-other-libraries_002c-interfacing-with">other libraries, interfacing with</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Compatibility">Compatibility</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-overload-set">overload set</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Extension">Extension</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-P">P</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-pack"><code class="code">pack</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-pick"><code class="code">pick</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-ply"><code class="code">ply</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-prod"><code class="code">prod</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-ptr"><code class="code">ptr</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-Python">Python</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Compatibility">Compatibility</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-R">R</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-rank">rank</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Overview">Overview</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-rank_002c-compile_002dtime">rank, compile-time</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Slicing">Slicing</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-rank_002c-runtime">rank, runtime</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Slicing">Slicing</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-real_005fpart"><code class="code">real_part</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-rel_005ferror"><code class="code">rel_error</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-reverse"><code class="code">reverse</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-rt">rt</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Containers-and-views">Containers and views</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-runtime">runtime</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Containers-and-views">Containers and views</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-S">S</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-scalar"><code class="code">scalar</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-shape">shape</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Overview">Overview</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-shape-1"><code class="code">shape</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-shape-agreement_002c-prefix">shape agreement, prefix</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Rank-extension">Rank extension</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-shape-agreement_002c-suffix">shape agreement, suffix</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Rank-extension">Rank extension</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-size"><code class="code">size</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-sqr"><code class="code">sqr</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-sqrm"><code class="code">sqrm</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-start"><code class="code">start</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Compatibility">Compatibility</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-start-1"><code class="code">start</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-stencil"><code class="code">stencil</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-step">step</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Rank-polymorphism">Rank polymorphism</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-stride">stride</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Rank-polymorphism">Rank polymorphism</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-sum"><code class="code">sum</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-swap"><code class="code">swap</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-T">T</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-transpose"><code class="code">transpose</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-U">U</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-uninitialized-container">uninitialized container</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Containers-and-views">Containers and views</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-uninitialized-container-1">uninitialized container</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Containers-and-views">Containers and views</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-V">V</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-view">view</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Containers-and-views">Containers and views</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-view_002c-rank-0">view, rank 0</a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Slicing">Slicing</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-W">W</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-where"><code class="code">where</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-withshape"><code class="code">withshape</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-wrank"><code class="code">wrank</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-X">X</th><td></td><td></td></tr>
<tr><td></td><td class="printindex-index-entry"><a href="#index-xI"><code class="code">xI</code></a>:</td><td>&nbsp;</td><td class="printindex-index-section"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
</table>
<table class="cp-letters-footer-printindex"><tr><th>Jump to: &nbsp; </th><td><a class="summary-letter-printindex" href="#Indices_cp_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-E"><b>E</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-J"><b>J</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-L"><b>L</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-R"><b>R</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-U"><b>U</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-V"><b>V</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-W"><b>W</b></a>
 &nbsp; 
<a class="summary-letter-printindex" href="#Indices_cp_letter-X"><b>X</b></a>
 &nbsp; 
</td></tr></table>
</div>


<hr>
</div>
<div class="unnumbered-level-extent" id="Notes">
<div class="nav-panel">
<p>
Previous: <a href="#Indices" accesskey="p" rel="prev">Indices</a>, Up: <a href="#Top" accesskey="u" rel="up"><code class="code">ra::</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<h2 class="unnumbered" id="Notes-1">Notes</h2>

<ol class="enumerate">
<li> <code class="code">ra::</code> uses the non standard <code class="code">#pragma once</code> (supported on all major compilers).
</li></ol>

</div>
</div>
<div class="footnotes-segment">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>

<h5 class="footnote-body-heading"><a id="FOOT1" href="#DOCF1">(1)</a></h5>
<p>/ə&rsquo;ɹ-eɪ/, I guess.</p>
<h5 class="footnote-body-heading"><a id="FOOT2" href="#DOCF2">(2)</a></h5>
<p>Sometimes &lsquo;strides&rsquo;. Cf. <a class="url" href="https://en.wikipedia.org/wiki/Dope_vector"><em class="dfn">dope vector</em></a></p>
<h5 class="footnote-body-heading"><a id="FOOT3" href="#DOCF3">(3)</a></h5>
<p>This particular decision may be revisited in the future.</p>
<h5 class="footnote-body-heading"><a id="FOOT4" href="#DOCF4">(4)</a></h5>
<p>Examples given without context assume that one has declared <code class="code">using std::cout;</code>, etc.</p>
<h5 class="footnote-body-heading"><a id="FOOT5" href="#DOCF5">(5)</a></h5>
<p>Diagram generated using Graphviz and <a class="url" href="https://www.flourish.org/cinclude2dot">https://www.flourish.org/cinclude2dot</a>.
</p>
<pre class="verbatim">cd ra &amp;&amp; cinclude2dot.pl --include . &gt; headers.dot
dot -Tpng headers.dot -Gdpi=100 &gt; headers.png
</pre>
<h5 class="footnote-body-heading"><a id="FOOT6" href="#DOCF6">(6)</a></h5>
<p>The brace-list constructors of rank 2 and higher aren&rsquo;t supported on types of rt rank, because in the C++ grammar, a nested initializer list doesn&rsquo;t always define a rank unambiguously.</p>
<h5 class="footnote-body-heading"><a id="FOOT7" href="#DOCF7">(7)</a></h5>
<p>You can still use pointers or <code class="code">std::initializer_list</code>s for shape by wrapping them in the functions <code class="code">ptr</code> or <code class="code">vector</code>, respectively.</p>
<h5 class="footnote-body-heading"><a id="FOOT8" href="#DOCF8">(8)</a></h5>
<p>The brace-list constructors aren&rsquo;t rank extending, because giving the ravel is incompatible with rank extension. They are shape-strict —you must give every element.</p>
<h5 class="footnote-body-heading"><a id="FOOT9" href="#DOCF9">(9)</a></h5>
<p>Prefix agreement is chosen for <code class="code">ra::</code> because of the availability of a <a class="ref" href="#The-rank-conjunction">rank conjunction</a> [<a class="ref" href="#Sources">Ber87</a>]
 and <a class="ref" href="#Cell-iteration">cell iterators of arbitrary rank</a>. This allows rank extension to be performed at multiple axes of an array expression.</p>
<h5 class="footnote-body-heading"><a id="FOOT10" href="#DOCF10">(10)</a></h5>
<p>The multi-argument square bracket form <code class="code">A[i₀, i₁, ...]</code> is supported under C++23 compilers (e.g. gcc ≥ 12 with <code class="code">-std=c++2b</code>), with the same meaning as <code class="code">A(i₀, i₁, ...)</code>. Under C++20 only a single-argument square bracket form <code class="code">A[i₀]</code> is available.</p>
<h5 class="footnote-body-heading"><a id="FOOT11" href="#DOCF11">(11)</a></h5>
<p>Currently, <code class="code">ra::len</code> can only be used in scalar expressions or <code class="code">ra::iota</code> expressions.</p>
<h5 class="footnote-body-heading"><a id="FOOT12" href="#DOCF12">(12)</a></h5>
<p>Simplified; see the references in <a class="url" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1170r0.html">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1170r0.html</a>.</p>
<h5 class="footnote-body-heading"><a id="FOOT13" href="#DOCF13">(13)</a></h5>
<p><code class="code">&amp;&amp;</code>, <code class="code">||</code> are short-circuiting as array operations; the elements of the second operand won&rsquo;t be evaluated if the elements of the first one evaluate to <code class="code">false</code> or <code class="code">true</code>, respectively.
Note that if both operands are of rank 0 and at least one of them is an <code class="code">ra::</code> object, they is no way to preserve the behavior of <code class="code">&amp;&amp;</code> and <code class="code">||</code> with built in types and avoid evaluating both, since the overloaded operators <a class="url" href="http://en.cppreference.com/w/cpp/language/operators">are normal functions</a>.</p>
</div>


<a href="js_licenses.html" rel="jslicense"><small>JavaScript license information</small></a>
</body>
</html>