Download the PHP package jakewhiteley/php-sets without Composer

php-set-data-structure

A PHP implementation of a Java-like Set data structure.

A 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.

Implementation is based on the MDN JS Reference for Sets in EMCA 6 JavaScript.

Sets require a min PHP version of 7.4.

• Installation
• Basic usage:
  • Creating a Set
  • Adding values
  • Removing values
  • Testing if a value is present
  • Counting items
• Set Iteration
  • As a traditional Array
  • Using entries()
  • Using each
• Set operations
  • Union
  • Difference
  • Symmetric difference
  • Intersect
  • Subsets
• Set family operations
  • Family Union
  • Family Intersection

Installation

You can download the latest release via the releases link on this page.

PHP-Sets is available via Composer by running the following command:

`

then include the library in your project like so: ``

Basic Usage

Creating a Set

When you create a set, you can insert initial values or keep it empty. ``

Sets cannot contain duplicate values, and values are stored in insertion order. ``

If you have an array of elements, you can either pass in the array directly, or splat the array.

Adding values

Values of any type (Including Objects, arrays, and other Sets) are added to a set via the add() method.

It 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. ``

As Sets implements the ArrayAccess interface, you can also add values as you would with a standard Array. ``

Removing values

Values can be removed individually via delete(), or all at once via the clear() method. ``

You can also delete methods via ArrayAccess: ``

Testing if a value is present

You can easily test if a Set contains a value via the has($value) method.

As with the other methods, this is a strict type test.

``

Counting items

This is done using the count method: ``

Iteration

There are many ways to iterate a Set:

• Like a traditional PHP array
• Using entries() to return an instance of PHP's ArrayIterator
• Using each() and a provided callback function
• Using values() which returns a traditional PHP Array version of the Set

As a traditional Array

The Set object extends an ArrayObject, and can be iterated like a normal array: ``

Or if you want, you can iterate $set->values() instead.

Using entries()

The entries() method returns an ArrayIterator object. ``

Using each($callback, ...$args)

You can also iterate a Set via a provided callable method.

The callback is called with the current item as parameter 1, with any additional specified params passed after.

``

Set operations

Union

Appends a second Set onto a given Set without creating duplicates: ``

Difference

The difference() method will return a new Set containing values present in the original Set but not present in another.

This is also known as the relative complement. ``

Symmetric Difference

The symmetricDifference() method also returns a new Set but differs to the difference method in that it will return all uncommon values between both Sets.

``

Intersect

Returns a new Set containing the items common (present in both) between two sets: ``

Subsets

The isSupersetOf method returns a bool indicating if a given Set is a subset of the current Set.

The order of values does not matter, but a subset must only contain items present in the original Set:

``

Set family operations

If we have a collection of sets, for example { { 1,2,3 }, { 3,4,5 } , { 3, 5, 6, 7 } }, often called a family of sets in 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.

Note that, at present, these operations are implemented naively by iteratively calling the union and intersect methods above. More efficient implementations are possible and welcome.

Union of a Family of Sets

At present the family of sets needs to be in an array of Set objects:

Intersection of a Family of Sets

As with familyUnion, the family of sets needs to be in an array of Set objects:

Note that, contrary to Set Theory, the result of taking the intersection of an empty array results in an empty array. (In Set Theory the intersection of an empty family is undefined as it would be the 'set of all sets'.)

Contributing

Contributions and changes welcome! Just open an issue or submit a PR :muscle: