Astrologue-Website/developer/invercargill/index.html

<!doctype html>
<html lang="en-nz">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Invercargill — Astrologue Developer</title>
  <meta name="description" content="Invercargill is the Enumerable library for Vala — LINQ-style querying plus the Vector, Dictionary, Series and buffer data structures the whole Astrologue stack is written against. Free software, LGPL-3.0-or-later.">
  <meta name="color-scheme" content="light dark">
  <meta name="theme-color" content="#f2ebda" media="(prefers-color-scheme: light)">
  <meta name="theme-color" content="#0a0a12" media="(prefers-color-scheme: dark)">
  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Ccircle cx='32' cy='32' r='27' fill='none' stroke='%23a8801f' stroke-width='4'/%3E%3Cpath d='M32 8l6 18 18 6-18 6-6 18-6-18-18-6 18-6z' fill='%23a8801f'/%3E%3Ccircle cx='32' cy='32' r='4' fill='%23003078'/%3E%3C/svg%3E">
  <meta property="og:title" content="Invercargill — Astrologue Developer">
  <meta property="og:description" content="The Enumerable library for Vala: LINQ-style querying plus Vector, Dictionary, Series, buffers, sets and heaps — the foundation the Astrologue stack is written against.">
  <meta property="og:type" content="website">
  <link rel="stylesheet" href="../../assets/css/style.css">
</head>
<body>
  <a class="skip-link" href="#main">Skip to content</a>

  <header class="masthead">
    <div class="container masthead__inner">
      <a class="brand" href="../../">
        <img class="brand__logo brand__logo--light" src="../../assets/img/astrologue-light.png" width="392" height="89" alt="Astrologue">
        <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
      </a>
      <nav class="site-nav" aria-label="Primary">
        <ul class="site-nav__list">
          <li><a href="../../">Home</a></li>
          <li><a href="../../#news">News</a></li>
          <li><a href="../../#download">Download</a></li>
          <li><a href="../" aria-current="page">Developer</a></li>
          <li><a class="nav-cta" href="../../#download">Get Astrologue</a></li>
        </ul>
      </nav>
    </div>
  </header>

  <main id="main">

    <nav class="breadcrumb" aria-label="Breadcrumb">
      <div class="container">
        <ol>
          <li><a href="../../">Astrologue</a></li>
          <li><a href="../">Developer</a></li>
          <li aria-current="page">Invercargill</li>
        </ol>
      </div>
    </nav>

    <section class="docs-header">
      <div class="container">
        <p class="kicker"><span>Foundation · The collections beneath everything</span></p>
        <h1>Invercargill</h1>
        <p class="lede">The Enumerable library for Vala — LINQ-style querying plus the data structures the whole Astrologue stack is written against. Every row a database returns, every setting a server reads, every key a cryptographer signs passes through this library.</p>
        <dl class="docs-facts">
          <div><dt>Version</dt> <dd><code>1.0.0</code></dd></div>
          <div><dt>Licence</dt> <dd>LGPL-3.0-or-later</dd></div>
          <div><dt>Package</dt> <dd><code>usm&nbsp;install&nbsp;invercargill</code></dd></div>
          <div><dt>Language</dt> <dd>Vala</dd></div>
        </dl>
      </div>
    </section>

    <section class="band band--plain" id="docs">
      <div class="container docs-layout">

        <nav class="docs-toc" aria-label="On this page">
          <h2>On this page</h2>
          <ul>
            <li><a href="#overview">Overview</a></li>
            <li><a href="#features">Features</a></li>
            <li><a href="#installation">Installation</a></li>
            <li><a href="#usage">Usage &amp; documentation</a></li>
            <li><a href="#package">Package &amp; source</a></li>
          </ul>
        </nav>

        <div class="docs-prose">

          <header class="section-head" id="overview">
            <p class="kicker"><span>Overview</span></p>
            <h2>Why it exists</h2>
          </header>
          <p>Invercargill is a comprehensive data-manipulation library for the Vala programming language. Its central <code>Enumerable&lt;T&gt;</code> type makes working with data sets significantly more intuitive and less cognitively taxing, with a rich set of functional-programming tools for transformation, querying and manipulation.</p>
          <p>It exists because its author — a C# developer by trade — kept missing the operations the .NET <code>IEnumerable</code> interface provides. Unwilling to settle for LibGee, he rolled a library of his own and named it after New Zealand's southernmost city. It takes heavy inspiration from C#'s interface, adapted where Vala's nuances call for it, and adds unique functions and structures of its own.</p>
          <p>Today it is the foundation of the Astrologue stack: the query results of <a href="../invercargill-sql/">Invercargill-Sql</a> arrive as lazy <code>Enumerable</code> rows, <a href="../inversion/">Inversion</a> resolves its registrations through it, and every library above leans on its data structures instead of <code>GLib.ArrayList</code> or LibGee.</p>

          <header class="section-head" id="features">
            <p class="kicker"><span>Features</span></p>
            <h2>What it hands you</h2>
          </header>
          <ul class="docs-features">
            <li><strong>Enumerable everywhere.</strong> One interface for iteration, transformation, filtering, aggregation, set operations, ordering, partitioning and grouping — chained fluently.</li>
            <li><strong>Data structures.</strong> Vector, Series, SortedSeries, Dictionary, HashSet, Buffer, ByteBuffer, RingBuffer, PriorityQueue, Fifo and Lifo, each with a job.</li>
            <li><strong>Lazy evaluation.</strong> Sequences are computed as they are walked, with caching mechanisms for when a second pass should not recompute.</li>
            <li><strong>Parallel processing.</strong> Built-in parallel operations to leverage multi-core processors.</li>
            <li><strong>Numbers as sequences.</strong> Promotions turn an <code>Enumerable&lt;int&gt;</code> into a numeric view with <code>sum()</code>, <code>average()</code> and friends.</li>
            <li><strong>Attempts.</strong> Safe operation handling with error recovery, so a fallible step can be retried or abandoned without ceremony.</li>
          </ul>

          <header class="section-head" id="installation">
            <p class="kicker"><span>Installation</span></p>
            <h2>Getting the library</h2>
          </header>
          <p>With USM on your machine, one command acquires, builds and installs the library together with its C header, Vala binding and introspection:</p>
          <figure class="code-plate">
            <pre><code>usm install invercargill</code></pre>
            <figcaption>Installs from the Astrologue package repository.</figcaption>
          </figure>
          <p>From source, the library follows the stack's one-build discipline:</p>
          <figure class="code-plate">
            <pre><code>git clone &lt;the Invercargill repository&gt;
