{"id":19017443,"url":"https://github.com/jakewhiteley/php-sets","last_synced_at":"2025-04-23T02:49:24.985Z","repository":{"id":56995925,"uuid":"59407710","full_name":"jakewhiteley/php-sets","owner":"jakewhiteley","description":"A implementation of a Java-like Set data structure for PHP. A Set allows storage of any value without duplicates which can be iterated in insertion order.","archived":false,"fork":false,"pushed_at":"2023-05-31T20:49:09.000Z","size":134,"stargazers_count":19,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-23T02:49:07.443Z","etag":null,"topics":["data-structures","insertion-order","php","php-sets","sets","unique-values"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jakewhiteley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-22T10:58:47.000Z","updated_at":"2024-12-20T11:45:24.000Z","dependencies_parsed_at":"2024-11-08T19:47:14.799Z","dependency_job_id":"8d92c93e-5102-49b7-82ff-90c2e579333e","html_url":"https://github.com/jakewhiteley/php-sets","commit_stats":{"total_commits":54,"total_committers":2,"mean_commits":27.0,"dds":0.03703703703703709,"last_synced_commit":"129b6c46909bc73f7902660bd39b45c5712e856e"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakewhiteley%2Fphp-sets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakewhiteley%2Fphp-sets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakewhiteley%2Fphp-sets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakewhiteley%2Fphp-sets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jakewhiteley","download_url":"https://codeload.github.com/jakewhiteley/php-sets/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250360250,"owners_count":21417717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-structures","insertion-order","php","php-sets","sets","unique-values"],"created_at":"2024-11-08T19:47:02.821Z","updated_at":"2025-04-23T02:49:24.967Z","avatar_url":"https://github.com/jakewhiteley.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Travis (.com)](https://img.shields.io/travis/com/jakewhiteley/php-sets?style=flat-square)](https://travis-ci.com/jakewhiteley/php-sets) [![Coveralls github](https://img.shields.io/coveralls/github/jakewhiteley/php-sets?style=flat-square)](https://coveralls.io/github/jakewhiteley/php-sets)\n\n# php-set-data-structure\nA PHP implementation of a Java-like Set data structure.\n\nA set is simply a group of unique things that can be iterated by the order they were inserted. So, a significant characteristic of any set is that it does not contain duplicates.\n\nImplementation is based on the [MDN JS Reference](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Set) for Sets in EMCA 6 JavaScript.\n\nSets require a min PHP version of 7.4.\n\n* [Installation](#installation)\n* [**Basic usage:**](#basic-usage)\n    * [Creating a Set](#creating-a-set)\n    * [Adding values](#adding-values)\n    * [Removing values](#removing-values)\n    * [Testing if a value is present](#testing-if-a-value-is-present)\n    * [Counting items](#counting-items)\n* [**Set Iteration**](#iteration)\n    * [As a traditional Array](#as-a-traditional-array)\n    * [Using `entries()`](#using-entries)\n    * [Using `each`](#using-eachcallback-args)\n* [**Set operations**](#set-operations)\n    * [Union](#union)\n    * [Difference](#difference)\n    * [Symmetric difference](#symmetric-difference)\n    * [Intersect](#intersect)\n    * [Subsets](#subsets)\n* [**Set family operations**](#set-family-operations)\n    * [Family Union](#union-of-a-family-of-sets)\n    * [Family Intersection](#intersection-of-a-family-of-sets)\n\n## Installation\nYou can download the latest release via the releases link on this page.\n\nPHP-Sets is available via [Composer](https://packagist.org/packages/jakewhiteley/php-sets) by running the following command:\n\n````bash\ncomposer require jakewhiteley/php-sets\n````\n\nthen include the library in your project like so:\n````php\ninclude('vendor/autoload.php');\n\nuse PhpSets\\Set;\n````\n\n\n## Basic Usage\n\n#### Creating a Set\n\nWhen you create a set, you can insert initial values or keep it empty.\n````php\n$set = new Set(1, 2, 3);\n$emptySet = new Set();\n````\n\nSets cannot contain duplicate values, and values are stored in insertion order.\n````php\n// $set contains [1, 2, 3] as duplicates are not stored\n$set = new Set(1, 2, 1, 3, 2);\n````\n\nIf you have an array of elements, you can either pass in the array directly, or splat the array.\n```php\n$set = new Set([1, 2, 1, 3, 2]);\n\n$array = [1, 2, 1, 3, 2];\n$set = new Set(...$array);\n```\n\n#### Adding values\nValues of any type (Including Objects, arrays, and other `Sets`) are added to a set via the `add()` method.\n\nIt is worth noting that uniqueness is on a **strict type** basis, so `(string) '1' !==  (int) 1 !==  (float) 1.0`. This also is true for Objects within the set and an object with a classA is not equal to an object with classB, even if the properties etc are the same.\n````php\n// create empty Set\n$set = new Set(); \n\n$set-\u003eadd('a');\n// $set =\u003e ['a']\n\n$set-\u003eadd(1);\n// $set =\u003e ['a', 1]\n````\n\nAs `Sets` implements the `ArrayAccess` interface, you can also add values as you would with a standard Array.\n````php\n$set = new Set();\n\n$set[] = 1;\n$set[] = 'foo';\n// $set =\u003e [1, 'foo']\n\n\n// You can also replace values by key, provided the new value is unique within the Set\n$set[0] = 2;\n// $set =\u003e [2, 'foo']\n\n// If a key is not currently in the array, the value is appended to maintain insertion order\n$set[4] = 'foo';\n// $newSet =\u003e [2, 'foo', 'foo']\n````\n\n#### Removing values\nValues can be removed individually via `delete()`, or all at once via the `clear()` method.\n````php\n$set = new Set(1, 2, 3);\n\n$set-\u003edelete(2);\n// $set =\u003e [1, 3]\n\n$set-\u003eclear();\n// $set =\u003e []\n````\n\nYou can also delete methods via `ArrayAccess`:\n````php\n$set = new Set(1, 2, 3);\n\nunset($set[0]);\n// $set =\u003e [2, 3]\n````\n\n#### Testing if a value is present\nYou can easily test if a `Set` contains a value via the `has($value)` method.\n\nAs with the other methods, this is a **strict type** test.\n\n````php\n$set = new Set('a', [1, 2], 1.0);\n\n$set-\u003ehas('a');      // true\n$set-\u003ehas([1, 2]);   // true\n$set-\u003ehas(1);        // false\n$set-\u003ehas([1, '2']); // false\n$set-\u003ehas('foo');    // false\n````\n\n\n#### Counting items\nThis is done using the `count` method:\n````php\n$set = new Set(1, 2, 3);\n\necho $set-\u003ecount(); // 3\n````\n\n\n\n\n## Iteration\nThere are many ways to iterate a `Set`:\n* Like a traditional PHP array\n* Using `entries()` to return an instance of PHP's `ArrayIterator`\n* Using `each()` and a provided callback function\n* Using `values()` which returns a traditional PHP Array version of the Set\n\n#### As a traditional Array\nThe Set object extends an `ArrayObject`, and can be iterated like a normal array:\n````php\n$set = new Set(1, 2);\n\nforeach ($set as $val) {\n    print($val);\n}\n````\n\nOr if you want, you can iterate `$set-\u003evalues()` instead.\n\n#### Using `entries()`\nThe `entries()` method returns an [ArrayIterator](http://php.net/manual/en/class.arrayiterator.php) object.\n````php\n$iterator = $set-\u003eentries();\n\nwhile ($iterator-\u003evalid()) {\n    echo $iterator-\u003ecurrent();\n    $iterator-\u003enext();\n}\n````\n\n#### Using `each($callback, ...$args)`\nYou can also iterate a `Set` via a provided [callable](https://www.php.net/manual/en/language.types.callable.php) method. \n\nThe callback is called with the current item as parameter 1, with any additional specified params passed after.\n\n````php\nfunction cb($item, $parameter) {\n  echo $item * $parameter;\n}\n\n$set = new Set(1, 2);\n\n$set-\u003eeach('cb', 10);\n// prints 10 20\n````\n\n\n## Set operations\n\n#### Union\nAppends a second `Set` onto a given `Set` without creating duplicates:\n````php\n$a = new Set(1, 2, 3);\n$b = new Set(2, 3, 4);\n\n$merged = $a-\u003eunion($b);\n\nprint_r($merged-\u003evalues()); // [1, 2, 3, 4]\n````\n\n#### Difference\nThe `difference()` method will return a new `Set` containing values present in the original `Set` but not present in another. \n\nThis is also known as the _relative complement_.\n````php\n$a = new Set(1, 2, 3, 4);\n$b = new Set(3, 4, 5, 6);\n\nprint_r($a-\u003edifference($b)-\u003evalues()); // [1, 2]\nprint_r($b-\u003edifference($a)-\u003evalues()); // [5, 6]\n````\n\n#### Symmetric Difference\nThe `symmetricDifference()` method also returns a new `Set` but differs to the `difference` method in that it will return **all** uncommon values between both `Sets`.\n\n````php\n$a = new Set(1, 2, 3, 4);\n$b = new Set(3, 4, 5, 6);\n\nprint_r($a-\u003esymmetricDifference($b)-\u003evalues()); // [1, 2, 5, 6]\n````\n\n#### Intersect\nReturns a new `Set` containing the items common (present in both) between two sets:\n````php\n$a = new Set(1, 2, 3);\n$b = new Set(2, 3, 4);\n\n$intersect = $a-\u003eintersect($b);\n\nprint_r($intersect-\u003evalues()); // [2, 3]\n````\n\n#### Subsets\nThe `isSupersetOf` method returns a `bool` indicating if a given `Set` is a subset of the current `Set`.\n\nThe order of values does not matter, but a subset must only contain items present in the original `Set`:\n\n````php\n$a = new Set(1, 2, 3);\n$b = new Set(2, 3);\n\nvar_Dump($b-\u003eisSupersetOf($a)); // true\nvar_Dump($a-\u003eisSupersetOf($b)); // false\n````\n\n## Set family operations\n\nIf we have a collection of sets, for example `{ { 1,2,3 }, { 3,4,5 } , { 3, 5, 6, 7 } }`, often called a *family* of sets\nin Set Theory, we can take the union and intersection of the family. That is, `( { 1, 2, 3 } union { 3, 4, 5 } ) union { 3, 5, 6, 7 }` and likewise for intersection. In Set Theory a large union and intersection symbol is used for this purpose.\n\nNote that, at present, these operations are implemented\nnaively by iteratively calling the `union` and `intersect`\nmethods above. More efficient implementations are possible\nand welcome.\n\n#### Union of a Family of Sets\n\nAt present the family of sets needs to be in an array of `Set` objects:\n```php\n$set1 = Set(1, 2, 3);\n$set2 = Set(3, 4, 5);\n$set2 = Set(5, 1, 6);\n\n$set_union = Set::familyUnion([$set1, $set2]); // [1, 2, 3, 4, 5, 6]\n```\n\n#### Intersection of a Family of Sets\n\nAs with `familyUnion`, the family of sets needs to be in an array of `Set` objects:\n```php\n$set1 = Set(1,2,3);\n$set2 = Set(3,4,5);\n$set_family = [ $set1, $set2 ];\n$set_intersection = Set::familyIntersection($set_family);\n```\n\nNote that, contrary to Set Theory, the result of\ntaking the intersection of an empty array results\nin an empty array. (In Set Theory the intersection\nof an empty family is undefined as it would be the\n['set of all sets'](https://en.wikipedia.org/wiki/Universal_set).)\n\n### Contributing\nContributions and changes welcome! Just open an issue or submit a PR :muscle:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakewhiteley%2Fphp-sets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjakewhiteley%2Fphp-sets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakewhiteley%2Fphp-sets/lists"}