doc/parts/namespace/Shapes-Data.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet type="text/xsl" href="formats/html.xsl"?>
   3
   4 <!-- This file is part of Shapes.                                           -->
   5 <!--                                                                        -->
   6 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   7 <!-- it under the terms of the GNU General Public License as published by   -->
   8 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   9 <!-- any later version.                                                     -->
  10 <!--                                                                        -->
  11 <!-- Shapes is distributed in the hope that it will be useful,              -->
  12 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  13 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  14 <!-- GNU General Public License for more details.                           -->
  15 <!--                                                                        -->
  16 <!-- You should have received a copy of the GNU General Public License      -->
  17 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  18 <!--                                                                        -->
  19 <!-- Copyright 2015 Henrik Tidefelt                                         -->
  20
  21
  22 <book>
  23   <namespace>..Shapes..Data</namespace>
  24   <description>
  25     <p>Data containers and their operations.</p>
  26   </description>
  27
  28   <title><self /></title>
  29   <up-link><parent-namespace /></up-link>
  30   <base href=<!--#expand-next-string-->"$(BASE)" />
  31   <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  32   <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  33   <external>
  34     <!--#include virtual="^/toc.xml" -->
  35   </external>
  36
  37   <top>
  38     <alphabetical-index/>
  39     <p>It is not entirely clear at the moment how this namespace should be organized.  Currently, there is not too much in here, but the plan is to equip <str-Shapes /> with a type system and object-oriented features in the future, and then it may be more natural to use types rather than namespaces for organization.  So, take this as a notice of subject to change, and read on!</p>
  40   </top>
  41
  42   <section id="namespace/shapes/data/sequences">
  43     <title>Sequences</title>
  44     <body>
  45
  46 <system-binding name="nil">
  47   <simple-value>
  48     <type><named-type name="SeqNil" /></type>
  49     <description>
  50       <p>The empty list.</p>
  51     </description>
  52   </simple-value>
  53 </system-binding>
  54
  55 <system-binding name="fcons">
  56   <function>
  57     <type-templates>
  58       <template name="A">
  59         <description>
  60           <p>Type of elements in result.</p>
  61         </description>
  62       </template>
  63     </type-templates>
  64     <case constructor-of="Seq">
  65       <arguments>
  66         <arg identifier="car"><type><template-type name="A" /></type></arg>
  67         <arg identifier="cdr"><type><parameterized-type name="Seq"><template-type name="A" /></parameterized-type></type></arg>
  68       </arguments>
  69       <result>
  70         <type>
  71           <parameterized-type name="Seq">
  72             <template-type name="A" />
  73           </parameterized-type>
  74         </type>
  75       </result>
  76       <description>
  77         <p>Similar to <value name="cons" />, but forces both arguments and always producing a <parameterized-type name="Seq"><template-type name="A" /></parameterized-type>.</p>
  78         <p>This function is typically called using it's infix syntax, <a part="syntax" id="syntax/misc-expr/fcons" />.</p>
  79         <p>The internal representation of the result is more efficient than what is generally obtained with <value name="cons" />, even if the results are equal in type.</p>
  80       </description>
  81       <see-also><value name="cons" /></see-also>
  82     </case>
  83   </function>
  84 </system-binding>
  85
  86 <system-binding name="list">
  87   <function>
  88     <case constructor-of="Seq">
  89       <arguments>
  90         <sink>
  91         </sink>
  92       </arguments>
  93       <description>
  94         <p>Constructs a list of the arguments.</p>
  95         <p>The value created when called with no arguments is recognized by <value name="nil?" />, and should be used as a null marker for <named-type name="Seq" />.</p>
  96       </description>
  97       <see-also><value name="unlist" /><value name="array" /></see-also>
  98     </case>
  99   </function>
 100 </system-binding>
 101
 102 <system-binding name="nil?">
 103   <function>
 104     <case>
 105       <arguments>
 106         <arg>
 107           <type><named-type name="Object" /></type>
 108         </arg>
 109       </arguments>
 110       <result>
 111         <type><named-type name="Boolean" /></type>
 112       </result>
 113       <dynamic-references></dynamic-references>
 114       <description><p>True if the argument is the empty <named-type name="Seq" />.</p></description>
 115     </case>
 116   </function>
 117 </system-binding>
 118
 119 <system-binding name="unlist">
 120   <function>
 121     <case constructor-of="Structure">
 122       <arguments>
 123         <arg>
 124           <type><named-type name="Seq" /></type>
 125         </arg>
 126       </arguments>
 127       <description>
 128         <p>Converts a list to a structure, being the inverse of <value name="list" /> in the sense that
 129 <pre>
 130 <![CDATA[\ lst → ( list [] <>[unlist lst] )]]>
 131 </pre>
 132 is the identity for <named-type name="Seq" /> values, and
 133 <pre>
 134 <![CDATA[\ struct → [unlist ( list [] <>struct )]]]>
 135 </pre>
 136 is the identify for <named-type name="Structure" /> values without named parts.</p>
 137         <p>Note how this function may be used to define a Scheme-like <inline>apply</inline> function:
 138 <pre>
 139 <![CDATA[apply: \ fun args → ( fun [] <>[unlist args] )]]>
 140 </pre>
 141 </p>
 142       </description>
 143       <see-also><value name="list" /></see-also>
 144     </case>
 145   </function>
 146 </system-binding>
 147
 148
 149 <system-binding name="lexiographicSort">
 150   <function>
 151     <type-templates>
 152       <template name="V">
 153         <description>
 154           <p>Type of values to be sorted.</p>
 155         </description>
 156       </template>
 157     </type-templates>
 158     <case>
 159       <arguments>
 160         <arg identifier="keys">
 161           <type>
 162             <parameterized-type name="Seq">
 163               <parameterized-type name="Array">
 164                 <named-type name="Integerml"/>
 165               </parameterized-type>
 166             </parameterized-type>
 167           </type>
 168         </arg>
 169         <arg identifier="values">
 170           <type>
 171             <union-type>
 172             <parameterized-type name="Seq">
 173               <template-type name="V"/>
 174             </parameterized-type>
 175             <named-type name="Void" />
 176             </union-type>
 177           </type>
 178           <default><value-the-void /></default>
 179         </arg>
 180       </arguments>
 181       <result>
 182         <type>
 183           <parameterized-type name="Seq">
 184             <template-type name="V"/>
 185           </parameterized-type>
 186         </type>
 187       </result>
 188       <description>
 189         <p>Lexiographic sorting of <arg name="values" /> according to the corresponding <arg name="keys" />.  If <arg name="values" /> is not provided, <arg name="keys" /> is used instead.</p>
 190         <p>The lexiographic order puts smaller values before larger ones, and if one array is a prefix of another, the prefix goes before.  The sorting is stable, that is, values associated with equal keys will follow the same order in the result as given in <arg name="values" />.</p>
 191         <p>By sorting based on arrays associated with values, rather than using a comparison function to compare the <arg name="values" /> directly, sorting will be much more efficient compared to <value name="sort" />.</p>
 192         <p>It is an error if <arg name="values" /> is present but does not have the same number of elements as <arg name="keys" />.</p>
 193         <example-with-output title="Lexiographic sorting" internal-id="example/lexiographicSort">
 194 <source file="doc/lexiographicSort.blank">
 195 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/lexiographicSort.blank" -->]]>
 196 </source>
 197 <stdout>
 198 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/lexiographicSort.stdout" -->]]>
 199 </stdout>
 200 <caption>
 201   <p>Lexiographic sorting.  First sorting integer arrays in lexiographic order.  Then sorting some string values by using the integer arrays as keys for sorting.  Finally deriving new integer arrays from the string values in order to achieve alphabetical sorting.</p>
 202 </caption>
 203         </example-with-output>
 204       </description>
 205       <see-also><value name="sort" /></see-also>
 206     </case>
 207     <case>
 208       <arguments>
 209         <arg identifier="keys">
 210           <type>
 211             <parameterized-type name="Seq">
 212               <parameterized-type name="Array">
 213                 <named-type name="Float"/>
 214               </parameterized-type>
 215             </parameterized-type>
 216           </type>
 217         </arg>
 218         <arg identifier="values">
 219           <type>
 220             <union-type>
 221             <parameterized-type name="Seq">
 222               <template-type name="V"/>
 223             </parameterized-type>
 224             <named-type name="Void" />
 225             </union-type>
 226           </type>
 227           <default><value-the-void /></default>
 228         </arg>
 229       </arguments>
 230       <result>
 231         <type>
 232           <parameterized-type name="Seq">
 233             <template-type name="V"/>
 234           </parameterized-type>
 235         </type>
 236       </result>
 237       <description>
 238         <p>Similar to the previous case, but for keys being arrays of <named-type name="Float" /> values.</p>
 239       </description>
 240     </case>
 241   </function>
 242 </system-binding>
 243
 244 <system-binding name="sort">
 245   <function>
 246     <type-templates>
 247       <template name="V">
 248         <description>
 249           <p>Type of values to be sorted.</p>
 250         </description>
 251       </template>
 252     </type-templates>
 253     <case>
 254       <arguments>
 255         <arg identifier="values">
 256           <type>
 257             <parameterized-type name="Seq">
 258               <template-type name="V"/>
 259             </parameterized-type>
 260           </type>
 261         </arg>
 262         <arg identifier="precedes?">
 263           <type>
 264             <function-type>
 265               <arguments>
 266                 <arg><type><template-type name="V"/></type></arg>
 267                 <arg><type><template-type name="V"/></type></arg>
 268               </arguments>
 269               <result><named-type name="Boolean" /></result>
 270             </function-type>
 271           </type>
 272         </arg>
 273       </arguments>
 274       <result>
 275         <type>
 276           <parameterized-type name="Seq">
 277             <template-type name="V"/>
 278           </parameterized-type>
 279         </type>
 280       </result>
 281       <description>
 282         <p>Sort values in increasing order according to a comparison function.  The comparison function <arg name="precedes?" /> shall be a strict precedence test.</p>
 283         <p>The sorting is stable, that is, values that compare equal (neither precedes the other) will follow the same order in the result as given in <arg name="values" />.</p>
 284         <p>The generality of using a comparison function comes at a performance penalty compared to the key-based sorting of <value name="lexiographicSort" />.  Hence, it is recommended to use <value name="lexiographicSort" /> for performance-critical tasks.  Use <self /> when performance is not critical or deriving keys for lexiographic sorting is difficult or contreived.</p>
 285         <note>
 286           <p>Part of the performance penalty lies in the bookkeeping in terms of setting up all the continuations for a full blown continuation passing style algorithm.  However, a worse problem may actually be that the <str-Shapes /> compiler currenty does no garbage collection of function environments.  This means that any program that does lots of functions calls has a problem, and sorting large amounts of data using a callback function clearly falls into this category.</p>
 287         </note>
 288         <p>To clarify how the <arg name="precedes?" /> test is applied, the following will sort the numbers in increasing order:
 289 <pre lang="Shapes">
 290 <![CDATA[[sort [list '5 '4 '6 '3 '2 '7 '1 '9 '8] (<)]]]>
 291 </pre>
 292         </p>
 293       </description>
 294       <see-also><value name="lexiographicSort" /></see-also>
 295     </case>
 296   </function>
 297 </system-binding>
 298
 299     </body>
 300   </section><!-- End of namespace/shapes/data/sequences -->
 301
 302
 303   <section id="namespace/shapes/data/array">
 304     <title>Arrays</title>
 305     <body>
 306
 307 <system-binding name="array">
 308   <function>
 309     <case constructor-of="Array">
 310       <arguments>
 311         <sink>
 312         </sink>
 313       </arguments>
 314       <description>
 315         <p>Constructs a vector of the arguments.</p>
 316       </description>
 317       <see-also><value name="unlist" /></see-also>
 318     </case>
 319   </function>
 320 </system-binding>
 321
 322 <system-binding name="newArray">
 323   <hot>
 324     <constructor-of><named-statetype name="Array" /></constructor-of>
 325     <description></description>
 326   </hot>
 327 </system-binding>
 328
 329     </body>
 330   </section><!-- End of namespace/shapes/data/array -->
 331
 332
 333   <section id="namespace/shapes/data/graphs">
 334     <title>Graphs</title>
 335     <body>
 336
 337
 338 <system-binding name="graph">
 339   <function>
 340     <type-templates>
 341       <template name="N">
 342         <description>
 343           <p>Type of node values.</p>
 344         </description>
 345       </template>
 346       <template name="E">
 347         <description>
 348           <p>Type of edge values.</p>
 349         </description>
 350       </template>
 351     </type-templates>
 352     <case constructor-of="Graph">
 353       <arguments>
 354         <arg identifier="nodes">
 355           <type>
 356             <parameterized-type name="Seq">
 357               <union-type>
 358                 <parameterized-type name="NodeData">
 359                   <template-type name="N" />
 360                 </parameterized-type>
 361                 <named-type name="GraphKey" />
 362               </union-type>
 363             </parameterized-type>
 364           </type>
 365           <default><value name="nil" /></default>
 366         </arg>
 367         <arg identifier="edges">
 368           <type>
 369             <parameterized-type name="Seq">
 370               <parameterized-type name="EdgeData">
 371                 <template-type name="E" />
 372               </parameterized-type>
 373             </parameterized-type>
 374           </type>
 375           <default><value name="nil" /></default>
 376         </arg>
 377         <arg identifier="directed">
 378           <type><named-type name="Boolean" /></type>
 379           <default><value-the-false /></default>
 380         </arg>
 381         <arg identifier="undirected">
 382           <type><named-type name="Boolean" /></type>
 383           <default><value-the-false /></default>
 384         </arg>
 385         <arg identifier="loops">
 386           <type><named-type name="Boolean" /></type>
 387           <default><value-the-false /></default>
 388         </arg>
 389         <arg identifier="parallel">
 390           <type><named-type name="Boolean" /></type>
 391           <default><value-the-false /></default>
 392         </arg>
 393         <arg identifier="partitions">
 394           <type>
 395             <union-type>
 396               <parameterized-type name="Seq">
 397                 <named-type name="GraphKey" />
 398               </parameterized-type>
 399               <named-type name="Void" />
 400             </union-type>
 401           </type>
 402           <default><value-the-void /></default>
 403         </arg>
 404       </arguments>
 405       <result>
 406         <type>
 407           <intersection-type>
 408             <parameterized-type name="Graph">
 409               <template-type name="N" />
 410               <template-type name="E" />
 411             </parameterized-type>
 412             <structure-type>
 413               <field name="directed?"><type><singleton-type><operator name="not" /> <arg name="undirected"/></singleton-type></type></field>
 414               <field name="undirected?"><type><singleton-type><operator name="not" /> <arg name="directed"/></singleton-type></type></field>
 415               <field name="mixed?"><type><singleton-type><arg name="directed"/> <operator name="and"/> <arg name="undirected"/></singleton-type></type></field>
 416               <field name="loops?"><type><singleton-type><arg name="loops"/></singleton-type></type></field>
 417               <field name="parallel?"><type><singleton-type><arg name="parallel"/></singleton-type></type></field>
 418             </structure-type>
 419           </intersection-type>
 420         </type>
 421       </result>
 422       <dynamic-references></dynamic-references>
 423       <description>
 424         <p>Functional construction of a graph.</p>
 425         <p>The <named-type name="Boolean" /> arguments define the graph domain, and it is an error if <arg name="edges" /> contains edges that are inconsistent with the graph domain.</p>
 426         <p>If <arg name="partitions" /> is present, each node must belong to one of the given partitions, and the graph will become a partitioned graph.  If <arg name="partitions" /> is <value-the-void />, the graph will not be considered partitioned and nodes are not allowed to specify a partition.</p>
 427         <p>Each node and edge in a graph can be identified by an index.  For nodes, the indices correspond to the positions in <arg name="nodes" /> (starting from zero).  For edges, however, the indices must not be assumed to have any particular relation to the order in <arg name="edges" />.</p>
 428         <p>The rather unwieldy type of this function states that if the <named-type name="Boolean" /> arguments can be evaluated at compile time, then the graph domain is encoded in the type of the result.  If the <named-type name="Boolean" /> arguments are not evaluated at compile time, the type of the result is just <parameterized-type name="Graph"><template-type name="N" /><template-type name="E" /></parameterized-type> with no information about the domain.</p>
 429       </description>
 430     </case>
 431   </function>
 432 </system-binding>
 433
 434 <system-binding name="walk">
 435   <function>
 436     <type-templates>
 437       <template name="N">
 438         <description>
 439           <p>Type of node values.</p>
 440         </description>
 441       </template>
 442       <template name="E">
 443         <description>
 444           <p>Type of edge values.</p>
 445         </description>
 446       </template>
 447     </type-templates>
 448     <case constructor-of="Walk">
 449       <arguments>
 450         <arg identifier="edges">
 451           <type>
 452             <parameterized-type name="Seq">
 453               <parameterized-type name="Edge">
 454                 <template-type name="N" />
 455                 <template-type name="E" />
 456               </parameterized-type>
 457             </parameterized-type>
 458           </type>
 459         </arg>
 460         <arg identifier="start">
 461           <type>
 462             <union-type>
 463               <parameterized-type name="Node">
 464                 <template-type name="N" />
 465                 <template-type name="E" />
 466               </parameterized-type>
 467               <named-type name="Void" />
 468             </union-type>
 469           </type>
 470           <default><value-the-void /></default>
 471         </arg>
 472         <arg identifier="end">
 473           <type>
 474             <union-type>
 475               <parameterized-type name="Node">
 476                 <template-type name="N" />
 477                 <template-type name="E" />
 478               </parameterized-type>
 479               <named-type name="Void" />
 480             </union-type>
 481           </type>
 482           <default><value-the-void /></default>
 483         </arg>
 484       </arguments>
 485       <result>
 486         <type>
 487           <parameterized-type name="Walk">
 488             <template-type name="N" />
 489             <template-type name="E" />
 490           </parameterized-type>
 491         </type>
 492       </result>
 493       <dynamic-references></dynamic-references>
 494       <description>
 495         <p>Construction of a walk in a graph.</p>
 496         <p>In all but two special situations it is enough just to specify the <arg name="edges" />, and the rest will be derived from the edges.  The first exceptions is empty paths, when there are no edges to derive at which node the walk starts and ends.  The second exception is walks consisting of a single undirected non-loop edge, where one cannot know which of the two nodes is the start and which is the end.  However, when writing code that has to work for any length of the walk, there is clearly a need to specify either <arg name="start" /> or <arg name="end" />.  Providing both <arg name="start" /> and <arg name="end" /> adds redundancy that might help detecting errors.</p>
 497         <p>Note that the arguments are not <named-type name="NodeData" /> and <named-type name="EdgeData" /> values, but nodes and edges of an existing graph.  It is an error if not all nodes and edges belong to the same graph.</p>
 498         <p>It is an error if <arg name="start" /> is not incident to the first edge, if <arg name="end" /> is not incident to the last edge, or if it is not possible to trace the sequence of edges.  If there are no edges, <arg name="start" /> and <arg name="end" /> must coincide.</p>
 499       </description>
 500     </case>
 501   </function>
 502 </system-binding>
 503
 504     </body>
 505   </section><!-- End of namespace/shapes/data/graphs -->
 506
 507
 508   <section id="namespace/shapes/data/misc">
 509     <title>Miscellaneous</title>
 510     <body>
 511
 512 <system-binding name="cons">
 513   <function>
 514     <type-templates>
 515       <template name="A">
 516         <description>
 517           <p>Type of <field name="car"/> field in result.</p>
 518         </description>
 519       </template>
 520       <template name="D">
 521         <description>
 522           <p>Type of <field name="cdr"/> field in result.</p>
 523         </description>
 524       </template>
 525     </type-templates>
 526     <case constructor-of="ConsPair">
 527       <arguments>
 528         <arg identifier="car"><type><template-type name="A" /></type></arg>
 529         <arg identifier="cdr"><type><template-type name="D" /></type></arg>
 530       </arguments>
 531       <result>
 532         <type>
 533           <parameterized-type name="ConsPair">
 534             <parameter-type name="A"/>
 535             <parameter-type name="D"/>
 536           </parameterized-type>
 537         </type>
 538       </result>
 539       <description>
 540         <p>Constructs a cons pair.  The arguments are not forced, which allows infinite data structures to be defined.</p>
 541         <p>Explicit forcing of the arguments (see <a part="syntax" id="syntax/misc-expr/laziness" />) may improve performance when there is no point to have evaluation delayed.  Also consider using <value name="fcons" /> instead of <self/>.</p>
 542         <p>Note that if <template-type name="D" /> is <parameterized-type name="Seq"><template-type name="A" /></parameterized-type>, then the result will also be a <parameterized-type name="Seq"><template-type name="A" /></parameterized-type>.  However, having the type <parameterized-type name="Seq"><template-type name="A" /></parameterized-type> is not the same as being as efficiently represented internally as if constructed with <value name="fcons" />.</p>
 543       </description>
 544       <see-also><value name="fcons" /></see-also>
 545     </case>
 546   </function>
 547 </system-binding>
 548
 549 <system-binding name="range">
 550   <function>
 551     <case constructor-of="Seq">
 552       <arguments>
 553         <arg identifier="begin">
 554           <type><named-type name="Integer" /></type>
 555         </arg>
 556         <arg identifier="end">
 557           <type><named-type name="Integer" /></type>
 558         </arg>
 559         <arg identifier="step">
 560           <type><named-type name="Integer" /></type>
 561         </arg>
 562         <arg identifier="count">
 563           <type><named-type name="Integer" /></type>
 564         </arg>
 565       </arguments>
 566       <description>
 567         <p>Constructs a range of <named-type name="Integer" /> values.  One of the arguments must be omitted, and it is forbidden to provide <arg name="begin" />, <arg name="end" />, and <arg name="count" /> at the same time.  It is allowed to omit both <arg name="step" /> and <arg name="count" />, in which case <arg name="step" /> defaults to (a positive) 1.</p>
 568         <p>See the <named-type name="Float" /> case for the semantics of the various argument combinations, and notes on efficiency.</p>
 569       </description>
 570     </case>
 571     <case constructor-of="Seq">
 572       <arguments>
 573         <arg identifier="begin">
 574           <type><named-type name="Float" /></type>
 575         </arg>
 576         <arg identifier="end">
 577           <type><named-type name="Float" /></type>
 578         </arg>
 579         <arg identifier="step">
 580           <type><named-type name="Float" /></type>
 581         </arg>
 582         <arg identifier="count">
 583           <type><named-type name="Integer" /></type>
 584         </arg>
 585       </arguments>
 586       <description>
 587         <p>Constructs a range of <named-type name="Float" /> values.  One of the arguments must be omitted.  It is allowed to omit both <arg name="step" /> and <arg name="count" />, in which case <arg name="step" /> defaults to (a positive) 1.</p>
 588         <p>If <arg name="step" /> is provided, it determines the step length.  If <arg name="count" /> is provided, it determines the number of elements in the constructed range, which will begin at <arg name="begin" /> if <arg name="begin" /> is provided, and end at <arg name="end" /> if <arg name="end" /> is provided (note that achieving this using <arg name="step" /> may be inconvenient or even difficult due to problems with numeric precision).  If neither <arg name="step" /> nor <arg name="count" /> is provided, <arg name="step" /> defaults to 1.</p>
 589         <p>When both <arg name="begin" /> and <arg name="end" /> are provided, the range starts at <arg name="begin" />, and ends at a value with is not <em>past</em> <arg name="end" />.  This is not like in <str-C-plus-plus />, where <em>end</em> refers to a point in a range which itself is past the end of the range.</p>
 590         <p><em>Note on efficiency:</em>  The result is constructed in constant time and space, and is particularly efficient for left folds.  Semantically, it is as if the whole range was stored element by element in a long list, but the kernel just stores the first element, the step, and the total number of elements.  During a left fold, at two values in the range are stored in memory at the same time.  A right fold, on the other hand, will require all elements to be constructed before they can be destructed again.  Hence, when possible, right folds should be avoided in favor of left folds over a range constructed with elements in the reverse order.</p>
 591       </description>
 592     </case>
 593     <case constructor-of="Seq">
 594       <arguments>
 595         <arg identifier="begin">
 596           <type><named-type name="Length" /></type>
 597         </arg>
 598         <arg identifier="end">
 599           <type><named-type name="Length" /></type>
 600         </arg>
 601         <arg identifier="step">
 602           <type><named-type name="Length" /></type>
 603         </arg>
 604         <arg identifier="count">
 605           <type><named-type name="Integer" /></type>
 606         </arg>
 607       </arguments>
 608       <description>
 609         <p>Constructs a range of <named-type name="Length" /> values.  One of the arguments must be omitted, and it is forbidden to omit both <arg name="step" /> and <arg name="count" />.</p>
 610         <p>See the <named-type name="Float" /> case for the semantics of the various argument combinations, and notes on efficiency.</p>
 611       </description>
 612     </case>
 613     <body>
 614       <example-with-output title="Range construction" internal-id="example:ranges">
 615 <source file="features/ranges.blank">
 616 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/ranges.blank" -->]]>
 617 </source>
 618 <stdout>
 619 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/ranges.stdout" -->]]>
 620 </stdout>
 621       </example-with-output>
 622     </body>
 623   </function>
 624   <see-also><value name="span" /></see-also>
 625 </system-binding>
 626
 627 <system-binding name="span">
 628   <function>
 629     <case constructor-of="Span">
 630       <arguments>
 631         <arg identifier="begin"></arg>
 632         <arg identifier="end"></arg>
 633         <arg identifier="step"></arg>
 634         <arg identifier="count"></arg>
 635       </arguments>
 636       <description>
 637         <p>Calling <self /> is like calling <value name="range" />, except that the arguments may use the special <syntax name="last-expr" /> expression to refer to the last position in a container.  Since the container will generally not be known at the time of the call, the arguments are not evaluated immediately, but stored as thunks inside <named-type name="Span" /> value.</p>
 638         <p>Since a <self /> should be used to select ranges of valid container positions, there are more defaults available when calling <self /> compared to <value name="range" />.  For instance, a span including all but the first two positions in a container can be constructed as
 639 <pre>
 640 <![CDATA[[span begin:'2]]]>
 641 </pre>
 642 and a span including all but the last two positions as
 643 <pre>
 644 <![CDATA[[span end:%last-'2]]]>
 645 </pre>
 646 </p>
 647         <p>Note that a <named-type name="Span" /> value is not automatically expanded to <named-type name="Seq" /> whenever a <named-type name="Seq" /> is expected, so it is up to the methods of the container types to accept <named-type name="Span" /> values and expand them.</p>
 648       </description>
 649       <see-also>
 650         <value name="range" /> <named-type name="String" />
 651       </see-also>
 652     </case>
 653   </function>
 654 </system-binding>
 655
 656     </body>
 657   </section><!-- End of namespace/shapes/data/misc -->
 658
 659 </book>