Subscripts | Raku Documentation

<!DOCTYPE html> <html lang="en" class="fontawesome-i2svg-active fontawesome-i2svg-complete" style="scroll-padding-top:60px"> <head> <title>Subscripts | Raku Documentation</title> <meta charset="UTF-8" /> <link href="/assets/images/Camelia.ico" rel="icon" type="image/x-icon"/> <link rel="stylesheet" href="/assets/css/Website.css"/> <link rel="stylesheet" href="/assets/css/typegraph-styling.css"/> <link rel="stylesheet" href="/assets/css/typegraph-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/typegraph-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/filtered-toc-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/filtered-toc-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/announce-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/announce-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/all.min.css"/> <link rel="stylesheet" href="/assets/css/listf-styling-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/listf-styling-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/options-search-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/options-search-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/page-styling-main.css"/> <link rel="stylesheet" href="/assets/css/css/page-styling-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/page-styling-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/chyronToggle-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/chyronToggle-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/css/centreToggle-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/centreToggle-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/tm-styling.css"/> <link rel="stylesheet" href="/assets/css/tm-light.css" title="light"/> <link rel="stylesheet" href="/assets/css/tm-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/rainbow-dark.css" title="dark"/> <link rel="stylesheet" href="/assets/css/css/rainbow-light.css" title="light"/> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.7/dist/css/autoComplete.min.css" /> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-light.min.css" title="light" /> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css" title="dark" /> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script> <script src="/assets/scripts/all.min.js"></script><script src="/assets/scripts/filter-script.js"></script><script src="/assets/scripts/tableManager.js"></script><script src="https://cdn.jsdelivr.net/npm/fuzzysort@2.0.4/fuzzysort.min.js"></script><script src="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.7/dist/autoComplete.min.js"></script><script src="/assets/scripts/filtered-toc.js"></script><script src="/assets/scripts/options-search.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/haskell.min.js"></script><script src="/assets/scripts/page-styling.js"></script><script src="/assets/scripts/announcements.js"></script><script src="/assets/scripts/rainbow.js"></script> </head> <body class="has-navbar-fixed-top"> <div id="Subscripts" class="top-of-page"></div> <nav class="navbar is-fixed-top is-flex-touch" role="navigation" aria-label="main navigation"> <div class="navbar-item" style="margin-left: auto;"> <div class="left-bar-toggle" title="Toggle Table of Contents & Index"> <label class="chyronToggle left"> <input id="navbar-left-toggle" type="checkbox"> <span class="text">Contents</span> </label> </div> </div> <div class="container is-justify-content-space-around"> <div class="navbar-brand"> <div class="navbar-logo"> <a class="navbar-item" href="/"> <img src="/assets/images/camelia-recoloured.png" alt="Raku" width="52.83" height="38"> </a> <span class="navbar-logo-tm">tm</span> </div> <a role="button" class="navbar-burger burger" aria-label="menu" aria-expanded="false" data-target="navMenu"> <span aria-hidden="true"></span> <span aria-hidden="true"></span> <span aria-hidden="true"></span> </a> </div> <div id="navMenu" class="navbar-menu"> <div class="navbar-start"> <a class="navbar-item" href="/introduction" title="Getting started, Tutorials, Migration guides"> Introduction </a> <a class="navbar-item" href="/reference" title="Fundamentals, General reference"> Reference </a> <a class="navbar-item" href="/miscellaneous" title="Programs, Experimental"> Miscellaneous </a> <a class="navbar-item" href="/types" title="The core types (classes) available"> Types </a> <a class="navbar-item" href="/routines" title="Searchable table of routines"> Routines </a> <a class="navbar-item" href="https://raku.org" title="Home page for community"> Raku<sup>®</sup> </a> <a class="navbar-item" href="https://web.libera.chat/#raku" title="IRC live chat"> Chat </a> <div class="navbar-item has-dropdown is-hoverable"> <a class="navbar-link"> More </a> <div class="navbar-dropdown is-right is-rounded"> <hr class="navbar-divider"> <a class="navbar-item js-modal-trigger" data-target="download-ebook"> Download E-Book (epub) </a> <hr class="navbar-divider"> <a class="navbar-item" href="/about"> About </a> <hr class="navbar-divider"> <a class="navbar-item has-text-red" href="https://github.com/raku/doc-website/issues"> Report an issue with this site </a> <hr class="navbar-divider"> <a class="navbar-item" href="https://github.com/raku/doc/issues"> Report an issue with the documentation content </a> <hr class="navbar-divider"> <label class="navbar-item centreToggle" title="Enable/Disable Announcements" style="--switch-width: 18"> <input id="cancelAnnouncements" type="checkbox"> <span class="text">Announcements</span> <span class="on">suppressed</span> <span class="off">allowed</span> </label> </div> </div> </div> <div class="navbar-end navbar-search-wrapper"> <div class="navbar-item"> <div class="field has-addons"> <div class="autoComplete_options"> <input class="control input" id="autoComplete" type="search" dir="ltr" spellcheck=false autocorrect="off" autocomplete="off" autocapitalize="off" placeholder="🔍 Type f to search for ..."> </div> <div class="control" title="Search options"> <a class="button is-primary js-modal-trigger" data-target="options-search-info"> <span class="icon"> <i class="fas fa-cogs"></i> </span> </a> </div> </div> </div> </div> <div id="options-search-info" class="modal"> <div class="modal-background"></div> <div class="modal-content"> <div class="box"> <p>The last search was: <span id="selected-candidate" class="ss-selected"></span></p> <div class="control is-grouped is-grouped-centered options-search-controls"> <label class="centreToggle" title="Include extra information (Alt-E)" style="--switch-width: 10.5"> <input id="options-search-extra" type="checkbox"> <span class="text">Extra info</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>The search response can be shortened by excluding the extra information line (Alt-E)</p> <label class="centreToggle" title="Search engine type Strict/Loose (Alt-L)" style="--switch-width: 10.5"> <input id="options-search-loose" type="checkbox"> <span class="text">Search type</span> <span class="on">loose</span> <span class="off">strict</span> </label> <p> The search engine can perform a strict search (only the characters in the search box) or a loose search (Alt-L)</p> <label class="centreToggle" title="Search in headings (Alt-H)" style="--switch-width: 10.5"> <input id="options-search-headings" type="checkbox"> <span class="text">Headings</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search through headings in all web-pages (Alt-H)</p> <label class="centreToggle" title="Search indexed items (Alt-I)" style="--switch-width: 10.5"> <input id="options-search-indexed" type="checkbox"> <span class="text">Indexed</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search through all indexed items (Alt-I)</p> <label class="centreToggle" title="Search composite pages (Alt-C)" style="--switch-width: 10.5"> <input id="options-search-composite" type="checkbox"> <span class="text">Composite</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search in the names of composite pages, which combine similar information from the main web pages (Alt-C)</p> <label class="centreToggle" title="Search primary sources (Alt-P)" style="--switch-width: 10.5"> <input id="options-search-primary" type="checkbox"> <span class="text">Primary</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Search through the names of the main web pages (Alt-P)</p> <label class="centreToggle" title="Open in new tab (Alt-Q)" style="--switch-width: 10.5"> <input id="options-search-newtab" type="checkbox"> <span class="text">New tab</span> <span class="on">yes</span> <span class="off">no</span> </label> <p>Once a search candidate has been chosen, it can be opened in a new tab or in the current tab (Alt-Q)</p> <p>If all else fails, an item is added to use the Google search engine on the whole site</p> <button class="button is-warning" id="options-search-reset-defaults">Clear options, reset to defaults</button> <p>Exit this page by pressing <Escape>, or clicking on X or on the background.</p> </div> </div> </div> <button class="modal-close is-large" aria-label="close"></button> </div> </div> <div id="download-ebook" class="modal"> <div class="modal-background"></div> <div class="modal-content"> <div class="box"> <p><a href="/RakuDocumentation.epub" download>RakuDocumentation.epub</a> is a work in progress e-book. It targets the <a href="https://www.w3.org/publishing/epub3/">EPUB v3 specification</a>. It needs testing on a variety of ereaders (some of which may still implicitly expect compliance with EPUB v2). The CSS definitely needs enhancing (especially for code snippets). The Ebook opens in a Calibre reader, which is available on all operating systems.</p> <p>Suggestions are welcome and should be addressed by opening an issue on the Raku/doc-website repository</p> <p>Exit this popup by pressing <Escape>, or clicking on X or on the background.</p> </div> </div> <button class="modal-close is-large" aria-label="close"></button> </div> <div id="announcement-modal" class="modal"> <div class="modal-background"></div> <div class="modal-content"> <div class="box"> <div id="raku-doc-announcement"></div> <p>For more see <a href="/announcements">Announcements page</a>.</p> <p>Exit this popup by pressing <Escape>, or clicking on X or on the background.</p> </div> </div> <button class="modal-close is-large" aria-label="close"></button> </div> </div> </nav> <div class="tile is-ancestor section"> <div class="page-edit"> <a class="button page-edit-button" href="https://github.com/Raku/doc/edit/main/doc/Language/subscripts.rakudoc" title="Edit this page.Commit: 4d4aaa64c 2024-09-07"> <span class="icon is-right"> <i class="fas fa-pen-alt is-medium"></i> </span> </a> </div> <div id="left-column" class="tile is-parent is-2 is-hidden"> <div id="left-col-inner"> <div class="tabs" id="tabs"> <ul> <li class="is-active" id="toc-tab"> <a>Table of Contents</a> </li> <li id="index-tab"> <a>Index</a> </li> </ul> </div> <div class="field"> <div class="control has-icons-right"> <input id="toc-filter" class="input" type="text" placeholder="Filter"> <span class="icon is-right has-text-grey"> <i class="fas fa-search is-medium"></i> </span> </div> </div> <div class="raku-sidebar"> <aside id="toc-menu" class="menu"> <ul class="menu-list"> <li><a href="#Basics">Basics</a></li> <ul> <li><a href="#Positional_subscripting">Positional subscripting</a></li> <li><a href="#Associative_subscripting">Associative subscripting</a></li> <li><a href="#Applying_subscripts">Applying subscripts</a></li> </ul> <li><a href="#Nonexistent_elements">Nonexistent elements</a></li> <li><a href="#From_the_end">From the end</a></li> <li><a href="#Slices">Slices</a></li> <ul> <li><a href="#Truncating_slices">Truncating slices</a></li> <li><a href="#Zen_slices">Zen slices</a></li> </ul> <li><a href="#Multiple_dimensions">Multiple dimensions</a></li> <li><a href="#Modifying_elements">Modifying elements</a></li> <li><a href="#Autovivification">Autovivification</a></li> <li><a href="#Binding">Binding</a></li> <li><a href="#Adverbs">Adverbs</a></li> <ul> <li><a href="#:exists">:exists</a></li> <li><a href="#:delete">:delete</a></li> <li><a href="#:p">:p</a></li> <li><a href="#:kv">:kv</a></li> <li><a href="#:k">:k</a></li> <li><a href="#:v">:v</a></li> </ul> <li><a href="#Custom_types">Custom types</a></li> <ul> <li><a href="#Custom_type_example">Custom type example</a></li> <li><a href="#Methods_to_implement_for_positional_subscripting">Methods to implement for positional subscripting</a></li> <ul> <li><a href="#method_elems">method elems</a></li> <li><a href="#method_AT-POS">method AT-POS</a></li> <li><a href="#method_EXISTS-POS">method EXISTS-POS</a></li> <li><a href="#method_DELETE-POS">method DELETE-POS</a></li> <li><a href="#method_ASSIGN-POS">method ASSIGN-POS</a></li> <li><a href="#method_BIND-POS">method BIND-POS</a></li> <li><a href="#method_STORE">method STORE</a></li> </ul> <li><a href="#Methods_to_implement_for_associative_subscripting">Methods to implement for associative subscripting</a></li> <ul> <li><a href="#method_AT-KEY">method AT-KEY</a></li> <li><a href="#method_EXISTS-KEY">method EXISTS-KEY</a></li> <li><a href="#method_DELETE-KEY">method DELETE-KEY</a></li> <li><a href="#method_ASSIGN-KEY">method ASSIGN-KEY</a></li> <li><a href="#method_BIND-KEY">method BIND-KEY</a></li> <li><a href="#method_STORE_0">method STORE</a></li> </ul> </aside> <aside id="index-menu" class="menu is-hidden"> <ul class="menu-list"> <li>Adverbs<ul> <li><a href="#index-entry-:delete_(subscript_adverb)">:delete </a></li> <li><a href="#index-entry-:exists_(subscript_adverb)">:exists </a></li> <li><a href="#index-entry-:k_(subscript_adverb)">:k </a></li> <li><a href="#index-entry-:kv_(subscript_adverb)">:kv </a></li> <li><a href="#index-entry-:p_(subscript_adverb)">:p </a></li> <li><a href="#index-entry-:v_(subscript_adverb)">:v </a></li> </ul></li> <li>Language<ul> </ul></li> <li>Syntax<ul> <li><a href="#index-entry-flattening_">flattening </a></li> </ul></li> </ul> </aside> </div> </div> </div> <div id="main-column" class="tile is-parent" style="overflow-x: hidden;"> <div id="main-col-inner"> <section class="raku page-header"> <div class="container px-4"> <div class="raku page-title has-text-centered"> Subscripts </div> <div class="raku page-subtitle has-text-centered"> <p>Accessing data structure elements by index or key</p> </div> </div> </section> <section class="raku page-content"><div class="container px-4"><div class="columns one-col"><p>One often needs to refer to a specific element (or slice of elements) from a collection or data structure. Borrowing from mathematical notation where the components of a vector <em>v</em> would be referred to as <em>v₁, v₂, v₃</em>, this concept is called "subscripting" (or "indexing") in Raku.</p> <h1 id="Basics" class="raku-h1"><a href="#Subscripts" title="go to top of document">Basics<a class="raku-anchor" title="direct link" href="#Basics">§</a></a></h1> <p>Raku provides two universal subscripting interfaces:</p><table class="table is-bordered centered pod-table"> <thead> <tr><th></th><th>elements are identified by</th><th>interface name</th><th>supported by</th></tr> </thead> <tbody> <tr><td>[ ]</td><td>zero-based indices</td><td>Positional</td><td>Array, List, Buf, Match, ...</td></tr> <tr><td>{ }</td><td>string or object keys</td><td>Associative</td><td>Hash, Bag, Mix, Match, ...</td></tr> </tbody> </table> <h2 id="Positional_subscripting" class="raku-h2"><a href="#Subscripts" title="go to top of document"><a href="/type/Positional"><code>Positional</code></a> subscripting<a class="raku-anchor" title="direct link" href="#Positional_subscripting">§</a></a></h2> <p><a href="/type/Positional"><code>Positional</code></a> subscripting (via <a href="/language/operators#postcircumfix_[_]"><code>postcircumfix [ ]</code></a>) addresses elements of an ordered collection by their position. Index 0 refers to the first element, index 1 to the second, and so on:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@chores</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">buy groceries</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">feed dog</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">wash car</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@chores</span>[0]; <span class="highlite-COMMENT"># OUTPUT: «buy groceries␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@chores</span>[1]; <span class="highlite-COMMENT"># OUTPUT: «feed dog␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@chores</span>[2]; <span class="highlite-COMMENT"># OUTPUT: «wash car␤»</span></pre> </div> </div> <p>Note that Rakudo's implementation of subscripting allows only 63 bits on 64 bit builds. See <a href="https://stackoverflow.com/questions/61031107/do-array-indices-need-to-be-native-ints/61031617#61031617">Stack Overflow</a>. If larger subscripts are required, one may use <a href="https://raku.land/zef:lizmat/Array::Sparse">Array::Sparse</a> or alternatively, use a <a href="/type/Hash"><code>Hash</code></a> with <a href="/type/Associative"><code>Associative</code></a> subscripting (see below).</p> <h2 id="Associative_subscripting" class="raku-h2"><a href="#Subscripts" title="go to top of document"><a href="/type/Associative"><code>Associative</code></a> subscripting<a class="raku-anchor" title="direct link" href="#Associative_subscripting">§</a></a></h2> <p><a href="/type/Associative"><code>Associative</code></a> subscripting (via <a href="/language/operators#postcircumfix_{_}"><code>postcircumfix { }</code></a>), does not require the collection to keep its elements in any particular order - instead, it uses a unique key to address each value. The nature of the keys depends on the collection in question: For example a standard <a href="/type/Hash"><code>Hash</code></a> uses string keys, whereas a <a href="/type/Mix"><code>Mix</code></a> allows arbitrary objects as keys, etc.:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%grade</span> <span class="highlite-OPERATOR">=</span> Zoe <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">C</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> Ben <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">B+</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%grade</span>{<span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Zoe</span><span class="highlite-STRING_DELIMITER">"</span>}; <span class="highlite-COMMENT"># OUTPUT: «C␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%grade</span>{<span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Ben</span><span class="highlite-STRING_DELIMITER">"</span>}; <span class="highlite-COMMENT"># OUTPUT: «B+␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$stats</span> <span class="highlite-OPERATOR">=</span> ( <span class="highlite-TYPE">Date</span>.<span class="highlite-ROUTINE">today</span> <span class="highlite-OPERATOR">=></span> 4.18<span class="highlite-OPERATOR">,</span> <span class="highlite-TYPE">Date</span>.<span class="highlite-ROUTINE">new</span>(2015<span class="highlite-OPERATOR">,</span> 4<span class="highlite-OPERATOR">,</span> 5) <span class="highlite-OPERATOR">=></span> 17.253 ).<span class="highlite-TYPE">Mix</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$stats</span>{ <span class="highlite-TYPE">Date</span>.<span class="highlite-ROUTINE">new</span>(2015<span class="highlite-OPERATOR">,</span> 4<span class="highlite-OPERATOR">,</span> 4) <span class="highlite-OPERATOR">+</span> 1 }; <span class="highlite-COMMENT"># OUTPUT: «17.253␤»</span></pre> </div> </div> <p>For passing single-word string keys to <code>{ }</code>, you can also use the <a href="/language/quoting#Word_quoting:_qw">angle bracketed word quoting constructs</a> as if they were postcircumfix operators:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%grade</span> <span class="highlite-OPERATOR">=</span> Zoe <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">C</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> Ben <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">B+</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%grade</span><Zoe>; <span class="highlite-COMMENT"># OUTPUT: «C␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%grade</span><Ben>; <span class="highlite-COMMENT"># OUTPUT: «B+␤»</span></pre> </div> </div> <p>This is really just syntactic sugar that gets turned into the corresponding <code>{ }</code> form at compile-time:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-NAME_HASH">%hash</span><foo bar>; <span class="highlite-COMMENT"># same as %hash{ <foo bar> } </span><span class="highlite-NAME_HASH">%hash</span>«foo <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-NAME_SCALAR">$var</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">»</span>; <span class="highlite-COMMENT"># same as %hash{ «foo "$var"» } </span><span class="highlite-NAME_HASH">%hash</span><<foo <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-NAME_SCALAR">$var</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">>></span>; <span class="highlite-COMMENT"># same as %hash{ <<foo "$var">> } </span></pre> </div> </div> <p>You may have noted above that we avoided having to quote <code>Zoe</code> by using the <code>=></code> operator, but that same operator did not just put invisible quotes around <code>Date.new(2015, 4, 5)</code>, and we were able to find the same element using <code>$stats{ Date.new(2015, 4, 4) + 1 }</code>. This is because <code>=></code> only puts invisible quotes around single words, and by "word" we mean an identifier/name. The <code>=></code> operator is there to prevent us from accidentally calling functions or using constants with that name.</p><p>Hash subscripts do not do the same thing as <code>=></code>. The default <a href="/type/Hash"><code>Hash</code></a> has been made to behave the way new users have come to expect from using other languages, and for general ease of use. On a default <a href="/type/Hash"><code>Hash</code></a>, subscripts coerce keys into strings, as long as those keys produce something <a href="/type/Cool"><code>Cool</code></a>. You can use <code>.raku</code> on a collection to be sure whether the keys are strings or objects:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights">( 1 <span class="highlite-OPERATOR">=></span> 1 ).<span class="highlite-ROUTINE">raku</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: «1 => 1␤» </span><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%h</span>; <span class="highlite-NAME_HASH">%h</span>{1} <span class="highlite-OPERATOR">=</span> 1; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%h</span>.<span class="highlite-ROUTINE">raku</span>; <span class="highlite-COMMENT"># OUTPUT: «{ "1" => 1 }␤» </span>( 1/2 <span class="highlite-OPERATOR">=></span> 1 ).<span class="highlite-ROUTINE">raku</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: «0.5 => 1␤» </span><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%h</span>; <span class="highlite-NAME_HASH">%h</span>{1/2} <span class="highlite-OPERATOR">=</span> 1; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%h</span>.<span class="highlite-ROUTINE">raku</span>; <span class="highlite-COMMENT"># OUTPUT: «{ "0.5" => 1 }␤» </span>( pi <span class="highlite-OPERATOR">=></span> 1 ).<span class="highlite-ROUTINE">raku</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: «:pi(1)␤» </span><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%h</span>; <span class="highlite-NAME_HASH">%h</span>{pi} <span class="highlite-OPERATOR">=</span> 1; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%h</span>.<span class="highlite-ROUTINE">raku</span>; <span class="highlite-COMMENT"># OUTPUT: «{ "3.14159265358979" => 1 }␤»</span></pre> </div> </div> <p>While the invisible quotes around single names is built into <code>=></code>, string conversion is not built into the curly braces: it is a behavior of the default <a href="/type/Hash"><code>Hash</code></a>. Not all types of hashes or collections do so:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%h</span> <span class="highlite-OPERATOR">:=</span> <span class="highlite-TYPE">MixHash</span>.<span class="highlite-ROUTINE">new</span>; <span class="highlite-NAME_HASH">%h</span>{pi} <span class="highlite-OPERATOR">=</span> 1; <span class="highlite-NAME_HASH">%h</span>.<span class="highlite-ROUTINE">raku</span>.<span class="highlite-ROUTINE">say</span>; <span class="highlite-COMMENT"># OUTPUT: «(3.14159265358979e0=>1).MixHash␤» </span></pre> </div> </div> <p>(Any name that <code>=></code> would convert to a string can also be used to build a pair using "adverbial notation" and will appear that way when viewed through <code>.raku</code>, which is why we see <code>:pi(1)</code> above.)</p> <h2 id="Applying_subscripts" class="raku-h2"><a href="#Subscripts" title="go to top of document">Applying subscripts<a class="raku-anchor" title="direct link" href="#Applying_subscripts">§</a></a></h2> <p>Subscripts can be applied to any expression that returns a subscriptable object, not just to variables:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">__Hello__</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-ROUTINE">match</span>(<span class="highlite-REGEX_DELIMITER">/</span><span class="highlite-REGEX_LITERAL">__</span><span class="highlite-REGEX_SPECIAL">(.*)</span><span class="highlite-REGEX_LITERAL">__</span><span class="highlite-REGEX_DELIMITER">/</span>)[0]; <span class="highlite-COMMENT"># OUTPUT: «｢Hello｣␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">__Hello__</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-ROUTINE">match</span>(<span class="highlite-REGEX_DELIMITER">/</span><span class="highlite-REGEX_LITERAL">__</span><span class="highlite-REGEX_SPECIAL">(.*)</span><span class="highlite-REGEX_LITERAL">__</span><span class="highlite-REGEX_DELIMITER">/</span>)<span class="highlite-OPERATOR">.</span>[0]; <span class="highlite-COMMENT"># same, in method notation</span></pre> </div> </div> <p>Positional and associative subscripting are not mutually exclusive - for example, <a href="/type/Match"><code>Match</code></a> objects support both (each accessing a different set of data). Also, to make list processing more convenient, class <a href="/type/Any"><code>Any</code></a> provides a fallback implementation for positional subscripts which simply treats the invocant as a list of one element. (But there's no such fallback for associative subscripts, so they throw a runtime error when applied to an object that does not implement support for them.)</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> 42[0]; <span class="highlite-COMMENT"># OUTPUT: «42␤» </span><span class="highlite-ROUTINE">say</span> 42<foo>; <span class="highlite-COMMENT"># ERROR: Type Int does not support associative indexing. </span></pre> </div> </div> <h1 id="Nonexistent_elements" class="raku-h1"><a href="#Subscripts" title="go to top of document">Nonexistent elements<a class="raku-anchor" title="direct link" href="#Nonexistent_elements">§</a></a></h1> <p>What happens when a <em>nonexistent</em> element is addressed by a subscript is up to the collection type in question. Standard <a href="/type/Array"><code>Array</code></a> and <a href="/type/Hash"><code>Hash</code></a> collections return the type object of their <a href="/routine/of">value type constraint</a> (which, by default, is <a href="/type/Any"><code>Any</code></a>) unless the collection has been declared with the <a href="/type/Variable#trait_is_default"><code>is default</code></a> trait in which case the returned value will be whatever the programmer declared it to be:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-COMMENT"># no default values specified </span><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@array1</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@array1</span>[10]; <span class="highlite-COMMENT"># OUTPUT: «(Any)␤» </span><span class="highlite-KEYWORD">my</span> <span class="highlite-TYPE">Int</span> <span class="highlite-NAME_ARRAY">@array2</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@array2</span>[10]; <span class="highlite-COMMENT"># OUTPUT: «(Int)␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%hash1</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%hash1</span><foo>; <span class="highlite-COMMENT"># OUTPUT: «(Any)␤» </span><span class="highlite-KEYWORD">my</span> <span class="highlite-TYPE">Int</span> <span class="highlite-NAME_HASH">%hash2</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%hash2</span><foo>; <span class="highlite-COMMENT"># OUTPUT: «(Int)␤» </span> <span class="highlite-COMMENT"># default values specified </span><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@array3</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">default</span>(<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">--</span><span class="highlite-STRING_DELIMITER">'</span>); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@array3</span>[10]; <span class="highlite-COMMENT"># OUTPUT: «--␤» </span><span class="highlite-KEYWORD">my</span> <span class="highlite-TYPE">Int</span> <span class="highlite-NAME_ARRAY">@array4</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">default</span>(17); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@array4</span>[10]; <span class="highlite-COMMENT"># OUTPUT: «17␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%hash3</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">default</span>(<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Empty</span><span class="highlite-STRING_DELIMITER">'</span>); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%hash3</span><foo>; <span class="highlite-COMMENT"># OUTPUT: «Empty␤» </span><span class="highlite-KEYWORD">my</span> <span class="highlite-TYPE">Int</span> <span class="highlite-NAME_HASH">%hash4</span> <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">default</span>(4711); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%hash4</span><foo>; <span class="highlite-COMMENT"># OUTPUT: «4711␤»</span></pre> </div> </div> <p>However, other types of collections may react differently to subscripts that address nonexistent elements:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> (0<span class="highlite-OPERATOR">,</span> 10<span class="highlite-OPERATOR">,</span> 20)[3]; <span class="highlite-COMMENT"># OUTPUT: «Nil␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-ROUTINE">bag</span>(<span class="highlite-STRING_DELIMITER"><</span><span class="highlite-STRING">a a b b b</span><span class="highlite-STRING_DELIMITER">></span>)<c>; <span class="highlite-COMMENT"># OUTPUT: «0␤» </span><span class="highlite-ROUTINE">say</span> array[<span class="highlite-TYPE">uint8</span>].<span class="highlite-ROUTINE">new</span>(1<span class="highlite-OPERATOR">,</span> 2)[2] <span class="highlite-COMMENT"># OUTPUT: «0␤»</span></pre> </div> </div> <p>To silently skip nonexistent elements in a subscripting operation, see <a href="#Truncating_slices">Truncating slices</a> and the <a href="#:v"><code>:v</code></a> adverb.</p> <h1 id="From_the_end" class="raku-h1"><a href="#Subscripts" title="go to top of document">From the end<a class="raku-anchor" title="direct link" href="#From_the_end">§</a></a></h1> <p>Positional indices are counted from the start of the collection, but there's also a notation for addressing elements by their position relative to the end: <code>*-1</code> refers to the last element, <code>*-2</code> to the second-to-last element, and so on. From version 6.d, <code>*-0</code> refers to the element just beyond the last one</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@alphabet</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">A</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">..</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Z</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[*-1]; <span class="highlite-COMMENT"># OUTPUT: «Z␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[*-2]; <span class="highlite-COMMENT"># OUTPUT: «Y␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[*-3]; <span class="highlite-COMMENT"># OUTPUT: «X␤» </span><span class="highlite-NAME_ARRAY">@alphabet</span>[*-0] <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">þ</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>; <span class="highlite-COMMENT"># OUTPUT: «[A B C D E F G H I J K L M N O P Q R S T U V W X Y Z þ]␤»</span></pre> </div> </div> <p><strong>Note</strong>: The asterisk, which is actually a <a href="/type/Whatever"><code>Whatever</code></a>, is important. Passing a bare negative integer (e.g. <code>@alphabet[-1]</code>) like you would do in many other programming languages, throws an error in Raku.</p><p>What actually happens here, is that an expression like <code>*-1</code> declares a code object via <a href="/type/Whatever"><code>Whatever</code></a>-priming - and the <code>[ ]</code> subscript reacts to being given a code object as an index, by calling it with the length of the collection as argument and using the result value as the actual index. In other words, <code>@alphabet[*-1]</code> becomes <code>@alphabet[@alphabet.elems - 1]</code>.</p><p>This means that you can use arbitrary expressions which depend on the size of the collection:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@array</span>[<span class="highlite-OPERATOR">*</span> <span class="highlite-OPERATOR">div</span> 2]; <span class="highlite-COMMENT"># select the middlemost element </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@array</span>[<span class="highlite-NAME_SCALAR">$i</span> <span class="highlite-OPERATOR">%</span> <span class="highlite-OPERATOR">*</span>]; <span class="highlite-COMMENT"># wrap around a given index ("modular arithmetic") </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@array</span>[ <span class="highlite-KEYWORD">-></span> <span class="highlite-NAME_SCALAR">$size</span> { <span class="highlite-NAME_SCALAR">$i</span> <span class="highlite-OPERATOR">%</span> <span class="highlite-NAME_SCALAR">$size</span> } ]; <span class="highlite-COMMENT"># same as previous </span></pre> </div> </div> <h1 id="Slices" class="raku-h1"><a href="#Subscripts" title="go to top of document">Slices<a class="raku-anchor" title="direct link" href="#Slices">§</a></a></h1> <p>When multiple elements of a collection need to be accessed, there's a shortcut to doing multiple separate subscripting operations: Simply specify a <em>list</em> of indices/keys in the subscript, to get back a <em>list</em> of elements - also called a "slice" - in the same order.</p><p>For positional slices, you can mix normal indices with <a href="#From_the_end">from-the-end</a> ones:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@alphabet</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">a</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">..</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">z</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[15<span class="highlite-OPERATOR">,</span> 4<span class="highlite-OPERATOR">,</span> *-9<span class="highlite-OPERATOR">,</span> 11].<span class="highlite-ROUTINE">raku</span>; <span class="highlite-COMMENT"># OUTPUT: «("p", "e", "r", "l")␤»</span></pre> </div> </div> <p>In the <code>*-number</code> construct above, <code>*</code> indicates the end of the array as explained above in the <a href="#From_the_end">From the end</a> section. So if you want to take the last N elements of the array, you will have to create a <a href="/type/Range"><code>Range</code></a> that includes it.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights">(5802..5830).<span class="highlite-ROUTINE">map</span>( {.<span class="highlite-ROUTINE">chr</span>} )[*-10..*-5] <span class="highlite-COMMENT"># OUTPUT: «(ᚽ ᚾ ᚿ ᛀ ᛁ ᛂ)␤»</span></pre> </div> </div> <p>Using <code>*</code> as the last element of the range will, effectively, return the last elements of the collection.</p><p>For associative slices, the angle brackets form often comes in handy:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%color</span> <span class="highlite-OPERATOR">=</span> kiwi <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">green</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> banana <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">yellow</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> cherry <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">red</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%color</span>{<span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">cherry</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">kiwi</span><span class="highlite-STRING_DELIMITER">"</span>}; <span class="highlite-COMMENT"># OUTPUT: «(red green)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%color</span><cherry kiwi>; <span class="highlite-COMMENT"># OUTPUT: «(red green)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%color</span>{<span class="highlite-OPERATOR">*</span>}; <span class="highlite-COMMENT"># OUTPUT: «(red yellow green)␤»</span></pre> </div> </div> <p>Be aware that slices are controlled by the <em>type</em> of what is passed to (<a href="#Multiple_dimensions">one dimension of</a>) the subscript, not its length. In particular the <em>type</em> can be any of the following:</p> <ul class="rakudoc-item"> <li><p>a lazy Iterable, that <a href="#Truncating_slices">truncates</a> in [ ]</p></li> <li><p>accordingly, an infinite Range will truncate, but a finite one produces a normal slice</p></li> <li><p>'*' (whatever-star), that returns the full slice (as if all keys/indices were specified)</p></li> <li><p>'**' (hyperwhatever-star), that returns the full slice (as if all keys/indices were specified), with any lists flattened recursively (since Rakudo Release 2024.08)</p></li> <li><p>any other object, that provides a single-element access rather than a slice</p></li> <li><p>Callable, whatever is returned by the callable (this can lead to recursion)</p></li> <li><p>empty, the full slice known as <a href="#Zen_slices">Zen slice</a></p></li> <li><p>any iterable different from the above ones, normal slice</p></li> </ul> <p>The notable difference between <code>*</code> and Zen slice (empty) is that the <a href="/type/Whatever"><code>Whatever</code></a> star will cause full <a href="/language/glossary#Reify">reification</a> or itemization, while Zen slice won't. Both versions also <a href="https://perl6advent.wordpress.com/2017/12/02/perl-6-sigils-variables-and-containers/#decont">de-cont</a>.</p><p>So even a one-element list returns a slice, whereas a bare scalar value doesn't:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[2<span class="highlite-OPERATOR">,</span>]; <span class="highlite-COMMENT"># OUTPUT: «(c)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[2<span class="highlite-OPERATOR">,</span>].^<span class="highlite-ROUTINE">name</span>; <span class="highlite-COMMENT"># OUTPUT: «List␤» </span> <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[2]; <span class="highlite-COMMENT"># OUTPUT: «c␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[2].^<span class="highlite-ROUTINE">name</span>; <span class="highlite-COMMENT"># OUTPUT: «Str␤» </span></pre> </div> </div> <p>(The angle bracket form for associative subscripts works out because <a href="/language/quoting#Word_quoting:_qw">word quoting</a> conveniently returns a <a href="/type/Str"><code>Str</code></a> in case of a single word, but a <a href="/type/List"><code>List</code></a> in case of multiple words.)</p><p>In fact, the list structure of (<a href="#Multiple_dimensions">the current dimension of</a>) the subscript is preserved across the slice operation (but the kind of Iterable is not – the result is always just lists.)</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[0<span class="highlite-OPERATOR">,</span> (1..2<span class="highlite-OPERATOR">,</span> (3<span class="highlite-OPERATOR">,</span>))]; <span class="highlite-COMMENT"># OUTPUT: «(a ((b c) (d)))␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[0<span class="highlite-OPERATOR">,</span> (1..2<span class="highlite-OPERATOR">,</span> [3<span class="highlite-OPERATOR">,</span>])]; <span class="highlite-COMMENT"># OUTPUT: «(a ((b c) (d)))␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[<span class="highlite-ROUTINE">flat</span> 0<span class="highlite-OPERATOR">,</span> (1..2<span class="highlite-OPERATOR">,</span> (3<span class="highlite-OPERATOR">,</span>))]; <span class="highlite-COMMENT"># OUTPUT: «(a b c d)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-ROUTINE">flat</span> <span class="highlite-NAME_ARRAY">@alphabet</span>[0<span class="highlite-OPERATOR">,</span> (1..2<span class="highlite-OPERATOR">,</span> (3<span class="highlite-OPERATOR">,</span>))]; <span class="highlite-COMMENT"># OUTPUT: «(a b c d)␤» </span></pre> </div> </div> <h2 id="Truncating_slices" class="raku-h2"><a href="#Subscripts" title="go to top of document">Truncating slices<a class="raku-anchor" title="direct link" href="#Truncating_slices">§</a></a></h2> <p>Referring to nonexistent elements in a slice subscript causes the output <a href="/type/List"><code>List</code></a> to contain undefined values (or <a href="#Nonexistent_elements">whatever else</a> the collection in question chooses to return for nonexistent elements):</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@letters</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER"><</span><span class="highlite-STRING">a b c d e f</span><span class="highlite-STRING_DELIMITER">></span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@letters</span>[3..7]; <span class="highlite-COMMENT"># OUTPUT: «(d e f (Any) (Any))␤» </span></pre> </div> </div> <p>This behavior, while at first glance may seem unintuitive, is desirable in instances when you want to assign a value at an index in which a value does not currently exist.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@letters</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@letters</span>; <span class="highlite-COMMENT"># OUTPUT: «[]␤» </span> <span class="highlite-NAME_ARRAY">@letters</span>[^10] <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">a</span><span class="highlite-STRING_DELIMITER">'</span>..<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">z</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@letters</span>; <span class="highlite-COMMENT"># OUTPUT: «[a b c d e f g h i j]␤» </span></pre> </div> </div> <p>If you want the resulting slice to only include existing elements, you can silently skip the non-existent elements using the <a href="#:v"><code>:v</code></a> adverb.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@letters</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER"><</span><span class="highlite-STRING">a b c d e f</span><span class="highlite-STRING_DELIMITER">></span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@letters</span>[3..7]:v; <span class="highlite-COMMENT"># OUTPUT: «(d e f)␤» </span></pre> </div> </div> <p>The behavior when indexing a collection via <a href="/language/list#Lazy_lists">lazy</a> subscripts is different than when indexing with their eager counterparts. When accessing via a lazy subscript, the resulting slice will be truncated.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@letters</span>[<span class="highlite-ROUTINE">lazy</span> 3..7]; <span class="highlite-COMMENT"># OUTPUT: «(d e f)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@letters</span>[ 3.<span class="highlite-OPERATOR">.*</span>]; <span class="highlite-COMMENT"># OUTPUT: «(d e f)␤» </span></pre> </div> </div> <p>This behavior exists as a precaution to prevent runaway generation of massive, potentially infinite <a href="/type/List"><code>List</code></a>s and the out-of-memory issues that occur as a result.</p> <h2 id="Zen_slices" class="raku-h2"><a name="index-entry-Zen_slices-Zen_slices" data-indexedheader="Language;Zen slices"></a><a href="#Subscripts" title="go to top of document">Zen slices<a class="raku-anchor" title="direct link" href="#Zen_slices">§</a></a></h2>  <p>If you put the subscript operator behind an object without specifying any indices/keys at all, it simply returns the subscripted object itself. Since it is empty but returns everything, it is known as a <em>Zen slice</em>.</p><p>Zen slicing is different from passing a <a href="/type/Whatever"><code>Whatever</code></a>-star (which, like a normal slice, always returns a List of elements no matter the type of the original object) or an empty list (which returns an empty slice):</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%bag</span> <span class="highlite-OPERATOR">:=</span> (orange <span class="highlite-OPERATOR">=></span> 1<span class="highlite-OPERATOR">,</span> apple <span class="highlite-OPERATOR">=></span> 3).<span class="highlite-TYPE">Bag</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%bag</span><<span class="highlite-OPERATOR">></span>; <span class="highlite-COMMENT"># OUTPUT: «Bag(apple(3) orange)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%bag</span>{}; <span class="highlite-COMMENT"># OUTPUT: «Bag(apple(3) orange)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%bag</span>{<span class="highlite-OPERATOR">*</span>}; <span class="highlite-COMMENT"># OUTPUT: «(1 3)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%bag</span>{()}; <span class="highlite-COMMENT"># OUTPUT: «()␤»</span></pre> </div> </div> <p>Zen slicing does not <a href="/language/glossary#Reify">reify</a> or <a href="/routine/cache">cache</a> (not even <a href="/type/Seq"><code>Seq</code></a>s) and merely returns the invocant. It is usually used to <a href="/language/quoting#Interpolation:_qq">interpolate</a> entire arrays / hashes into strings or to <a href="/language/glossary#decont">decont</a>.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@words</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">cruel</span><span class="highlite-STRING_DELIMITER">"</span><span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">world</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Hello, </span><span class="highlite-NAME_ARRAY">@words</span><span class="highlite-STRING">[]!</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-COMMENT"># OUTPUT: «Hello, cruel world!␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$list</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER"><</span><span class="highlite-STRING">a b c</span><span class="highlite-STRING_DELIMITER">></span>; .<span class="highlite-ROUTINE">say</span> <span class="highlite-KEYWORD">for</span> <span class="highlite-NAME_SCALAR">$list</span>; <span class="highlite-COMMENT"># OUTPUT: «(a b c)␤» </span>.<span class="highlite-ROUTINE">say</span> <span class="highlite-KEYWORD">for</span> <span class="highlite-NAME_SCALAR">$list</span><<span class="highlite-OPERATOR">></span>; <span class="highlite-COMMENT"># OUTPUT: «a␤b␤c␤» </span>.<span class="highlite-ROUTINE">say</span> <span class="highlite-KEYWORD">for</span> <span class="highlite-NAME_SCALAR">$list</span>[]; <span class="highlite-COMMENT"># OUTPUT: «a␤b␤c␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@fib</span> <span class="highlite-OPERATOR">=</span> 1,1<span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">*</span> <span class="highlite-OPERATOR">+</span> <span class="highlite-OPERATOR">*</span> <span class="highlite-OPERATOR">…</span> <span class="highlite-OPERATOR">*</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@fib</span>[]; <span class="highlite-COMMENT"># OUTPUT: «[...]␤»</span></pre> </div> </div> <h1 id="Multiple_dimensions" class="raku-h1"><a href="#Subscripts" title="go to top of document">Multiple dimensions<a class="raku-anchor" title="direct link" href="#Multiple_dimensions">§</a></a></h1> <p>Dimensions in subscripts are separated by a semicolon, allowing to mix lists of elements and dimensions.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@twodim</span> <span class="highlite-OPERATOR">=</span> (<span class="highlite-STRING_DELIMITER"><</span><span class="highlite-STRING">a b c</span><span class="highlite-STRING_DELIMITER">></span><span class="highlite-OPERATOR">,</span> (1<span class="highlite-OPERATOR">,</span> 2<span class="highlite-OPERATOR">,</span> 3)); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@twodim</span>; <span class="highlite-COMMENT"># OUTPUT: «[(a b c) (1 2 3)]␤» </span> <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@twodim</span>[0,1;1]; <span class="highlite-COMMENT"># 2nd element of both lists </span><span class="highlite-COMMENT"># OUTPUT: «(b 2)␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%pantheon</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-OPERATOR">%</span>(<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Baldr</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">consort</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Nanna</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Bragi</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">consort</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Iðunn</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Nótt</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">consort</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Dellingr</span><span class="highlite-STRING_DELIMITER">'</span> ); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%pantheon</span>{<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Bragi</span><span class="highlite-STRING_DELIMITER">'</span>,<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Nótt</span><span class="highlite-STRING_DELIMITER">'</span>;<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">consort</span><span class="highlite-STRING_DELIMITER">'</span>}; <span class="highlite-COMMENT"># 'consort' value for both keys </span><span class="highlite-COMMENT"># OUTPUT: «(Iðunn Dellingr)␤»</span></pre> </div> </div> <p><a name="index-entry-flattening_" class="index-entry"></a></p><p>Multidimensional subscripts can be used to flatten nested lists when combined with <a href="/type/Whatever"><code>Whatever</code></a>.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@toomany</span> <span class="highlite-OPERATOR">=</span> [[<a b>]<span class="highlite-OPERATOR">,</span> [1<span class="highlite-OPERATOR">,</span> 2]]; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@toomany</span>; <span class="highlite-COMMENT"># OUTPUT: «[[a b] [1 2]]␤» </span> <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@toomany</span>[<span class="highlite-OPERATOR">*</span>;<span class="highlite-OPERATOR">*</span>]; <span class="highlite-COMMENT"># OUTPUT: «(a b 1 2)␤»</span></pre> </div> </div> <p>You can use as many <em>flattening semicolons</em> as you want; there will be, at most, as many nesting levels flattened as the number of semicolons:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> [[1,2<span class="highlite-OPERATOR">,</span>[3,4]]<span class="highlite-OPERATOR">,</span>[4,5]][<span class="highlite-OPERATOR">*</span>;<span class="highlite-OPERATOR">*</span>]; <span class="highlite-COMMENT"># OUTPUT: «(1 2 [3 4] 4 5)␤» </span><span class="highlite-ROUTINE">say</span> [[1,2<span class="highlite-OPERATOR">,</span>[3,4]]<span class="highlite-OPERATOR">,</span>[4,5]][<span class="highlite-OPERATOR">*</span>;<span class="highlite-OPERATOR">*</span>;<span class="highlite-OPERATOR">*</span>;<span class="highlite-OPERATOR">*</span>]; <span class="highlite-COMMENT"># OUTPUT: «(1 2 3 4 4 5)␤»</span></pre> </div> </div> <p>In the first example, with one <a href="/type/Whatever"><code>Whatever</code></a> less than the number of levels, the deepest one will not be flattened; in the second case it is, since it's greater than the number of levels.</p><p>You can use <a href="/type/Whatever"><code>Whatever</code></a> to select ranges or "rows" in multidimensional subscripts.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@a</span> <span class="highlite-OPERATOR">=</span> [[1,2]<span class="highlite-OPERATOR">,</span> [3,4]]; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@a</span>[<span class="highlite-OPERATOR">*</span>;1]; <span class="highlite-COMMENT"># 2nd element of each sub list </span><span class="highlite-COMMENT"># OUTPUT: «(2 4)␤» </span><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@a</span> <span class="highlite-OPERATOR">=</span> (<span class="highlite-STRING_DELIMITER"><</span><span class="highlite-STRING">1 c 6</span><span class="highlite-STRING_DELIMITER">></span><span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER"><</span><span class="highlite-STRING">2 a 4</span><span class="highlite-STRING_DELIMITER">></span><span class="highlite-OPERATOR">,</span> <span class="highlite-STRING_DELIMITER"><</span><span class="highlite-STRING">5 b 3</span><span class="highlite-STRING_DELIMITER">></span>); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@a</span>.<span class="highlite-ROUTINE">sort</span>( { <span class="highlite-NAME_SCALAR">$_</span>[1] } ); <span class="highlite-COMMENT"># sort by 2nd column </span><span class="highlite-COMMENT"># OUTPUT: «((2 a 4) (5 b 3) (1 c 6))␤»</span></pre> </div> </div> <h1 id="Modifying_elements" class="raku-h1"><a href="#Subscripts" title="go to top of document">Modifying elements<a class="raku-anchor" title="direct link" href="#Modifying_elements">§</a></a></h1> <h1 id="Autovivification" class="raku-h1"><a href="#Subscripts" title="go to top of document">Autovivification<a class="raku-anchor" title="direct link" href="#Autovivification">§</a></a></h1> <p>Subscripts participate in "autovivification", i.e. the process by which arrays and hashes automatically spring into existence when needed, so that you can build nested data structures without having to pre-declare the collection type at each level:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$beatles</span>; <span class="highlite-NAME_SCALAR">$beatles</span>{<span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">White Album</span><span class="highlite-STRING_DELIMITER">"</span>}[0] <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Back in the U.S.S.R.</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-COMMENT"># autovivification! </span> <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$beatles</span>.<span class="highlite-ROUTINE">raku</span>; <span class="highlite-COMMENT"># OUTPUT: «${"White Album" => $["Back in the U.S.S.R."]}␤» </span></pre> </div> </div> <p><code>$beatles</code> started out undefined, but became a <a href="/type/Hash"><code>Hash</code></a> object because it was subscripted with <code>{ }</code> in the assignment. Similarly, <code>$beatles{"White Album"}</code> became an <a href="/type/Array"><code>Array</code></a> object due to being subscripted with <code>[ ]</code> in the assignment.</p><p>Note that the subscripting itself does not cause autovivification: It only happens when the result of the subscripting chain is <em>assigned</em> to (or otherwise mutated).</p> <h1 id="Binding" class="raku-h1"><a href="#Subscripts" title="go to top of document">Binding<a class="raku-anchor" title="direct link" href="#Binding">§</a></a></h1> <p>A subscripting expression may also be used as the left-hand-side of a binding statement. If supported by the subscripted collection's type, this replaces whatever value container would be naturally found at that "slot" of the collection, with the specified container.</p><p>The built-in <a href="/type/Array"><code>Array</code></a> and <a href="/type/Hash"><code>Hash</code></a> types support this in order to allow building complex linked data structures:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@a</span> <span class="highlite-OPERATOR">=</span> 10<span class="highlite-OPERATOR">,</span> 11<span class="highlite-OPERATOR">,</span> 12<span class="highlite-OPERATOR">,</span> 13; <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$x</span> <span class="highlite-OPERATOR">=</span> 1; <span class="highlite-NAME_ARRAY">@a</span>[2] <span class="highlite-OPERATOR">:=</span> <span class="highlite-NAME_SCALAR">$x</span>; <span class="highlite-COMMENT"># Bound! (@a[2] and $x refer to the same container now.) </span> <span class="highlite-NAME_SCALAR">$x</span>+<span class="highlite-OPERATOR">+</span>; <span class="highlite-NAME_ARRAY">@a</span>[2]<span class="highlite-OPERATOR">++</span>; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@a</span>; <span class="highlite-COMMENT"># OUTPUT: «[10 11 3 13]␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$x</span>; <span class="highlite-COMMENT"># OUTPUT: «3␤»</span></pre> </div> </div> <p>This can be specially useful when lazy data structures are part of a bigger one.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@fib</span> <span class="highlite-OPERATOR">=</span> 1,1<span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">*</span> <span class="highlite-OPERATOR">+</span> <span class="highlite-OPERATOR">*</span> <span class="highlite-OPERATOR">…</span> ∞; <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@lucas</span> <span class="highlite-OPERATOR">=</span> 1,3<span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">*</span> <span class="highlite-OPERATOR">+</span> <span class="highlite-OPERATOR">*</span> <span class="highlite-OPERATOR">…</span> ∞; <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%sequences</span>; <span class="highlite-NAME_HASH">%sequences</span><<span class="highlite-ROUTINE">f</span>> <span class="highlite-OPERATOR">:=</span> <span class="highlite-NAME_ARRAY">@fib</span>; <span class="highlite-NAME_HASH">%sequences</span><<span class="highlite-ROUTINE">l</span>> <span class="highlite-OPERATOR">:=</span> <span class="highlite-NAME_ARRAY">@lucas</span>; <span class="highlite-KEYWORD">for</span> <span class="highlite-NAME_HASH">%sequences</span>.<span class="highlite-ROUTINE">keys</span> <span class="highlite-KEYWORD">-></span> <span class="highlite-NAME_SCALAR">$s</span> { <span class="highlite-KEYWORD">for</span> ^10 <span class="highlite-KEYWORD">-></span> <span class="highlite-NAME_SCALAR">$n</span> { <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%sequences</span>{<span class="highlite-NAME_SCALAR">$s</span>}[100+<span class="highlite-NAME_SCALAR">$n</span>*10]<span class="highlite-OPERATOR">/</span><span class="highlite-NAME_HASH">%sequences</span>{<span class="highlite-NAME_SCALAR">$s</span>}[101+<span class="highlite-NAME_SCALAR">$n</span>*10]; } } <span class="highlite-COMMENT"># OUTPUT: 0.6180339887498949 times 20. </span></pre> </div> </div> <p>In this case, hash keys are bound to lazily generated sequences. The fact that they are bound means that whatever state has been computed is shared by the hash value and the sequence it's bound to, making computations of subsequent elements faster.</p><p>See <a href="#method_BIND-POS">method <code>BIND-POS</code></a> and <a href="#method_BIND-KEY">method <code>BIND-KEY</code></a> for the underlying mechanism.</p> <h1 id="Adverbs" class="raku-h1"><a href="#Subscripts" title="go to top of document">Adverbs<a class="raku-anchor" title="direct link" href="#Adverbs">§</a></a></h1> <p>The return value and possible side-effect of a subscripting operation can be controlled using adverbs; these are defined on the relevant subscript <a href="/language/operators#Method_postfix_precedence">operators</a>.</p><p>Beware of the relatively loose precedence of operator adverbs, which may require you to add parentheses in compound expressions:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">if</span> <span class="highlite-NAME_SCALAR">$foo</span> <span class="highlite-OPERATOR">||</span> <span class="highlite-NAME_HASH">%hash</span><<span class="highlite-ROUTINE">key</span>>:exists { <span class="highlite-OPERATOR">...</span> } <span class="highlite-COMMENT"># WRONG, tries to adverb the || op </span></pre> </div> </div> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">if</span> <span class="highlite-NAME_SCALAR">$foo</span> <span class="highlite-OPERATOR">||</span> (<span class="highlite-NAME_HASH">%hash</span><<span class="highlite-ROUTINE">key</span>>:exists) { <span class="highlite-OPERATOR">...</span> } <span class="highlite-COMMENT"># correct </span><span class="highlite-KEYWORD">if</span> <span class="highlite-NAME_SCALAR">$foo</span> <span class="highlite-OPERATOR">or</span> <span class="highlite-NAME_HASH">%hash</span><<span class="highlite-ROUTINE">key</span>>:exists { <span class="highlite-OPERATOR">...</span> } <span class="highlite-COMMENT"># also correct </span></pre> </div> </div> <p>The supported adverbs are:</p><p><a name="index-entry-:exists_(subscript_adverb)" class="index-entry"></a></p> <h2 id=":exists" class="raku-h2"><a href="#Subscripts" title="go to top of document"><code>:exists</code><a class="raku-anchor" title="direct link" href="#:exists">§</a></a></h2> <p>Returns whether or not the requested element exists, instead of returning the element's actual value. This can be used to distinguish between elements with an undefined value, and elements that aren't part of the collection at all:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@foo</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-TYPE">Any</span><span class="highlite-OPERATOR">,</span> 10; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@foo</span>[0].<span class="highlite-ROUTINE">defined</span>; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@foo</span>[0]:exists; <span class="highlite-COMMENT"># OUTPUT: «True␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@foo</span>[2]:exists; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@foo</span>[0<span class="highlite-OPERATOR">,</span> 2]:exists; <span class="highlite-COMMENT"># OUTPUT: «(True False)␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%fruit</span> <span class="highlite-OPERATOR">=</span> apple <span class="highlite-OPERATOR">=></span> <span class="highlite-TYPE">Any</span><span class="highlite-OPERATOR">,</span> orange <span class="highlite-OPERATOR">=></span> 10; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%fruit</span><apple>.<span class="highlite-ROUTINE">defined</span>; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%fruit</span><apple>:exists; <span class="highlite-COMMENT"># OUTPUT: «True␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%fruit</span><banana>:exists; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%fruit</span><apple banana>:exists; <span class="highlite-COMMENT"># OUTPUT: «(True False)␤»</span></pre> </div> </div> <p>May also be negated to test for non-existence:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%fruit</span><apple banana><span class="highlite-OPERATOR">:</span>!exists; <span class="highlite-COMMENT"># OUTPUT: «(False True)␤» </span></pre> </div> </div> <p>To check if <em>all</em> elements of a slice exist, use an <a href="/routine/all">all</a> junction:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">if</span> <span class="highlite-ROUTINE">all</span> <span class="highlite-NAME_HASH">%fruit</span><apple orange banana>:exists { <span class="highlite-OPERATOR">...</span> } </pre> </div> </div> <p>It can be used on multi-dimensional arrays and hashes:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@multi-dim</span> <span class="highlite-OPERATOR">=</span> 1<span class="highlite-OPERATOR">,</span> [2<span class="highlite-OPERATOR">,</span> 3<span class="highlite-OPERATOR">,</span> [4<span class="highlite-OPERATOR">,</span> 5]]; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@multi-dim</span>[1;2;0]:exists; <span class="highlite-COMMENT"># OUTPUT: «True␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@multi-dim</span>[1;2;5]:exists; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%multi-dim</span> <span class="highlite-OPERATOR">=</span> 1 <span class="highlite-OPERATOR">=></span> { foo <span class="highlite-OPERATOR">=></span> { 3 <span class="highlite-OPERATOR">=></span> 42 } }; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%multi-dim</span>{1;<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">foo</span><span class="highlite-STRING_DELIMITER">'</span>;3}:exists; <span class="highlite-COMMENT"># OUTPUT: «True␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%multi-dim</span>{1;<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">bar</span><span class="highlite-STRING_DELIMITER">'</span>;3}:exists; <span class="highlite-COMMENT"># OUTPUT: «False␤»</span></pre> </div> </div> <p><code>:exists</code> can be combined with the <a href="#:delete"><code>:delete</code></a> and <a href="#:p"><code>:p</code></a>/<a href="#:kv"><code>:kv</code></a> adverbs - in which case the behavior is determined by those adverbs, except that any returned element <em>value</em> is replaced with the corresponding <a href="/type/Bool"><code>Bool</code></a> indicating element <em>existence</em>.</p><p>See <a href="#method_EXISTS-POS">method <code>EXISTS-POS</code></a> and <a href="#method_EXISTS-KEY">method <code>EXISTS-KEY</code></a> for the underlying mechanism.</p><p><a name="index-entry-:delete_(subscript_adverb)" class="index-entry"></a></p> <h2 id=":delete" class="raku-h2"><a href="#Subscripts" title="go to top of document"><code>:delete</code><a class="raku-anchor" title="direct link" href="#:delete">§</a></a></h2> <p>Delete the element from the collection or, if supported by the collection, creates a hole at the given index, in addition to returning its value.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@tens</span> <span class="highlite-OPERATOR">=</span> 0<span class="highlite-OPERATOR">,</span> 10<span class="highlite-OPERATOR">,</span> 20<span class="highlite-OPERATOR">,</span> 30; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@tens</span>[3]:delete; <span class="highlite-COMMENT"># OUTPUT: «30␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@tens</span>; <span class="highlite-COMMENT"># OUTPUT: «[0 10 20]␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%fruit</span> <span class="highlite-OPERATOR">=</span> apple <span class="highlite-OPERATOR">=></span> 5<span class="highlite-OPERATOR">,</span> orange <span class="highlite-OPERATOR">=></span> 10<span class="highlite-OPERATOR">,</span> banana <span class="highlite-OPERATOR">=></span> 4<span class="highlite-OPERATOR">,</span> peach <span class="highlite-OPERATOR">=></span> 17; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%fruit</span><apple>:delete; <span class="highlite-COMMENT"># OUTPUT: «5␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%fruit</span><peach orange>:delete; <span class="highlite-COMMENT"># OUTPUT: «(17 10)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%fruit</span>; <span class="highlite-COMMENT"># OUTPUT: «{banana => 4}␤»</span></pre> </div> </div> <p>Note that assigning <a href="/type/Nil"><code>Nil</code></a> will revert the container at the given index to its default value. It will not create a hole. The created holes can be tested for with <code>:exists</code> but iteration will not skip them and produce undefined values instead.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@a</span> <span class="highlite-OPERATOR">=</span> 1<span class="highlite-OPERATOR">,</span> 2<span class="highlite-OPERATOR">,</span> 3; <span class="highlite-NAME_ARRAY">@a</span>[1]:delete; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@a</span>[1]:exists; <span class="highlite-COMMENT"># OUTPUT: «False␤» </span>.<span class="highlite-ROUTINE">say</span> <span class="highlite-KEYWORD">for</span> <span class="highlite-NAME_ARRAY">@a</span>; <span class="highlite-COMMENT"># OUTPUT: «1␤(Any)␤3␤»</span></pre> </div> </div> <p>With the negated form of the adverb, the element is not actually deleted. This means you can pass a flag to make it conditional:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%fruit</span><apple> :delete(<span class="highlite-NAME_SCALAR">$flag</span>); <span class="highlite-COMMENT"># deletes the element only if $flag is </span> <span class="highlite-COMMENT"># true, but always returns the value. </span></pre> </div> </div> <p>It can be combined with the <a href="#:exists"><code>:exists</code></a> and <a href="#:p"><code>:p</code></a>/<a href="#:kv"><code>:kv</code></a>/<a href="#:k"><code>:k</code></a>/<a href="#:v"><code>:v</code></a> adverbs - in which case the return value will be determined by those adverbs, but the element will at the same time also be deleted.</p><p>See <a href="#method_DELETE-POS">method <code>DELETE-POS</code></a> and <a href="#method_DELETE-KEY">method <code>DELETE-KEY</code></a> for the underlying mechanism.</p><p>You can use also these adverbs on associative type objects, but it will actually do nothing; it will also return <a href="/type/Nil"><code>Nil</code></a></p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-TYPE">Hash</span><foo>:delete; <span class="highlite-COMMENT"># OUTPUT: «Nil␤» </span></pre> </div> </div> <p>The adverb can be used on lazy arrays too:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@lazy-array</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">lazy</span> 1<span class="highlite-OPERATOR">,</span> 11<span class="highlite-OPERATOR">,</span> 121 <span class="highlite-OPERATOR">...</span> 10**100; <span class="highlite-NAME_ARRAY">@lazy-array</span>[2**24]:delete; </pre> </div> </div> <p><a name="index-entry-:p_(subscript_adverb)" class="index-entry"></a></p> <h2 id=":p" class="raku-h2"><a href="#Subscripts" title="go to top of document"><code>:p</code><a class="raku-anchor" title="direct link" href="#:p">§</a></a></h2> <p>Return both the index/key and the value of the element, in the form of a <a href="/type/Pair"><code>Pair</code></a>, and silently skip nonexistent elements:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@tens</span> <span class="highlite-OPERATOR">=</span> 0<span class="highlite-OPERATOR">,</span> 10<span class="highlite-OPERATOR">,</span> 20<span class="highlite-OPERATOR">,</span> 30; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@tens</span>[1]:p; <span class="highlite-COMMENT"># OUTPUT: «1 => 10␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@tens</span>[0<span class="highlite-OPERATOR">,</span> 4<span class="highlite-OPERATOR">,</span> 2]:p; <span class="highlite-COMMENT"># OUTPUT: «(0 => 0 2 => 20)␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%month</span> <span class="highlite-OPERATOR">=</span> Jan <span class="highlite-OPERATOR">=></span> 1<span class="highlite-OPERATOR">,</span> Feb <span class="highlite-OPERATOR">=></span> 2<span class="highlite-OPERATOR">,</span> Mar <span class="highlite-OPERATOR">=></span> 3; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Feb>:p; <span class="highlite-COMMENT"># OUTPUT: «Feb => 2␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Jan Foo Mar>:p; <span class="highlite-COMMENT"># OUTPUT: «(Jan => 1 Mar => 3)␤»</span></pre> </div> </div> <p>If you <em>don't</em> want to skip nonexistent elements, use the negated form:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Jan Foo Mar><span class="highlite-OPERATOR">:</span>!p; <span class="highlite-COMMENT"># OUTPUT: «(Jan => 1 Foo => (Any) Mar => 3)␤» </span></pre> </div> </div> <p>It can be combined with the <a href="#:exists"><code>:exists</code></a> and <a href="#:delete"><code>:delete</code></a> adverbs.</p><p>See also the <a href="/routine/pairs">pairs</a> routine.</p><p><a name="index-entry-:kv_(subscript_adverb)" class="index-entry"></a></p> <h2 id=":kv" class="raku-h2"><a href="#Subscripts" title="go to top of document"><code>:kv</code><a class="raku-anchor" title="direct link" href="#:kv">§</a></a></h2> <p>Return both the index/key and the value of the element, in the form of a <a href="/type/List"><code>List</code></a>, and silently skip nonexistent elements. When used on a <a href="#Slices">slice</a>, the return value is a single flat list of interleaved keys and values:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@tens</span> <span class="highlite-OPERATOR">=</span> 0<span class="highlite-OPERATOR">,</span> 10<span class="highlite-OPERATOR">,</span> 20<span class="highlite-OPERATOR">,</span> 30; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@tens</span>[1]:kv; <span class="highlite-COMMENT"># OUTPUT: «(1 10)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@tens</span>[0<span class="highlite-OPERATOR">,</span> 4<span class="highlite-OPERATOR">,</span> 2]:kv; <span class="highlite-COMMENT"># OUTPUT: «(0 0 2 20)␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%month</span> <span class="highlite-OPERATOR">=</span> Jan <span class="highlite-OPERATOR">=></span> 1<span class="highlite-OPERATOR">,</span> Feb <span class="highlite-OPERATOR">=></span> 2<span class="highlite-OPERATOR">,</span> Mar <span class="highlite-OPERATOR">=></span> 3; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Feb>:kv; <span class="highlite-COMMENT"># OUTPUT: «(Feb 2)␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Jan Foo Mar>:kv; <span class="highlite-COMMENT"># OUTPUT: «(Jan 1 Mar 3)␤»</span></pre> </div> </div> <p>If you <em>don't</em> want to skip nonexistent elements, use the negated form:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Jan Foo Mar><span class="highlite-OPERATOR">:</span>!<span class="highlite-ROUTINE">kv</span>; <span class="highlite-COMMENT"># OUTPUT: «(Jan 1 Foo (Any) Mar 3)␤» </span></pre> </div> </div> <p>This adverb is commonly used to iterate over slices:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">for</span> <span class="highlite-NAME_HASH">%month</span><Feb Mar>:kv <span class="highlite-KEYWORD">-></span> <span class="highlite-NAME_SCALAR">$month</span><span class="highlite-OPERATOR">,</span> <span class="highlite-NAME_SCALAR">$i</span> { <span class="highlite-ROUTINE">say</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-NAME_SCALAR">$month</span><span class="highlite-STRING"> had </span><span class="highlite-ESCAPE">{</span><span class="highlite-TYPE">Date</span>.<span class="highlite-ROUTINE">new</span>(2015<span class="highlite-OPERATOR">,</span> <span class="highlite-NAME_SCALAR">$i</span><span class="highlite-OPERATOR">,</span> 1).<span class="highlite-ROUTINE">days-in-month</span><span class="highlite-ESCAPE">}</span><span class="highlite-STRING"> days in 2015</span><span class="highlite-STRING_DELIMITER">"</span> } </pre> </div> </div> <p>It can be combined with the <a href="#:exists"><code>:exists</code></a> and <a href="#:delete"><code>:delete</code></a> adverbs.</p><p>See also the <a href="/routine/kv">kv</a> routine.</p><p><a name="index-entry-:k_(subscript_adverb)" class="index-entry"></a></p> <h2 id=":k" class="raku-h2"><a href="#Subscripts" title="go to top of document"><code>:k</code><a class="raku-anchor" title="direct link" href="#:k">§</a></a></h2> <p>Return only the index/key of the element, rather than its value, and silently skip nonexistent elements:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@tens</span> <span class="highlite-OPERATOR">=</span> 0<span class="highlite-OPERATOR">,</span> 10<span class="highlite-OPERATOR">,</span> 20<span class="highlite-OPERATOR">,</span> 30; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@tens</span>[1]:k; <span class="highlite-COMMENT"># OUTPUT: «1␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@tens</span>[0<span class="highlite-OPERATOR">,</span> 4<span class="highlite-OPERATOR">,</span> 2]:k; <span class="highlite-COMMENT"># OUTPUT: «(0 2)␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%month</span> <span class="highlite-OPERATOR">=</span> Jan <span class="highlite-OPERATOR">=></span> 1<span class="highlite-OPERATOR">,</span> Feb <span class="highlite-OPERATOR">=></span> 2<span class="highlite-OPERATOR">,</span> Mar <span class="highlite-OPERATOR">=></span> 3; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Feb>:k; <span class="highlite-COMMENT"># OUTPUT: «Feb␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Jan Foo Mar>:k; <span class="highlite-COMMENT"># OUTPUT: «(Jan Mar)␤»</span></pre> </div> </div> <p>If you <em>don't</em> want to skip nonexistent elements, use the negated form:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Jan Foo Mar><span class="highlite-OPERATOR">:</span>!k; <span class="highlite-COMMENT"># OUTPUT: «(Jan Foo Mar)␤» </span></pre> </div> </div> <p>See also the <a href="/routine/keys">keys</a> routine.</p><p><a name="index-entry-:v_(subscript_adverb)" class="index-entry"></a></p> <h2 id=":v" class="raku-h2"><a href="#Subscripts" title="go to top of document"><code>:v</code><a class="raku-anchor" title="direct link" href="#:v">§</a></a></h2> <p>Return the bare value of the element (rather than potentially returning a mutable value container), and silently skip nonexistent elements:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@tens</span> <span class="highlite-OPERATOR">=</span> 0<span class="highlite-OPERATOR">,</span> 10<span class="highlite-OPERATOR">,</span> 20<span class="highlite-OPERATOR">,</span> 30; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@tens</span>[1]:v; <span class="highlite-COMMENT"># OUTPUT: «10␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@tens</span>[0<span class="highlite-OPERATOR">,</span> 4<span class="highlite-OPERATOR">,</span> 2]:v; <span class="highlite-COMMENT"># OUTPUT: «(0, 20)␤» </span><span class="highlite-NAME_ARRAY">@tens</span>[3] <span class="highlite-OPERATOR">=</span> 31; <span class="highlite-COMMENT"># OK </span><span class="highlite-NAME_ARRAY">@tens</span>[3]:v <span class="highlite-OPERATOR">=</span> 31; <span class="highlite-COMMENT"># ERROR, Cannot modify an immutable Int (31) </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%month</span> <span class="highlite-OPERATOR">=</span> Jan <span class="highlite-OPERATOR">=></span> 1<span class="highlite-OPERATOR">,</span> Feb <span class="highlite-OPERATOR">=></span> 2<span class="highlite-OPERATOR">,</span> Mar <span class="highlite-OPERATOR">=></span> 3; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Feb>:v; <span class="highlite-COMMENT"># OUTPUT: «2␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Jan Foo Mar>:v; <span class="highlite-COMMENT"># OUTPUT: «(1 3)␤» </span></pre> </div> </div> <p>If you <em>don't</em> want to skip nonexistent elements, use the negated form:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_HASH">%month</span><Jan Foo Mar><span class="highlite-OPERATOR">:</span>!v; <span class="highlite-COMMENT"># OUTPUT: «(1 (Any) 3)␤» </span></pre> </div> </div> <p>See also the <a href="/routine/values">values</a> routine.</p> <h1 id="Custom_types" class="raku-h1"><a href="#Subscripts" title="go to top of document">Custom types<a class="raku-anchor" title="direct link" href="#Custom_types">§</a></a></h1> <p>The subscripting interfaces described on this page are not meant to be exclusive to Raku's built-in collection types - you can (and should) reuse them for any custom type that wants to provide access to data by index or key.</p><p>You don't have to manually overload the <a href="/language/operators#postcircumfix_[_]"><code>postcircumfix [ ]</code></a> and <a href="/language/operators#postcircumfix_{_}"><code>postcircumfix { }</code></a> operators and re-implement all their magic, to achieve that - instead, you can rely on the fact that their standard implementation dispatches to a well-defined set of low-level methods behind the scenes. For example:</p><table class="table is-bordered centered pod-table"> <thead> <tr><th>when you write:</th><th>this gets called behind the scenes:</th></tr> </thead> <tbody> <tr><td>%foo<aa></td><td>%foo.AT-KEY("aa")</td></tr> <tr><td>%foo<aa>:delete</td><td>%foo.DELETE-KEY("aa")</td></tr> <tr><td>@foo[3, 4, 5]</td><td>@foo.AT-POS(3), @foo.AT-POS(4), @foo.AT-POS(5)</td></tr> <tr><td>@foo[*-1]</td><td>@foo.AT-POS(@foo.elems - 1)</td></tr> </tbody> </table> <p>So in order to make subscripting work, you only have to implement or delegate those low-level methods (<a href="#Methods_to_implement_for_positional_subscripting">detailed below</a>) for your custom type.</p><p>If you do, you should also let your type compose the <a href="/type/Positional"><code>Positional</code></a> or <a href="/type/Associative"><code>Associative</code></a> role, respectively. This doesn't add any functionality per se, but announces (and may be used to check) that the type implements the corresponding subscripting interface.</p> <h2 id="Custom_type_example" class="raku-h2"><a href="#Subscripts" title="go to top of document">Custom type example<a class="raku-anchor" title="direct link" href="#Custom_type_example">§</a></a></h2> <p>Imagine a <code>HTTP::Header</code> type which, despite being a custom class with special behavior, can be indexed like a hash:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$request</span> <span class="highlite-OPERATOR">=</span> HTTP::Request.<span class="highlite-ROUTINE">new</span>(GET <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">raku.org</span><span class="highlite-STRING_DELIMITER">"</span>); <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$request</span>.header.^<span class="highlite-ROUTINE">name</span>; <span class="highlite-COMMENT"># OUTPUT: «HTTP::Header␤» </span> <span class="highlite-NAME_SCALAR">$request</span>.header<Accept> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">text/plain</span><span class="highlite-STRING_DELIMITER">"</span>; <span class="highlite-NAME_SCALAR">$request</span>.header{<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Accept-</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">X</span>~ <Charset <span class="highlite-TYPE">Encoding</span> Language>} <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER"><</span><span class="highlite-STRING">utf-8 gzip en</span><span class="highlite-STRING_DELIMITER">></span>; <span class="highlite-NAME_SCALAR">$request</span>.header.<span class="highlite-ROUTINE">push</span>(<span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">Accept-Language</span><span class="highlite-STRING_DELIMITER">'</span> <span class="highlite-OPERATOR">=></span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">fr</span><span class="highlite-STRING_DELIMITER">"</span>); <span class="highlite-COMMENT"># like .push on a Hash </span> <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_SCALAR">$request</span>.header<Accept-Language>.<span class="highlite-ROUTINE">raku</span>; <span class="highlite-COMMENT"># OUTPUT: «["en", "fr"]␤» </span> <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$rawheader</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-NAME_SCALAR">$request</span>.header.<span class="highlite-TYPE">Str</span>; <span class="highlite-COMMENT"># stringify according to HTTP spec </span></pre> </div> </div> <p>A simple way to implement this class would be to give it an attribute of type <a href="/type/Hash"><code>Hash</code></a>, and delegate all subscripting and iterating related functionality to that attribute (using a custom type constraint to make sure users don't insert anything invalid into it):</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">class</span> HTTP::Header <span class="highlite-KEYWORD">does</span> <span class="highlite-TYPE">Associative</span> { <span class="highlite-KEYWORD">subset</span> StrOrArrayOfStr <span class="highlite-KEYWORD">where</span> <span class="highlite-TYPE">Str</span> <span class="highlite-OPERATOR">|</span> ( <span class="highlite-TYPE">Array</span> <span class="highlite-OPERATOR">&</span> {.<span class="highlite-ROUTINE">all</span> <span class="highlite-OPERATOR">~~</span> <span class="highlite-TYPE">Str</span>} ); <span class="highlite-KEYWORD">has</span> <span class="highlite-NAME_HASH">%!fields</span> <span class="highlite-KEYWORD">of</span> StrOrArrayOfStr <span class="highlite-ROUTINE">handles</span> <<span class="highlite-ROUTINE">AT-KEY</span> <span class="highlite-ROUTINE">EXISTS-KEY</span> <span class="highlite-ROUTINE">DELETE-KEY</span> <span class="highlite-ROUTINE">push</span> <span class="highlite-ROUTINE">iterator</span> <span class="highlite-ROUTINE">list</span> <span class="highlite-ROUTINE">kv</span> <span class="highlite-ROUTINE">keys</span> <span class="highlite-ROUTINE">values</span>>; <span class="highlite-KEYWORD">method</span> <span class="highlite-TYPE">Str</span> { <span class="highlite-COMMENT">#`[not shown, for brevity]</span> } } </pre> </div> </div> <p>However, HTTP header field names are supposed to be case-insensitive (and preferred in camel-case). We can accommodate this by taking the <code>*-KEY</code> and <code>push</code> methods out of the <code>handles</code> list, and implementing them separately like this:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">AT-KEY</span> (<span class="highlite-NAME_SCALAR">$key</span>) <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">rw</span> { <span class="highlite-NAME_HASH">%!fields</span>{normalize-key <span class="highlite-NAME_SCALAR">$key</span>} } <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">EXISTS-KEY</span> (<span class="highlite-NAME_SCALAR">$key</span>) { <span class="highlite-NAME_HASH">%!fields</span>{normalize-key <span class="highlite-NAME_SCALAR">$key</span>}:exists } <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">DELETE-KEY</span> (<span class="highlite-NAME_SCALAR">$key</span>) { <span class="highlite-NAME_HASH">%!fields</span>{normalize-key <span class="highlite-NAME_SCALAR">$key</span>}:delete } <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">push</span>(<span class="highlite-OPERATOR">*</span><span class="highlite-NAME_ARRAY">@_</span>) { <span class="highlite-COMMENT">#`[not shown, for brevity]</span> } <span class="highlite-KEYWORD">sub</span> normalize-key (<span class="highlite-NAME_SCALAR">$key</span>) { <span class="highlite-NAME_SCALAR">$key</span>.<span class="highlite-ROUTINE">subst</span>(<span class="highlite-REGEX_DELIMITER">/</span><span class="highlite-REGEX_SPECIAL">\w+</span><span class="highlite-REGEX_DELIMITER">/</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">*</span>.<span class="highlite-ROUTINE">tc</span><span class="highlite-OPERATOR">,</span> :g) } </pre> </div> </div> <p>Note that subscripting <code>%!fields</code> returns an appropriate rw container, which our <code>AT-KEY</code> can simply pass on.</p><p>However, we may prefer to be less strict about user input and instead take care of sanitizing the field values ourselves. In that case, we can remove the <code>StrOrArrayOfStr</code> type constraint on <code>%!fields</code>, and replace our <code>AT-KEY</code> implementation with one that returns a custom <a href="/type/Proxy"><code>Proxy</code></a> container which takes care of sanitizing values on assignment:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">AT-KEY</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$key</span>) <span class="highlite-KEYWORD">is</span> <span class="highlite-KEYWORD">rw</span> { <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$element</span> <span class="highlite-OPERATOR">:=</span> <span class="highlite-NAME_HASH">%!fields</span>{normalize-key <span class="highlite-NAME_SCALAR">$key</span>}; <span class="highlite-TYPE">Proxy</span>.<span class="highlite-ROUTINE">new</span>( FETCH <span class="highlite-OPERATOR">=></span> <span class="highlite-KEYWORD">method</span> () { <span class="highlite-NAME_SCALAR">$element</span> }<span class="highlite-OPERATOR">,</span> <span class="highlite-ROUTINE">STORE</span> <span class="highlite-OPERATOR">=></span> <span class="highlite-KEYWORD">method</span> (<span class="highlite-NAME_SCALAR">$value</span>) { <span class="highlite-NAME_SCALAR">$element</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-ROUTINE">do</span> <span class="highlite-KEYWORD">given</span> <span class="highlite-NAME_SCALAR">$value</span>».<span class="highlite-ROUTINE">split</span>(<span class="highlite-REGEX_DELIMITER">/</span><span class="highlite-REGEX_SPECIAL">'</span><span class="highlite-REGEX_LITERAL">,</span><span class="highlite-REGEX_SPECIAL">' \s+</span><span class="highlite-REGEX_DELIMITER">/</span>).<span class="highlite-ROUTINE">flat</span> { <span class="highlite-KEYWORD">when</span> 1 { <span class="highlite-OPERATOR">.</span>[0] } <span class="highlite-COMMENT"># a single value is stored as a string </span> <span class="highlite-KEYWORD">default</span> { .<span class="highlite-TYPE">Array</span> } <span class="highlite-COMMENT"># multiple values are stored as an array </span> } } ); } </pre> </div> </div> <p>Note that declaring the method as <code>multi</code> and restricting it to <code>:D</code> (defined invocants) makes sure that the undefined case is passed through to the default implementation provided by <a href="/type/Any"><code>Any</code></a> (which is involved in auto-vivification).</p> <h2 id="Methods_to_implement_for_positional_subscripting" class="raku-h2"><a href="#Subscripts" title="go to top of document">Methods to implement for positional subscripting<a class="raku-anchor" title="direct link" href="#Methods_to_implement_for_positional_subscripting">§</a></a></h2> <p>In order to make index-based subscripting via <a href="/language/operators#postcircumfix_[_]"><code>postcircumfix [ ]</code></a> work for your custom type, you should implement at least <code>elems</code>, <code>AT-POS</code> and <code>EXISTS-POS</code> - and optionally others as detailed below.</p> <h3 id="method_elems" class="raku-h3"><a href="#Subscripts" title="go to top of document">method elems<a class="raku-anchor" title="direct link" href="#method_elems">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">elems</span>(::?CLASS:D:)</pre> </div> </div> <p>Expected to return a number indicating how many subscriptable elements there are in the object. May be called by users directly, and is also called by <a href="/language/operators#postcircumfix_[_]"><code>postcircumfix [ ]</code></a> when indexing elements from the end, as in <code>@foo[*-1]</code>.</p><p>If not implemented, your type will inherit the default implementation from <a href="/type/Any"><code>Any</code></a> that always returns <code>1</code> for defined invocants - which is most likely not what you want. So if the number of elements cannot be known for your positional type, add an implementation that <a href="/routine/fail">fail</a>s or <a href="/routine/die">die</a>s, to avoid silently doing the wrong thing.</p> <h3 id="method_AT-POS" class="raku-h3"><a href="#Subscripts" title="go to top of document">method AT-POS<a class="raku-anchor" title="direct link" href="#method_AT-POS">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">AT-POS</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$index</span>)</pre> </div> </div> <p>Expected to return the element at position <code>$index</code>. This is what <a href="/language/operators#postcircumfix_[_]"><code>postcircumfix [ ]</code></a> normally calls.</p><p>If you want an element to be mutable (like they are for the built-in <a href="/type/Array"><code>Array</code></a> type), you'll have to make sure to return it in the form of an item container that evaluates to the element's value when read, and updates it when assigned to. Remember to use <code>return-rw</code> or the <code>is rw</code> routine trait to make that work; see the <a href="/language/subscripts#Custom_type_example">example</a>.</p> <h3 id="method_EXISTS-POS" class="raku-h3"><a href="#Subscripts" title="go to top of document">method EXISTS-POS<a class="raku-anchor" title="direct link" href="#method_EXISTS-POS">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">EXISTS-POS</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$index</span>)</pre> </div> </div> <p>Expected to return a Bool indicating whether or not there is an element at position <code>$index</code>. This is what <a href="/language/operators#postcircumfix_[_]"><code>postcircumfix [ ]</code></a> calls when invoked like <code>@foo[42]:exists</code>.</p><p>What "existence" of an element means, is up to your type.</p><p>If you don't implement this, your type will inherit the default implementation from <a href="/type/Any"><code>Any</code></a>, which returns True for 0 and False for any other index - which is probably not what you want. So if checking for element existence cannot be done for your type, add an implementation that <a href="/routine/fail">fail</a>s or <a href="/routine/die">die</a>s, to avoid silently doing the wrong thing.</p> <h3 id="method_DELETE-POS" class="raku-h3"><a href="#Subscripts" title="go to top of document">method DELETE-POS<a class="raku-anchor" title="direct link" href="#method_DELETE-POS">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">DELETE-POS</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$index</span>)</pre> </div> </div> <p>Expected to delete the element at position <code>$index</code>, and return the value it had. This is what <a href="/language/operators#postcircumfix_[_]"><code>postcircumfix [ ]</code></a> calls when invoked like <code>@foo[42]:delete</code>.</p><p>What "deleting" an element means, is up to your type.</p><p>Implementing this method is optional; if you don't, users trying to delete elements from an object of this type will get an appropriate error message.</p> <h3 id="method_ASSIGN-POS" class="raku-h3"><a href="#Subscripts" title="go to top of document">method ASSIGN-POS<a class="raku-anchor" title="direct link" href="#method_ASSIGN-POS">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">ASSIGN-POS</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$index</span><span class="highlite-OPERATOR">,</span> <span class="highlite-NAME_SCALAR">$new</span>)</pre> </div> </div> <p>Expected to set the element at position <code>$index</code> to the value <code>$new</code>. Implementing this is entirely optional; if you don't, <code>self.AT-POS($index) = $new</code> is used instead, and if you do, you should make sure it has the same effect.</p><p>This is meant as an opt-in performance optimization, so that simple assignments like <code>@numbers[5] = "five"</code> can operate without having to call <code>AT-POS</code> (which would have to create and return a potentially expensive container object).</p><p>Note that implementing <code>ASSIGN-POS</code> does <em>not</em> relieve you from making <code>AT-POS</code> a <code>rw</code> method though, because less trivial assignments/modifications such as <code>@numbers[5]++</code> will still use <code>AT-POS</code>.</p> <h3 id="method_BIND-POS" class="raku-h3"><a href="#Subscripts" title="go to top of document">method BIND-POS<a class="raku-anchor" title="direct link" href="#method_BIND-POS">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">BIND-POS</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$index</span><span class="highlite-OPERATOR">,</span> \<span class="highlite-ROUTINE">new</span>)</pre> </div> </div> <p>Expected to bind the value or container <code>new</code> to the slot at position <code>$index</code>, replacing any container that would be naturally found there. This is what is called when you write:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$x</span> <span class="highlite-OPERATOR">=</span> 10; <span class="highlite-NAME_ARRAY">@numbers</span>[5] <span class="highlite-OPERATOR">:=</span> <span class="highlite-NAME_SCALAR">$x</span>; </pre> </div> </div> <p>The generic <a href="/type/Array"><code>Array</code></a> class supports this in order to allow building complex linked data structures, but for more domain-specific types it may not make sense, so don't feel compelled to implement it. If you don't, users will get an appropriate error message when they try to bind to a positional slot of an object of this type.</p> <h3 id="method_STORE" class="raku-h3"><a href="#Subscripts" title="go to top of document">method STORE<a class="raku-anchor" title="direct link" href="#method_STORE">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">STORE</span> (::?CLASS:D: \<span class="highlite-ROUTINE">values</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$INITIALIZE</span>)</pre> </div> </div> <p>This method should only be supplied if you want to support this syntax:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@a</span> <span class="highlite-KEYWORD">is</span> Foo <span class="highlite-OPERATOR">=</span> 1,2,3; </pre> </div> </div> <p>Which is used for binding your implementation of the <a href="/type/Positional"><code>Positional</code></a> role.</p><p><code>STORE</code> should accept the values to (re-)initialize the object with. The optional named parameter will contain a <code>True</code> value when the method is called on the object for the first time. It should return the invocant.</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">role</span> Logger { <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">log</span>( <span class="highlite-TYPE">Str</span> <span class="highlite-NAME_SCALAR">$msg</span>) {<span class="highlite-OPERATOR">…</span>}} <span class="highlite-KEYWORD">class</span> ConsoLogger <span class="highlite-KEYWORD">does</span> Logger { <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">log</span> ( <span class="highlite-TYPE">Str</span> <span class="highlite-NAME_SCALAR">$msg</span> ) { <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">❢ </span><span class="highlite-NAME_SCALAR">$msg</span><span class="highlite-STRING_DELIMITER">"</span>.<span class="highlite-ROUTINE">say</span> }} <span class="highlite-KEYWORD">class</span> DNA { <span class="highlite-KEYWORD">has</span> <span class="highlite-NAME_SCALAR">$.chain</span>; <span class="highlite-KEYWORD">has</span> Logger <span class="highlite-NAME_SCALAR">$!logger</span>; <span class="highlite-KEYWORD">submethod</span> <span class="highlite-ROUTINE">BUILD</span>( <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$chain</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$logger</span> <span class="highlite-OPERATOR">=</span> ConsoLogger.<span class="highlite-ROUTINE">new</span>() ) {} <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">STORE</span> (<span class="highlite-TYPE">Str</span> <span class="highlite-NAME_SCALAR">$chain</span> <span class="highlite-KEYWORD">where</span> { <span class="highlite-OPERATOR">/</span><span class="highlite-OPERATOR">^^</span> <span class="highlite-OPERATOR"><</span>[ACGT]<span class="highlite-OPERATOR">></span><span class="highlite-OPERATOR">+</span> $$ <span class="highlite-OPERATOR">/</span> <span class="highlite-OPERATOR">and</span> .<span class="highlite-ROUTINE">chars</span> <span class="highlite-OPERATOR">%%</span> 3 }<span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$INITIALIZE</span> <span class="highlite-KEYWORD">--></span> DNA) { <span class="highlite-KEYWORD">if</span> (<span class="highlite-NAME_SCALAR">$INITIALIZE</span>) { <span class="highlite-NAME_SCALAR">$!logger</span> <span class="highlite-OPERATOR">=</span> ConsoLogger.<span class="highlite-ROUTINE">new</span>(); <span class="highlite-NAME_SCALAR">$!logger</span>.<span class="highlite-ROUTINE">log</span>( <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Initialized</span><span class="highlite-STRING_DELIMITER">"</span> ); } <span class="highlite-NAME_SCALAR">$!chain</span> <span class="highlite-OPERATOR">:=</span> <span class="highlite-NAME_SCALAR">$chain</span>; <span class="highlite-NAME_SCALAR">$!logger</span>.<span class="highlite-ROUTINE">log</span>(<span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Change value to </span><span class="highlite-NAME_SCALAR">$chain</span><span class="highlite-STRING_DELIMITER">"</span> ); <span class="highlite-ROUTINE">self</span> } <span class="highlite-KEYWORD">method</span> <span class="highlite-TYPE">Str</span>(::?CLASS:D:) { <span class="highlite-KEYWORD">return</span> <span class="highlite-NAME_SCALAR">$!chain</span>.<span class="highlite-ROUTINE">comb</span>.<span class="highlite-ROUTINE">rotor</span>(3).<span class="highlite-ROUTINE">map</span>( <span class="highlite-OPERATOR">*</span>.<span class="highlite-ROUTINE">join</span>(<span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING_DELIMITER">"</span>)).<span class="highlite-ROUTINE">join</span>(<span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">|</span><span class="highlite-STRING_DELIMITER">"</span>) } }; <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@string</span> <span class="highlite-KEYWORD">is</span> DNA <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">GAATCC</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-COMMENT"># OUTPUT: «❢ Initialized␤❢ Change value to GAATCC␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-OPERATOR">~</span><span class="highlite-NAME_ARRAY">@string</span>; <span class="highlite-COMMENT"># OUTPUT: «GAA|TCC␤» </span><span class="highlite-NAME_ARRAY">@string</span> <span class="highlite-OPERATOR">=</span> <span class="highlite-STRING_DELIMITER">'</span><span class="highlite-STRING">ACGTCG</span><span class="highlite-STRING_DELIMITER">'</span>; <span class="highlite-COMMENT"># OUTPUT: «❢ Change value to ACGTCG␤» </span><span class="highlite-ROUTINE">say</span> <span class="highlite-OPERATOR">~</span><span class="highlite-NAME_ARRAY">@string</span>; <span class="highlite-COMMENT"># OUTPUT: «ACG|TCG␤» </span></pre> </div> </div> <p>This code takes into account the value of <code>$INITIALIZE</code>, which is set to <code>True</code> only if we are assigning a value to a variable declared using the <code>is</code> syntax for the first time; for instance, as in this case, we might need to initialize any injected dependency. The <code>STORE</code> method should set the <code>self</code> variable and return it in all cases, including when the variable has already been initialized; however, only in the first case we need to initialize the logger we are using in this example.</p><p>The presence of the <code>INITIALIZE</code> flag can be also used to create immutable data structures:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">class</span> A { <span class="highlite-KEYWORD">has</span> <span class="highlite-NAME_ARRAY">@.foo</span> <span class="highlite-ROUTINE">handles</span> <<span class="highlite-TYPE">Str</span> <span class="highlite-ROUTINE">gist</span> <span class="highlite-ROUTINE">raku</span>>; <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">STORE</span>(<span class="highlite-OPERATOR">*</span><span class="highlite-NAME_ARRAY">@!foo</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$INITIALIZE</span>!) { } <span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">STORE</span>(<span class="highlite-OPERATOR">|</span>) { <span class="highlite-ROUTINE">die</span> <span class="highlite-STRING_DELIMITER">"</span><span class="highlite-STRING">Immutable</span><span class="highlite-STRING_DELIMITER">"</span> } } <span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_ARRAY">@a</span> <span class="highlite-KEYWORD">is</span> A <span class="highlite-OPERATOR">=</span> 1,2,3,4; <span class="highlite-ROUTINE">say</span> <span class="highlite-NAME_ARRAY">@a</span>; <span class="highlite-COMMENT"># OUTPUT: «[1,2,3,4]␤» </span><span class="highlite-NAME_ARRAY">@a</span> <span class="highlite-OPERATOR">=</span> 4,5,6,7; <span class="highlite-COMMENT"># dies: Immutable </span></pre> </div> </div> <h2 id="Methods_to_implement_for_associative_subscripting" class="raku-h2"><a href="#Subscripts" title="go to top of document">Methods to implement for associative subscripting<a class="raku-anchor" title="direct link" href="#Methods_to_implement_for_associative_subscripting">§</a></a></h2> <p>In order to make key-based subscripting via <a href="/language/operators#postcircumfix_{_}"><code>postcircumfix { }</code></a> work for your custom type, you should implement at least <code>AT-KEY</code> and <code>EXISTS-KEY</code> - and optionally others as detailed below.</p> <h3 id="method_AT-KEY" class="raku-h3"><a href="#Subscripts" title="go to top of document">method AT-KEY<a class="raku-anchor" title="direct link" href="#method_AT-KEY">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">AT-KEY</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$key</span>)</pre> </div> </div> <p>Expected to return the element associated with <code>$key</code>. This is what <a href="/language/operators#postcircumfix_{_}"><code>postcircumfix { }</code></a> normally calls.</p><p>If you want an element to be mutable (like they are for the built-in <a href="/type/Hash"><code>Hash</code></a> type), you'll have to make sure to return it in the form of an item container that evaluates to the element's value when read, and updates it when assigned to. Remember to use <code>return-rw</code> or the <code>is rw</code> routine trait to make that work; see the <a href="/language/subscripts#Custom_type_example">example</a>.</p><p>On the other hand if you want your collection to be read-only, feel free to return non-container values directly.</p> <h3 id="method_EXISTS-KEY" class="raku-h3"><a href="#Subscripts" title="go to top of document">method EXISTS-KEY<a class="raku-anchor" title="direct link" href="#method_EXISTS-KEY">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">EXISTS-KEY</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$key</span>)</pre> </div> </div> <p>Expected to return a Bool indicating whether or not there is an element associated with <code>$key</code>. This is what <a href="/language/operators#postcircumfix_{_}"><code>postcircumfix { }</code></a> calls when invoked like <code>%foo<aa>:exists</code>.</p><p>What "existence" of an element means, is up to your type.</p><p>If you don't implement this, your type will inherit the default implementation from <a href="/type/Any"><code>Any</code></a>, which always returns False - which is probably not what you want. So if checking for element existence cannot be done for your type, add an implementation that <a href="/routine/fail">fail</a>s or <a href="/routine/die">die</a>s, to avoid silently doing the wrong thing.</p> <h3 id="method_DELETE-KEY" class="raku-h3"><a href="#Subscripts" title="go to top of document">method DELETE-KEY<a class="raku-anchor" title="direct link" href="#method_DELETE-KEY">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">DELETE-KEY</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$key</span>)</pre> </div> </div> <p>Expected to delete the element associated with <code>$key</code>, and return the value it had. This is what <a href="/language/operators#postcircumfix_{_}"><code>postcircumfix { }</code></a> calls when invoked like <code>%foo<aa>:delete</code>.</p><p>What "deleting" an element means, is up to your type - though it should usually cause <code>EXISTS-KEY</code> to become <code>False</code> for that key.</p><p>Implementing this method is optional; if you don't, users trying to delete elements from an object of this type will get an appropriate error message.</p> <h3 id="method_ASSIGN-KEY" class="raku-h3"><a href="#Subscripts" title="go to top of document">method ASSIGN-KEY<a class="raku-anchor" title="direct link" href="#method_ASSIGN-KEY">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">ASSIGN-KEY</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$key</span><span class="highlite-OPERATOR">,</span> <span class="highlite-NAME_SCALAR">$new</span>)</pre> </div> </div> <p>Expected to set the element associated with <code>$key</code> to the value <code>$new</code>. Implementing this is entirely optional; if you don't, <code>self.AT-KEY($key) = $new</code> is used instead, and if you do, you should make sure it has the same effect.</p><p>This is meant as an opt-in performance optimization, so that simple assignments <code>%age<Claire> = 29</code> can operate without having to call <code>AT-KEY</code> (which would have to create and return a potentially expensive container object).</p><p>Note that implementing <code>ASSIGN-KEY</code> does <em>not</em> relieve you from making <code>AT-KEY</code> a <code>rw</code> method though, because less trivial assignments/modifications such as <code>%age<Claire>++</code> will still use <code>AT-KEY</code>.</p> <h3 id="method_BIND-KEY" class="raku-h3"><a href="#Subscripts" title="go to top of document">method BIND-KEY<a class="raku-anchor" title="direct link" href="#method_BIND-KEY">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">multi</span> <span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">BIND-KEY</span> (::?CLASS:D: <span class="highlite-NAME_SCALAR">$key</span><span class="highlite-OPERATOR">,</span> \<span class="highlite-ROUTINE">new</span>)</pre> </div> </div> <p>Expected to bind the value or container <code>new</code> to the slot associated with <code>$key</code>, replacing any container that would be naturally found there. This is what is called when you write:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_SCALAR">$x</span> <span class="highlite-OPERATOR">=</span> 10; <span class="highlite-NAME_HASH">%age</span><Claire> <span class="highlite-OPERATOR">:=</span> <span class="highlite-NAME_SCALAR">$x</span>; </pre> </div> </div> <p>The generic <a href="/type/Hash"><code>Hash</code></a> class supports this in order to allow building complex linked data structures, but for more domain-specific types it may not make sense, so don't feel compelled to implement it. If you don't, users will get an appropriate error message when they try to bind to an associative slot of an object of this type.</p> <h3 id="method_STORE_0" class="raku-h3"><a href="#Subscripts" title="go to top of document">method STORE<a class="raku-anchor" title="direct link" href="#method_STORE_0">§</a></a></h3>  <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">method</span> <span class="highlite-ROUTINE">STORE</span> (::?CLASS:D: \<span class="highlite-ROUTINE">values</span><span class="highlite-OPERATOR">,</span> <span class="highlite-OPERATOR">:</span><span class="highlite-NAME_SCALAR">$INITIALIZE</span>)</pre> </div> </div> <p>This method should only be supplied if you want to support the:</p> <div class="raku-code raku-lang"> <button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button> <label>Raku highlighting</label> <div> <pre class="nohighlights"><span class="highlite-KEYWORD">my</span> <span class="highlite-NAME_HASH">%h</span> <span class="highlite-KEYWORD">is</span> Foo <span class="highlite-OPERATOR">=</span> a <span class="highlite-OPERATOR">=></span> 42<span class="highlite-OPERATOR">,</span> b <span class="highlite-OPERATOR">=></span> 666; </pre> </div> </div> <p>syntax for binding your implementation of the <a href="/type/Associative"><code>Associative</code></a> role.</p><p>Should accept the values to (re-)initialize the object with, which either could consist of <a href="/type/Pair"><code>Pair</code></a>s, or separate key/value pairs. The optional named parameter will contain a <code>True</code> value when the method is called on the object for the first time. Should return the invocant.</p> </div></div></section> </div> </div> </div> <footer class="footer main-footer"> <div class="container px-4"> <nav class="level"> <div class="level-left"> <div class="level-item"> <a href="/about">About</a> </div> <div class="level-item"> <a id="toggle-theme">Toggle theme</a> </div> <div class="level-item" title="4d4aaa64c 2024-09-07"> <a>Commit</a> </div> </div> <div class="level-right"> <div class="level-item"> <a href="/license">License</a> </div> </div> </nav> </div> </footer> </body> </html>

CINXE.COM

Subscripts | Raku Documentation