cd Invercargill
meson setup src build
ninja -C build
ninja -C build install</code></pre>
            <figcaption>The build lives in <code>src/</code>; the README and the package scripts agree on it.</figcaption>
          </figure>
          <p>Then compile against it with Vala's usual package mechanism:</p>
          <figure class="code-plate">
            <pre><code>valac --pkg invercargill-1 my-program.vala</code></pre>
            <figcaption>The <code>-1</code> suffix keeps the ABI generation honest.</figcaption>
          </figure>

          <header class="section-head" id="usage">
            <p class="kicker"><span>Usage &amp; documentation</span></p>
            <h2>Working with sequences</h2>
          </header>
          <p>Wrap anything enumerable — an array, a generic array, a stream — and work with it through the fluent API. These idioms are lifted from the library's own integration tests:</p>
          <figure class="code-plate">
            <pre><code>using Invercargill;

var items = Wrap.array(new int[] { 1, 2, 3, 4, 5 });
var result = items.aggregate&lt;int&gt;(0, (sum, item) =&gt; sum + item);
// result == 15

var words = Wrap.array(new string[] { "Hello", " ", "World", "!" });
var greeting = words.aggregate&lt;string&gt;("", (concat, item) =&gt; concat + item);
// greeting == "Hello World!"</code></pre>
            <figcaption>From <code>src/tests/Integration/EnumerableMethods.vala</code> — <code>aggregate</code> folds a sequence down to one value.</figcaption>
          </figure>
          <p>Predicates come in matched pairs, and empty sequences answer honestly:</p>
          <figure class="code-plate">
            <pre><code>var evens = Wrap.array(new int[] { 2, 4, 6, 8 });
evens.all(i =&gt; i % 2 == 0);   // true
evens.any(i =&gt; i == 5);       // false
evens.no(i =&gt; i % 2 == 1);    // true — nothing matches

var empty = Wrap.array(new int[] {});
empty.any();                  // false
empty.no();                   // true</code></pre>
            <figcaption><code>all</code>, <code>any</code> and <code>no</code> — the last is the existential negative LibGee never gave Vala.</figcaption>
          </figure>
          <p>Ordering and projection compose like their C# cousins:</p>
          <figure class="code-plate">
            <pre><code>var items = ClassToOrder.data();
var result = items.order_by&lt;int&gt;(i =&gt; i.id);
var ids     = result.select&lt;int&gt;(i =&gt; i.id);

var newest_first = items.order_by_descending&lt;string&gt;(i =&gt; i.name);</code></pre>
            <figcaption>From <code>src/tests/Integration/OrderBy.vala</code>.</figcaption>
          </figure>
          <p>The modifier vocabulary goes much further — <code>where()</code>, <code>from()</code>, <code>until()</code> for filtering; <code>select()</code>, <code>select_many()</code>, <code>cast()</code>, <code>of_type()</code> for transformation; <code>combine()</code>, <code>common()</code>, <code>exclude()</code>, <code>distinct()</code> for set operations; <code>take()</code>, <code>skip()</code>, <code>chunk()</code>, <code>window()</code> for partitioning; and <code>zip()</code>, <code>concat()</code>, <code>interleave()</code>, <code>cycle()</code> for combination.</p>

          <h3>The data structures</h3>
          <p>Alongside the query layer sit the collections the stack is actually written with — used in place of <code>GLib.ArrayList</code>, <code>GLib.List</code> and <code>GLib.HashTable</code>:</p>
          <figure class="code-plate">
            <pre><code>using Invercargill.DataStructures;

