First draft

.github/workflows/ci.yml

@@ -4,11 +4,11 @@ on: [push, pull_request]
 
 jobs:
   blackbox:
-    uses: innmind/github-workflows/.github/workflows/black-box-matrix.yml@next
+    uses: innmind/github-workflows/.github/workflows/black-box-matrix.yml@main
   coverage:
-    uses: innmind/github-workflows/.github/workflows/coverage-matrix.yml@next
+    uses: innmind/github-workflows/.github/workflows/coverage-matrix.yml@main
     secrets: inherit
   psalm:
-    uses: innmind/github-workflows/.github/workflows/psalm-matrix.yml@next
+    uses: innmind/github-workflows/.github/workflows/psalm-matrix.yml@main
   cs:
-    uses: innmind/github-workflows/.github/workflows/cs.yml@next
+    uses: innmind/github-workflows/.github/workflows/cs.yml@main

README.md

@@ -1,10 +1,10 @@
-# mutable
+# Mutable
 
-[![Build Status](https://github.com/innmind/mutable/workflows/CI/badge.svg?branch=main)](https://github.com/innmind/mutable/actions?query=workflow%3ACI)
+[![Build Status](https://github.com/Innmind/mutable/actions/workflows/ci.yml/badge.svg)](https://github.com/Innmind/mutable/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/innmind/mutable/branch/develop/graph/badge.svg)](https://codecov.io/gh/innmind/mutable)
 [![Type Coverage](https://shepherd.dev/github/innmind/mutable/coverage.svg)](https://shepherd.dev/github/innmind/mutable)
 
-Description
+This a collection of mutable data structures.
 
 ## Installation
 
@@ -14,4 +14,10 @@ composer require innmind/mutable
 
 ## Usage
 
-Todo
+Available structures:
+
+- `Innmind\Mutable\Map`
+- `Innmind\Mutable\Queue` FIFO queue
+- `Innmind\Mutable\Ring` Circle through a fixed sequence of data in an infinite loop
+- `Innmind\Mutable\Set`
+- `Innmind\Mutable\Stack` LIFO queue

blackbox.php

@@ -11,7 +11,7 @@
 
 Application::new($argv)
     ->when(
-        \get_env('ENABLE_COVERAGE') !== false,
+        \getenv('ENABLE_COVERAGE') !== false,
         static fn(Application $app) => $app 
             ->scenariiPerProof(1)
             ->codeCoverage(

composer.json

@@ -15,15 +15,16 @@
         "issues": "http://github.com/innmind/mutable/issues"
     },
     "require": {
-        "php": "~8.4"
+        "php": "~8.4",
+        "innmind/immutable": "~6.0"
     },
     "autoload": {
         "psr-4": {
             "Innmind\\Mutable\\": "src/"
         }
     },
     "require-dev": {
-        "innmind/static-analysis": "^1.2.1",
+        "innmind/static-analysis": "~1.3",
         "innmind/black-box": "~6.5",
         "innmind/coding-standard": "~2.0"
     }

proofs/queue.php

@@ -0,0 +1,43 @@
+<?php
+declare(strict_types = 1);
+
+use Innmind\Mutable\Queue;
+use Innmind\BlackBox\Set;
+
+return static function() {
+    yield proof(
+        'Queue',
+        given(
+            Set::sequence(Set::type()),
+        ),
+        static function($assert, $values) {
+            $queue = Queue::of();
+
+            $assert->same(0, $queue->size());
+            $assert->true($queue->empty());
+
+            foreach ($values as $i => $value) {
+                $queue->push($value);
+
+                $assert->false($queue->empty());
+                $assert->same($i + 1, $queue->size());
+            }
+
+            $pulled = [];
+            $size = $queue->size();
+
+            foreach ($values as $i => $_) {
+                $pulled[] = $queue->pull()->match(
+                    static fn($value) => $value,
+                    static fn() => null,
+                );
+
+                $assert->same($size - 1, $queue->size());
+                $size = $queue->size();
+            }
+
+            $assert->true($queue->empty());
+            $assert->same($values, $pulled);
+        },
+    );
+};

proofs/ring.php

@@ -0,0 +1,79 @@
+<?php
+declare(strict_types = 1);
+
+use Innmind\Mutable\Ring;
+use Innmind\BlackBox\Set;
+
+return static function() {
+    yield proof(
+        'Ring',
+        given(
+            Set::sequence(Set::type())->atLeast(1),
+            Set::integers()->between(1, 10),
+        ),
+        static function($assert, $values, $rotations) {
+            $ring = Ring::of(...$values);
+            $pulled = [];
+
+            foreach (\range(1, $rotations) as $_) {
+                foreach (\range(1, \count($values)) as $__) {
+                    $pulled[] = $ring->pull()->match(
+                        static fn($value) => $value,
+                        static fn() => null,
+                    );
+                }
+            }
+
+            $expected = \array_merge(
+                ...\array_fill(
+                    0,
+                    $rotations,
+                    $values,
+                ),
+            );
+
+            $assert->same($expected, $pulled);
+        },
+    );
+
+    yield proof(
+        'Partial Ring rotations',
+        given(
+            Set::sequence(Set::type())->atLeast(1),
+            Set::integers()->between(1, 1_000),
+        ),
+        static function($assert, $values, $toPull) {
+            $ring = Ring::of(...$values);
+            $pulled = [];
+
+            foreach (\range(1, $toPull) as $_) {
+                $pulled[] = $ring->pull()->match(
+                    static fn($value) => $value,
+                    static fn() => null,
+                );
+            }
+
+            $expected = \array_slice(
+                \array_merge(
+                    ...\array_fill(
+                        0,
+                        (int) \ceil($toPull / \count($values)),
+                        $values,
+                    ),
+                ),
+                0,
+                $toPull,
+            );
+
+            $assert->same($expected, $pulled);
+        },
+    );
+
+    yield test(
+        'Empty Ring returns nothing',
+        static fn($assert) => $assert->false(Ring::of()->pull()->match(
+            static fn() => true,
+            static fn() => false,
+        )),
+    );
+};

proofs/stack.php

@@ -0,0 +1,43 @@
+<?php
+declare(strict_types = 1);
+
+use Innmind\Mutable\Stack;
+use Innmind\BlackBox\Set;
+
+return static function() {
+    yield proof(
+        'Stack',
+        given(
+            Set::sequence(Set::type()),
+        ),
+        static function($assert, $values) {
+            $stack = Stack::of();
+
+            $assert->same(0, $stack->size());
+            $assert->true($stack->empty());
+
+            foreach ($values as $i => $value) {
+                $stack->push($value);
+
+                $assert->false($stack->empty());
+                $assert->same($i + 1, $stack->size());
+            }
+
+            $pulled = [];
+            $size = $stack->size();
+
+            foreach ($values as $i => $_) {
+                $pulled[] = $stack->pull()->match(
+                    static fn($value) => $value,
+                    static fn() => null,
+                );
+
+                $assert->same($size - 1, $stack->size());
+                $size = $stack->size();
+            }
+
+            $assert->true($stack->empty());
+            $assert->same(\array_reverse($values), $pulled);
+        },
+    );
+};

psalm.xml

@@ -14,4 +14,7 @@
             <directory name="vendor" />
         </ignoreFiles>
     </projectFiles>
+    <issueHandlers>
+        <UndefinedAttributeClass errorLevel="suppress" />
+    </issueHandlers>
 </psalm>