PHP Ds\Map Functions

A Map in PHP is a collection of key-value pairs, similar to an array. However, the keys in a Map can be of any type and must be unique. If you add a value with an existing key, the old value will be replaced with the new one. Maps are an efficient data structure in PHP 7 and offer an alternative to arrays.

Requirements

To use Maps, you need PHP 7. Both the extension and compatibility polyfill require PHP 7.

Installation

The easiest way to install the data structure is by using the PECL extension. Use the following command:

pecl install ds

Syntax

You can use Ds\Map functions with the following syntax:

public Ds\Map::functionName()

Example: Using Ds\Map::filter() Function

Here's an example of how to use the `filter()` function with Ds\Map in PHP:

<?php
// Create a Map
$map = new \Ds\Map([
    1 => "Welcome",
    2 => "to",
    3 => "Geeks",
    4 => "for",
    5 => "Geeks"
]);

// Display new sequence using filter function
var_dump($map->filter(function($key, $val) {
    return $key % 3 == 0;
}));
?>

Output

The above code will produce the following output:

object(Ds\Map)#3 (1) {
  [0]=>
  object(Ds\Pair)#2 (2) {
    ["key"]=>
    int(3)
    ["value"]=>
    string(5) "Geeks"
  }
}

In this example, the `filter()` function creates a new Map containing only the elements where the key is divisible by 3.

Complete list of data structure DS\Map:

Ds\Map Functions	Description
allocate(capacity)	Allocate enough memory for the map to hold a specific number of elements (`capacity`). This pre-allocates space to potentially avoid performance overhead during insertions.
apply(callback)	Apply a callback function to each value in the map. The callback function takes the current element value and key as arguments and can modify the element in-place.
capacity()	Return the current maximum number of elements the map can hold without needing reallocation.
clear()	Remove all elements from the map.
__construct([iterable])	**Optional:** Create a new map instance. You can optionally provide an iterable object (like an array) to populate the map initially.
copy()	Create a new map that is a shallow copy of the original map. Changes to the original map will not be reflected in the copy, and vice versa.
count()	Return the number of key-value pairs currently in the map.
diff(otherMap)	Create a new map containing only the key-value pairs that are present in the first map but not in the `otherMap`.
filter(callback)	Create a new map containing only the key-value pairs that pass a test defined by the callback function. The callback function takes the current value and key as arguments and should return true to keep the pair or false to exclude it.
first()	Return the first key-value pair (oldest entry) from the map.
get(key)	Return the value associated with the given key, or null if the key is not found.
hasKey(key)	Check whether the map contains a specific key.
hasValue(value)	Check whether the map contains a specific value (regardless of the associated key).
intersect(otherMap)	Create a new map containing only the key-value pairs that are present in both the current map and the `otherMap`.
isEmpty()	Check whether the map is empty (contains no elements).
keys()	Return a new iterator containing all the keys in the map.
ksort([comparison_function])	Sort the map elements in-place by key. You can optionally provide a comparison function to define the sorting order.
ksorted([comparison_function])	Create a new map containing a copy of the elements sorted by key. You can optionally provide a comparison function to define the sorting order.
last()	Return the last key-value pair (newest entry) from the map.
map(callback)	Create a new map by applying a callback function to each value in the original map. The callback function takes the current element value and key as arguments, and its return value becomes the value in the new map.
merge(otherMap)	Add all key-value pairs from the `otherMap` to the current map. If a key already exists in the current map, the value from the `otherMap` will overwrite the existing value.
pairs()	Return a new iterator containing all the key-value pairs in the map.
put(key, value)	Associate a value with a specific key in the map.
putAll(iterable)	Associate all key-value pairs from a traversable object (like an array) with the map.
reduce(callback, initial_value)	Reduce the map to a single value by applying a callback function to each key-value pair sequentially. The callback function takes the accumulated result, the current value, and the current key as arguments and returns a new accumulated value.
reverse()	Reverse the order of key-value pairs in the map in-place.
reversed()	Create a new map containing a copy of the elements with the order reversed.
skip(offset)	Return the key-value pair at a specific positional index in the map. The index starts from 0.
slice(offset, length)	Get a sub-map containing a range of key-value pairs from the original map.
sort([comparison_function])	Sort the map elements in-place by value. You can optionally provide a comparison function to define the sorting order.
sorted([comparison_function])	Create a new map containing a copy of the elements sorted by value. You can optionally provide a comparison function to define the sorting order.
sum()	Get the sum of all the values present in the map.
toArray()	Convert the map to a regular PHP array. The array will contain key-value pairs.
union(otherMap)	Create a new map containing the combined key-value pairs from both the current map and the `otherMap`. If a key exists in both maps, the value from the current map will be used.
values()	Return a new iterator containing all the values in the map.
xor(otherMap)	Create a new map containing key-value pairs that are present in either the current map or the `otherMap`, but not in both.