var data = new Vector&lt;int&gt;();
data.add(5);
data.add(15);
data.add(10);

var numbers = data.assert_promotion&lt;SignedNativeIntegers&gt;();
var mean = numbers.average();      // 10

var dict = new Dictionary&lt;int, string&gt;();
dict[1999] = "Billy";
dict[1962] = "John";
string? billy = dict.get_or_default(1999);</code></pre>
            <figcaption>From <code>src/tests/Integration/Numbers.vala</code> and <code>Dictionary.vala</code>. A promotion turns a plain sequence into a numeric view.</figcaption>
          </figure>
          <p>The full set: <strong>Vector</strong> (dynamic array), <strong>Series</strong> (linked list, efficient at both ends), <strong>SortedSeries</strong> (red-black tree, kept in order), <strong>Dictionary</strong> (key-value store), <strong>HashSet</strong> (hash table with tombstone deletion), <strong>Buffer</strong> and <strong>ByteBuffer</strong>, <strong>ImmutableBuffer</strong>, <strong>RingBuffer</strong> (circular, iterable forever), <strong>PriorityQueue</strong> (min-heap, thread-safe push/pop), and <strong>Fifo</strong>/<strong>Lifo</strong> (thread-safe queue and stack with blocking operations and unblocking support).</p>
          <p>The library also carries an expressions subsystem, property mapping, debugging utilities and the promotion system shown above. Its test suite — integration and speed — runs through <code>meson test</code> and through USM's <code>test</code> exec, so what is documented here is what is exercised.</p>

          <header class="section-head" id="package">
            <p class="kicker"><span>Package &amp; source</span></p>
            <h2>The ledger</h2>
          </header>
          <dl class="docs-package">
            <div><dt>Version</dt><dd><code>1.0.0</code> (from <code>MANIFEST.usm</code>)</dd></div>
            <div><dt>Licence</dt><dd>LGPL-3.0-or-later — free to run, study, share and improve; the LGPL keeps it free to link from any program.</dd></div>
            <div><dt>Package</dt><dd><code>usm install invercargill</code></dd></div>
            <div><dt>Provides</dt><dd><code>libinvercargill-1.so</code>, <code>invercargill-1.h</code>, <code>invercargill-1.vapi</code> + <code>.deps</code>, <code>invercargill-1.gir</code>, <code>invercargill-1.typelib</code>, <code>invercargill-1.pc</code></dd></div>
            <div><dt>Needs at runtime</dt><dd>GLib and GObject — nothing else. The foundation carries no dependencies of its own.</dd></div>
            <div><dt>Source</dt><dd>The repository <code>Tilo15/Invercargill</code> on the Astrologue forge (git over ssh, port 222). Free software: the licence guarantees your right to the source.</dd></div>
          </dl>

          <nav class="docs-siblings" aria-label="Built on Invercargill">
            <p>The libraries that stand on it directly:</p>
            <ul>
              <li><a href="../invercargill-json/">Invercargill-Json</a></li>
              <li><a href="../invercargill-sql/">Invercargill-Sql</a></li>
              <li><a href="../inversion/">Inversion</a></li>
            </ul>
          </nav>

          <nav class="docs-pager" aria-label="Project pages">
            <p class="docs-pager__up"><a href="../">All eleven</a></p>
            <a class="docs-pager__link docs-pager__link--next" href="../invercargill-json/">
              <span>Next in the catalogue</span>
              <strong>Invercargill-Json</strong>
            </a>
          </nav>

        </div>
      </div>
    </section>

  </main>

  <footer class="site-footer">
    <div class="container">
      <div class="footer-grid">
        <div class="foot-brand">
          <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
          <p>An operating system for change — kept for self sufficiency, resilience, and software freedom, so regular people can hold the power of general purpose computers in their own hands.</p>
        </div>
        <nav aria-label="The four freedoms">
          <p class="foot-title">The Four Freedoms</p>
          <ol class="freedoms">
            <li><strong>Run</strong> the software as you wish, for any purpose.</li>
            <li><strong>Study</strong> the source and change it to do your computing as you wish.</li>
            <li><strong>Share</strong> copies so you can help others.</li>
            <li><strong>Modify</strong> and publish your versions so everyone benefits.</li>
          </ol>
        </nav>
        <nav aria-label="Site">
          <p class="foot-title">Site</p>
          <ul class="foot-list">
            <li><a href="../../">Home</a></li>
            <li><a href="../../#news">News</a></li>
            <li><a href="../../#download">Download</a></li>
            <li><a href="../">Developer</a></li>
          </ul>
        </nav>
      </div>
      <p class="colophon">Set in Cinzel and EB Garamond (SIL Open Font License). Astrologue is free software, licensed GPL-3.0-or-later: take it, tend it, pass it on. The libraries are LGPL-3.0-or-later, so they remain free to link.</p>
    </div>
  </footer>
</body>
</html>