{"id":15032747,"url":"https://github.com/aimeos/map","last_synced_at":"2025-05-12T13:08:23.359Z","repository":{"id":39006526,"uuid":"222356890","full_name":"aimeos/map","owner":"aimeos","description":"PHP arrays and collections made easy","archived":false,"fork":false,"pushed_at":"2025-03-07T10:57:36.000Z","size":964,"stargazers_count":3594,"open_issues_count":1,"forks_count":17,"subscribers_count":9,"default_branch":"3.x","last_synced_at":"2025-04-23T15:54:30.038Z","etag":null,"topics":["array","collection","map","php","php-arrays","php-map"],"latest_commit_sha":null,"homepage":"http://php-map.org","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aimeos.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":"2019-11-18T03:35:21.000Z","updated_at":"2025-04-22T20:21:23.000Z","dependencies_parsed_at":"2024-07-30T14:30:24.964Z","dependency_job_id":"27dcfacf-e23c-4371-9cb6-8afd72771e2b","html_url":"https://github.com/aimeos/map","commit_stats":{"total_commits":365,"total_committers":3,"mean_commits":"121.66666666666667","dds":"0.021917808219178103","last_synced_commit":"41f9f11ca7f3dbc0397436f56c32e85102e06971"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimeos%2Fmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimeos%2Fmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimeos%2Fmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimeos%2Fmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aimeos","download_url":"https://codeload.github.com/aimeos/map/tar.gz/refs/heads/3.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745155,"owners_count":21957317,"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":["array","collection","map","php","php-arrays","php-map"],"created_at":"2024-09-24T20:19:20.386Z","updated_at":"2025-05-12T13:08:23.254Z","avatar_url":"https://github.com/aimeos.png","language":"PHP","readme":"\u003ca class=\"badge\" href=\"https://github.com/aimeos/map/actions\"\u003e\u003cimg src=\"https://github.com/aimeos/map/actions/workflows/php.yml/badge.svg\" alt=\"Build Status\" height=\"20\"\u003e\u003c/a\u003e\n\u003ca class=\"badge\" href=\"https://coveralls.io/github/aimeos/map\"\u003e\u003cimg src=\"https://coveralls.io/repos/github/aimeos/map/badge.svg\" alt=\"Coverage Status\" height=\"20\"\u003e\u003c/a\u003e\n\u003ca class=\"badge\" href=\"https://packagist.org/packages/aimeos/map\"\u003e\u003cimg src=\"https://poser.pugx.org/aimeos/map/license.svg\" alt=\"License\" height=\"20\"\u003e\u003c/a\u003e\n\u003ca class=\"badge\" href=\"https://packagist.org/packages/aimeos/map\"\u003e\u003cimg src=\"https://poser.pugx.org/aimeos/map/v/stable\" alt=\"Latest Stable Version\" height=\"20\"\u003e\u003c/a\u003e\n\u003ca class=\"badge\" href=\"https://packagist.org/packages/aimeos/map\"\u003e\u003cimg src=\"https://badgen.net/github/stars/aimeos/map\" alt=\"Stars\" height=\"20\"\u003e\u003c/a\u003e\n\u003ca class=\"badge\" href=\"https://packagist.org/packages/aimeos/map\"\u003e\u003cimg src=\"https://poser.pugx.org/aimeos/map/downloads\" alt=\"Downloads\" height=\"20\"\u003e\u003c/a\u003e\n\n# PHP arrays and collections made easy\n\nEasy and elegant handling of PHP arrays by using an array-like collection object\nas offered by jQuery and Laravel Collections.\n\n```bash\ncomposer req aimeos/map\n```\n\nSupported PHP versions:\n\n* PHP 7.1+\n* PHP 8+\n\n**Table of contents**\n\n* [Why PHP Map](#why-php-map)\n* [List of methods](#methods)\n    * [Create](#create)\n    * [Access](#access)\n    * [Add](#add)\n    * [Aggregate](#aggregate)\n    * [Debug](#debug)\n    * [Order](#order-by)\n    * [Shorten](#shorten)\n    * [Test](#test)\n    * [Mutate](#mutate)\n    * [Misc](#misc)\n* [Documentation](#method-documentation)\n* [Custom methods](#custom-methods)\n* [Performance](#performance)\n* [Upgrade guide](#upgrade-guide)\n\n## Why PHP Map\n\n**Instead of:**\n\n```php\n$list = [['id' =\u003e 'one', 'value' =\u003e 'value1'], ['id' =\u003e 'two', 'value' =\u003e 'value2'], null];\n$list[] = ['id' =\u003e 'three', 'value' =\u003e 'value3'];    // add element\nunset( $list[0] );                                   // remove element\n$list = array_filter( $list );                       // remove empty values\nsort( $list );                                       // sort elements\n$pairs = array_column( $list, 'value', 'id' );       // create ['three' =\u003e 'value3']\n$value = reset( $pairs ) ?: null;                    // return first value\n```\n\n**Only use:**\n\n```php\n$list = [['id' =\u003e 'one', 'value' =\u003e 'value1'], ['id' =\u003e 'two', 'value' =\u003e 'value2'], null];\n$value = map( $list )                                // create Map\n    -\u003epush( ['id' =\u003e 'three', 'value' =\u003e 'value3'] ) // add element\n    -\u003eremove( 0 )                                    // remove element\n    -\u003efilter()                                       // remove empty values\n    -\u003esort()                                         // sort elements\n    -\u003ecol( 'value', 'id' )                           // create ['three' =\u003e 'value3']\n    -\u003efirst();                                       // return first value\n```\n\n**You can still use:**\n\n```php\n$map[] = ['id' =\u003e 'three', 'value' =\u003e 'value3'];\n$value = $map[0];\ncount( $map );\nforeach( $map as $key =\u003e value );\n```\n\n**Use callbacks:**\n\nAlso, the map object allows you to pass anonymous functions to a lot of methods, e.g.:\n\n```php\n$map-\u003eeach( function( $val, $key ) {\n\techo $key . ': ' . $val;\n} );\n```\n\n**jQuery style:**\n\nIf your map elements are objects, you can call their methods for each object and get\nthe result as new map just like in jQuery:\n\n```php\n// MyClass implements setStatus() (returning $this) and getCode() (initialized by constructor)\n\n$map = Map::from( ['a' =\u003e new MyClass( 'x' ), 'b' =\u003e new MyClass( 'y' )] );\n$map-\u003esetStatus( 1 )-\u003egetCode()-\u003etoArray();\n```\n\nThis will call `setStatus( 1 )` on both objects. If `setStatus()` implementation\nreturns `$this`, the new map will also contain:\n\n```php\n['a' =\u003e MyClass(), 'b' =\u003e MyClass()]\n```\n\nOn those new map elements, `getCode()` will be called which returns `x` for the\nfirst object and `y` for the second. The map created from the results of `getCode()`\nwill return:\n\n```php\n['a' =\u003e 'x', 'b' =\u003e 'y']\n```\n\n\n## Methods\n\n\u003cnav\u003e\n\n\u003ca href=\"#is_map-function\"\u003efunction is_map\u003c/a\u003e\n\u003ca href=\"#map-function\"\u003efunction map\u003c/a\u003e\n\u003ca href=\"#__construct\"\u003e__construct\u003c/a\u003e\n\u003ca href=\"#__call\"\u003e__call\u003c/a\u003e\n\u003ca href=\"#__callstatic\"\u003e__callStatic\u003c/a\u003e\n\u003ca href=\"#after\"\u003eafter\u003c/a\u003e\n\u003ca href=\"#all\"\u003eall\u003c/a\u003e\n\u003ca href=\"#any\"\u003eany\u003c/a\u003e\n\u003ca href=\"#arsort\"\u003earsort\u003c/a\u003e\n\u003ca href=\"#arsorted\"\u003earsorted\u003c/a\u003e\n\u003ca href=\"#asort\"\u003easort\u003c/a\u003e\n\u003ca href=\"#asorted\"\u003easorted\u003c/a\u003e\n\u003ca href=\"#at\"\u003eat\u003c/a\u003e\n\u003ca href=\"#avg\"\u003eavg\u003c/a\u003e\n\u003ca href=\"#before\"\u003ebefore\u003c/a\u003e\n\u003ca href=\"#bool\"\u003ebool\u003c/a\u003e\n\u003ca href=\"#call\"\u003ecall\u003c/a\u003e\n\u003ca href=\"#cast\"\u003ecast\u003c/a\u003e\n\u003ca href=\"#chunk\"\u003echunk\u003c/a\u003e\n\u003ca href=\"#clear\"\u003eclear\u003c/a\u003e\n\u003ca href=\"#clone\"\u003eclone\u003c/a\u003e\n\u003ca href=\"#col\"\u003ecol\u003c/a\u003e\n\u003ca href=\"#collapse\"\u003ecollapse\u003c/a\u003e\n\u003ca href=\"#combine\"\u003ecombine\u003c/a\u003e\n\u003ca href=\"#concat\"\u003econcat\u003c/a\u003e\n\u003ca href=\"#contains\"\u003econtains\u003c/a\u003e\n\u003ca href=\"#copy\"\u003ecopy\u003c/a\u003e\n\u003ca href=\"#count\"\u003ecount\u003c/a\u003e\n\u003ca href=\"#countby\"\u003ecountBy\u003c/a\u003e\n\u003ca href=\"#dd\"\u003edd\u003c/a\u003e\n\u003ca href=\"#delimiter\"\u003edelimiter\u003c/a\u003e\n\u003ca href=\"#diff\"\u003ediff\u003c/a\u003e\n\u003ca href=\"#diffassoc\"\u003ediffAssoc\u003c/a\u003e\n\u003ca href=\"#diffkeys\"\u003ediffKeys\u003c/a\u003e\n\u003ca href=\"#dump\"\u003edump\u003c/a\u003e\n\u003ca href=\"#duplicates\"\u003eduplicates\u003c/a\u003e\n\u003ca href=\"#each\"\u003eeach\u003c/a\u003e\n\u003ca href=\"#empty\"\u003eempty\u003c/a\u003e\n\u003ca href=\"#equals\"\u003eequals\u003c/a\u003e\n\u003ca href=\"#every\"\u003eevery\u003c/a\u003e\n\u003ca href=\"#except\"\u003eexcept\u003c/a\u003e\n\u003ca href=\"#explode\"\u003eexplode\u003c/a\u003e\n\u003ca href=\"#fill\"\u003efill\u003c/a\u003e\n\u003ca href=\"#filter\"\u003efilter\u003c/a\u003e\n\u003ca href=\"#find\"\u003efind\u003c/a\u003e\n\u003ca href=\"#findkey\"\u003efindKey\u003c/a\u003e\n\u003ca href=\"#first\"\u003efirst\u003c/a\u003e\n\u003ca href=\"#firstkey\"\u003efirstKey\u003c/a\u003e\n\u003ca href=\"#flat\"\u003eflat\u003c/a\u003e\n\u003ca href=\"#flip\"\u003eflip\u003c/a\u003e\n\u003ca href=\"#float\"\u003efloat\u003c/a\u003e\n\u003ca href=\"#from\"\u003efrom\u003c/a\u003e\n\u003ca href=\"#fromjson\"\u003efromJson\u003c/a\u003e\n\u003ca href=\"#get\"\u003eget\u003c/a\u003e\n\u003ca href=\"#getiterator\"\u003egetIterator\u003c/a\u003e\n\u003ca href=\"#grep\"\u003egrep\u003c/a\u003e\n\u003ca href=\"#groupby\"\u003egroupBy\u003c/a\u003e\n\u003ca href=\"#has\"\u003ehas\u003c/a\u003e\n\u003ca href=\"#if\"\u003eif\u003c/a\u003e\n\u003ca href=\"#ifany\"\u003eifAny\u003c/a\u003e\n\u003ca href=\"#ifempty\"\u003eifEmpty\u003c/a\u003e\n\u003ca href=\"#implements\"\u003eimplements\u003c/a\u003e\n\u003ca href=\"#in\"\u003ein\u003c/a\u003e\n\u003ca href=\"#includes\"\u003eincludes\u003c/a\u003e\n\u003ca href=\"#index\"\u003eindex\u003c/a\u003e\n\u003ca href=\"#insertafter\"\u003einsertAfter\u003c/a\u003e\n\u003ca href=\"#insertat\"\u003einsertAt\u003c/a\u003e\n\u003ca href=\"#insertbefore\"\u003einsertBefore\u003c/a\u003e\n\u003ca href=\"#int\"\u003eint\u003c/a\u003e\n\u003ca href=\"#intersect\"\u003eintersect\u003c/a\u003e\n\u003ca href=\"#intersectassoc\"\u003eintersectAssoc\u003c/a\u003e\n\u003ca href=\"#intersectkeys\"\u003eintersectKeys\u003c/a\u003e\n\u003ca href=\"#is\"\u003eis\u003c/a\u003e\n\u003ca href=\"#isempty\"\u003eisEmpty\u003c/a\u003e\n\u003ca href=\"#islist\"\u003eisList\u003c/a\u003e\n\u003ca href=\"#isobject\"\u003eisObject\u003c/a\u003e\n\u003ca href=\"#isnumeric\"\u003eisNumeric\u003c/a\u003e\n\u003ca href=\"#isscalar\"\u003eisScalar\u003c/a\u003e\n\u003ca href=\"#isstring\"\u003eisString\u003c/a\u003e\n\u003ca href=\"#join\"\u003ejoin\u003c/a\u003e\n\u003ca href=\"#jsonserialize\"\u003ejsonSerialize\u003c/a\u003e\n\u003ca href=\"#keys\"\u003ekeys\u003c/a\u003e\n\u003ca href=\"#krsort\"\u003ekrsort\u003c/a\u003e\n\u003ca href=\"#krsorted\"\u003ekrsorted\u003c/a\u003e\n\u003ca href=\"#ksort\"\u003eksort\u003c/a\u003e\n\u003ca href=\"#ksorted\"\u003eksorted\u003c/a\u003e\n\u003ca href=\"#last\"\u003elast\u003c/a\u003e\n\u003ca href=\"#lastkey\"\u003elastKey\u003c/a\u003e\n\u003ca href=\"#ltrim\"\u003eltrim\u003c/a\u003e\n\u003ca href=\"#map\"\u003emap\u003c/a\u003e\n\u003ca href=\"#max\"\u003emax\u003c/a\u003e\n\u003ca href=\"#merge\"\u003emerge\u003c/a\u003e\n\u003ca href=\"#method\"\u003emethod\u003c/a\u003e\n\u003ca href=\"#min\"\u003emin\u003c/a\u003e\n\u003ca href=\"#none\"\u003enone\u003c/a\u003e\n\u003ca href=\"#nth\"\u003enth\u003c/a\u003e\n\u003ca href=\"#offsetexists\"\u003eoffsetExists\u003c/a\u003e\n\u003ca href=\"#offsetget\"\u003eoffsetGet\u003c/a\u003e\n\u003ca href=\"#offsetset\"\u003eoffsetSet\u003c/a\u003e\n\u003ca href=\"#offsetunset\"\u003eoffsetUnset\u003c/a\u003e\n\u003ca href=\"#only\"\u003eonly\u003c/a\u003e\n\u003ca href=\"#order\"\u003eorder\u003c/a\u003e\n\u003ca href=\"#pad\"\u003epad\u003c/a\u003e\n\u003ca href=\"#partition\"\u003epartition\u003c/a\u003e\n\u003ca href=\"#percentage\"\u003epercentage\u003c/a\u003e\n\u003ca href=\"#pipe\"\u003epipe\u003c/a\u003e\n\u003ca href=\"#pluck\"\u003epluck\u003c/a\u003e\n\u003ca href=\"#pop\"\u003epop\u003c/a\u003e\n\u003ca href=\"#pos\"\u003epos\u003c/a\u003e\n\u003ca href=\"#prefix\"\u003eprefix\u003c/a\u003e\n\u003ca href=\"#prepend\"\u003eprepend\u003c/a\u003e\n\u003ca href=\"#pull\"\u003epull\u003c/a\u003e\n\u003ca href=\"#push\"\u003epush\u003c/a\u003e\n\u003ca href=\"#put\"\u003eput\u003c/a\u003e\n\u003ca href=\"#random\"\u003erandom\u003c/a\u003e\n\u003ca href=\"#reduce\"\u003ereduce\u003c/a\u003e\n\u003ca href=\"#reject\"\u003ereject\u003c/a\u003e\n\u003ca href=\"#rekey\"\u003erekey\u003c/a\u003e\n\u003ca href=\"#remove\"\u003eremove\u003c/a\u003e\n\u003ca href=\"#replace\"\u003ereplace\u003c/a\u003e\n\u003ca href=\"#reverse\"\u003ereverse\u003c/a\u003e\n\u003ca href=\"#reversed\"\u003ereversed\u003c/a\u003e\n\u003ca href=\"#rsort\"\u003ersort\u003c/a\u003e\n\u003ca href=\"#rsorted\"\u003ersorted\u003c/a\u003e\n\u003ca href=\"#rtrim\"\u003ertrim\u003c/a\u003e\n\u003ca href=\"#search\"\u003esearch\u003c/a\u003e\n\u003ca href=\"#sep\"\u003esep\u003c/a\u003e\n\u003ca href=\"#set\"\u003eset\u003c/a\u003e\n\u003ca href=\"#shift\"\u003eshift\u003c/a\u003e\n\u003ca href=\"#shuffle\"\u003eshuffle\u003c/a\u003e\n\u003ca href=\"#shuffled\"\u003eshuffled\u003c/a\u003e\n\u003ca href=\"#skip\"\u003eskip\u003c/a\u003e\n\u003ca href=\"#slice\"\u003eslice\u003c/a\u003e\n\u003ca href=\"#some\"\u003esome\u003c/a\u003e\n\u003ca href=\"#sort\"\u003esort\u003c/a\u003e\n\u003ca href=\"#sorted\"\u003esorted\u003c/a\u003e\n\u003ca href=\"#splice\"\u003esplice\u003c/a\u003e\n\u003ca href=\"#strafter\"\u003estrAfter\u003c/a\u003e\n\u003ca href=\"#strbefore\"\u003estrBefore\u003c/a\u003e\n\u003ca href=\"#strcompare\"\u003estrCompare\u003c/a\u003e\n\u003ca href=\"#strcontains\"\u003estrContains\u003c/a\u003e\n\u003ca href=\"#strcontainsall\"\u003estrContainsAll\u003c/a\u003e\n\u003ca href=\"#strends\"\u003estrEnds\u003c/a\u003e\n\u003ca href=\"#strendsall\"\u003estrEndsAll\u003c/a\u003e\n\u003ca href=\"#string\"\u003estring\u003c/a\u003e\n\u003ca href=\"#strlower\"\u003estrLower\u003c/a\u003e\n\u003ca href=\"#strreplace\"\u003estrReplace\u003c/a\u003e\n\u003ca href=\"#strstarts\"\u003estrStarts\u003c/a\u003e\n\u003ca href=\"#strstartsall\"\u003estrStartsAll\u003c/a\u003e\n\u003ca href=\"#strupper\"\u003estrUpper\u003c/a\u003e\n\u003ca href=\"#suffix\"\u003esuffix\u003c/a\u003e\n\u003ca href=\"#sum\"\u003esum\u003c/a\u003e\n\u003ca href=\"#take\"\u003etake\u003c/a\u003e\n\u003ca href=\"#tap\"\u003etap\u003c/a\u003e\n\u003ca href=\"#times\"\u003etimes\u003c/a\u003e\n\u003ca href=\"#to\"\u003eto\u003c/a\u003e\n\u003ca href=\"#toarray\"\u003etoArray\u003c/a\u003e\n\u003ca href=\"#tojson\"\u003etoJson\u003c/a\u003e\n\u003ca href=\"#toreversed\"\u003etoReversed\u003c/a\u003e\n\u003ca href=\"#tosorted\"\u003etoSorted\u003c/a\u003e\n\u003ca href=\"#tourl\"\u003etoUrl\u003c/a\u003e\n\u003ca href=\"#transform\"\u003etransform\u003c/a\u003e\n\u003ca href=\"#transpose\"\u003etranspose\u003c/a\u003e\n\u003ca href=\"#traverse\"\u003etraverse\u003c/a\u003e\n\u003ca href=\"#tree\"\u003etree\u003c/a\u003e\n\u003ca href=\"#trim\"\u003etrim\u003c/a\u003e\n\u003ca href=\"#uasort\"\u003euasort\u003c/a\u003e\n\u003ca href=\"#uasorted\"\u003euasorted\u003c/a\u003e\n\u003ca href=\"#uksort\"\u003euksort\u003c/a\u003e\n\u003ca href=\"#uksorted\"\u003euksorted\u003c/a\u003e\n\u003ca href=\"#union\"\u003eunion\u003c/a\u003e\n\u003ca href=\"#unique\"\u003eunique\u003c/a\u003e\n\u003ca href=\"#unshift\"\u003eunshift\u003c/a\u003e\n\u003ca href=\"#usort\"\u003eusort\u003c/a\u003e\n\u003ca href=\"#usorted\"\u003eusorted\u003c/a\u003e\n\u003ca href=\"#values\"\u003evalues\u003c/a\u003e\n\u003ca href=\"#walk\"\u003ewalk\u003c/a\u003e\n\u003ca href=\"#where\"\u003ewhere\u003c/a\u003e\n\u003ca href=\"#with\"\u003ewith\u003c/a\u003e\n\u003ca href=\"#zip\"\u003ezip\u003c/a\u003e\n\n\u003c/nav\u003e\n\n### Create\n\n* [function map()](#map-function) : Creates a new map from passed elements\n* [__construct()](#__construct) : Creates a new map\n* [clone()](#clone) : Clones the map and all objects within\n* [copy()](#copy) : Creates a new copy\n* [explode()](#explode) : Splits a string into a map of elements\n* [fill()](#fill) : Creates a new map filled with given value\n* [from()](#from) : Creates a new map from passed elements\n* [fromJson()](#fromjson) : Creates a new map from a JSON string\n* [times()](#times) : Creates a new map by invoking the closure a number of times\n* [tree()](#tree) : Creates a tree structure from the list items\n\n### Access\n\n* [__call()](#__call) : Calls a custom method\n* [__callStatic()](#__callstatic) : Calls a custom method statically\n* [all()](#all) : Returns the plain array\n* [any()](#any) : Tests if at least one element satisfies the callback function\n* [at()](#at) : Returns the value at the given position\n* [bool()](#bool) : Returns an element by key and casts it to boolean\n* [call()](#call) : Calls the given method on all items\n* [find()](#find) : Returns the first/last element where the callback returns TRUE\n* [findKey()](#findkey) : Returns the first/last key where the callback returns TRUE\n* [first()](#first) : Returns the first element\n* [firstKey()](#firstkey) : Returns the first key\n* [get()](#get) : Returns an element by key\n* [index()](#index) : Returns the numerical index of the given key\n* [int()](#int) : Returns an element by key and casts it to integer\n* [float()](#float) : Returns an element by key and casts it to float\n* [keys()](#keys) : Returns all keys\n* [last()](#last) : Returns the last element\n* [lastKey()](#lastkey) : Returns the last key\n* [pop()](#pop) : Returns and removes the last element\n* [pos()](#pos) : Returns the numerical index of the value\n* [pull()](#pull) : Returns and removes an element by key\n* [random()](#random) : Returns random elements preserving keys\n* [search()](#search) : Find the key of an element\n* [shift()](#shift) : Returns and removes the first element\n* [string()](#string) : Returns an element by key and casts it to string\n* [to()](#to) : Returns the plain array\n* [toArray()](#toarray) : Returns the plain array\n* [values()](#values) : Returns all elements with new keys\n\n### Add\n\n* [concat()](#concat) : Adds all elements with new keys\n* [insertAfter()](#insertafter) : Inserts the value after the given element\n* [insertAt()](#insertat) : Inserts the element at the given position in the map\n* [insertBefore()](#insertbefore) : Inserts the value before the given element\n* [merge()](#merge) : Combines elements overwriting existing ones\n* [pad()](#pad) : Fill up to the specified length with the given value\n* [prepend()](#prepend) : Adds an element at the beginning (alias)\n* [push()](#push) : Adds an element to the end\n* [put()](#put) : Sets the given key and value in the map (alias)\n* [set()](#set) : Overwrites or adds an element\n* [union()](#union) : Adds the elements without overwriting existing ones\n* [unshift()](#unshift) : Adds an element at the beginning\n* [with()](#with) : Returns a copy and sets an element\n\n### Aggregate\n\n* [avg()](#avg) : Returns the average of all values\n* [count()](#count) : Returns the total number of elements\n* [countBy()](#countby) : Counts how often the same values are in the map\n* [max()](#max) : Returns the maximum value of all elements\n* [min()](#min) : Returns the minium value of all elements\n* [percentage()](#percentage) : Returns the percentage of all elements passing the test\n* [sum()](#sum) : Returns the sum of all values in the map\n\n### Debug\n\n* [dd()](#dd) : Prints the map content and terminates the script\n* [dump()](#dump) : Prints the map content\n* [tap()](#tap) : Passes a clone of the map to the given callback\n\n### Order By\n\n* [arsort()](#arsort) : Reverse sort elements preserving keys\n* [arsorted()](#arsorted) : Reverse sort elements preserving keys in a copy of the map\n* [asort()](#asort) : Sort elements preserving keys\n* [asorted()](#asorted) : Sort elements preserving keys in a copy of the map\n* [krsort()](#krsort) : Reverse sort elements by keys\n* [krsorted()](#krsorted) : Reverse sort elements by keys in a copy of the map\n* [ksort()](#ksort) : Sort elements by keys\n* [ksorted()](#ksorted) : Sorts a copy of the elements by their keys\n* [order()](#order) : Orders elements by the passed keys\n* [reverse()](#reverse) : Reverses the array order preserving keys\n* [reversed()](#reversed) : Reverses the element order in a copy of the map\n* [toReversed()](#toreversed) : Reverses the element order in a copy of the map (alias)\n* [rsort()](#rsort) : Reverse sort elements using new keys\n* [rsorted()](#rsorted) : Reverse sort elements using new keys in a copy of the map\n* [shuffle()](#shuffle) : Randomizes the element order\n* [shuffled()](#shuffled) : Randomizes the element order in a copy of the map\n* [sort()](#sort) : Sorts the elements in-place assigning new keys\n* [sorted()](#sorted) : Sorts the elements in a copy of the map using new keys\n* [toSorted()](#tosorted) : Sorts the elements in a copy of the map using new keys (alias)\n* [uasort()](#uasort) : Sorts elements preserving keys using callback\n* [uasorted()](#uasorted) : Sorts elements preserving keys using callback in a copy of the map\n* [uksort()](#uksort) : Sorts elements by keys using callback\n* [uksorted()](#uksorted) : Sorts elements by keys using callback in a copy of the map\n* [usort()](#usort) : Sorts elements using callback assigning new keys\n* [usorted()](#usorted) : Sorts elements using callback assigning new keys in a copy of the map\n\n### Shorten\n\n* [after()](#after) : Returns the elements after the given one\n* [before()](#before) : Returns the elements before the given one\n* [clear()](#clear) : Removes all elements\n* [diff()](#diff) : Returns the elements missing in the given list\n* [diffAssoc()](#diffassoc) : Returns the elements missing in the given list and checks keys\n* [diffKeys()](#diffkeys) : Returns the elements missing in the given list by keys\n* [duplicates()](#duplicates) : Returns the duplicate values from the map\n* [except()](#except) : Returns a new map without the passed element keys\n* [filter()](#filter) : Applies a filter to all elements\n* [grep()](#grep) : Applies a regular expression to all elements\n* [intersect()](#intersect) : Returns the elements shared\n* [intersectAssoc()](#intersectassoc) : Returns the elements shared and checks keys\n* [intersectKeys()](#intersectkeys) : Returns the elements shared by keys\n* [nth()](#nth) : Returns every nth element from the map\n* [only()](#only) : Returns only those elements specified by the keys\n* [pop()](#pop) : Returns and removes the last element\n* [pull()](#pull) : Returns and removes an element by key\n* [reject()](#reject) : Removes all matched elements\n* [remove()](#remove) : Removes an element by key\n* [shift()](#shift) : Returns and removes the first element\n* [skip()](#skip) : Skips the given number of items and return the rest\n* [slice()](#slice) : Returns a slice of the map\n* [take()](#take) : Returns a new map with the given number of items\n* [unique()](#unique) : Returns all unique elements preserving keys\n* [where()](#where) : Filters the list of elements by a given condition\n\n### Test\n\n* [function is_map()](#is_map-function) : Tests if the variable is a map object\n* [any()](#any) : Tests if at least one element satisfies the callback function\n* [contains()](#contains) : Tests if an item exists in the map\n* [each()](#each) : Applies a callback to each element\n* [empty()](#empty) : Tests if map is empty\n* [equals()](#equals) : Tests if map contents are equal\n* [every()](#every) : Verifies that all elements pass the test of the given callback\n* [has()](#has) : Tests if a key exists\n* [if()](#if) : Executes callbacks depending on the condition\n* [ifAny()](#ifany) : Executes callbacks if the map contains elements\n* [ifEmpty()](#ifempty) : Executes callbacks if the map is empty\n* [in()](#in) : Tests if element is included\n* [includes()](#includes) : Tests if element is included\n* [is()](#is) : Tests if the map consists of the same keys and values\n* [isEmpty()](#isempty) : Tests if map is empty\n* [isList()](#islist) : Checks if the map contains a list of subsequentially numbered keys\n* [isNumeric()](#isnumeric) : Tests if all entries are numeric values\n* [isObject()](#isobject) : Tests if all entries are objects\n* [isScalar()](#isscalar) : Tests if all entries are scalar values.\n* [isString()](#isstring) : Tests if all entries are string values.\n* [implements()](#implements) : Tests if all entries are objects implementing the interface\n* [none()](#none) : Tests if none of the elements are part of the map\n* [some()](#some) : Tests if at least one element is included\n* [strCompare()](#strcompare) : Compares the value against all map elements\n* [strContains()](#strcontains) : Tests if at least one of the passed strings is part of at least one entry\n* [strContainsAll()](#strcontainsall) : Tests if all of the entries contains one of the passed strings\n* [strEnds()](#strends) : Tests if at least one of the entries ends with one of the passed strings\n* [strEndsAll()](#strendsall) : Tests if all of the entries ends with at least one of the passed strings\n* [strStarts()](#strstarts) : Tests if at least one of the entries starts with at least one of the passed strings\n* [strStartsAll()](#strstartsall) : Tests if all of the entries starts with one of the passed strings\n\n### Mutate\n\n* [cast()](#cast) : Casts all entries to the passed type\n* [chunk()](#chunk) : Splits the map into chunks\n* [col()](#col) : Creates a key/value mapping\n* [collapse()](#collapse) : Collapses multi-dimensional elements overwriting elements\n* [combine()](#combine) : Combines the map elements as keys with the given values\n* [flat()](#flat) : Flattens multi-dimensional elements without overwriting elements\n* [flip()](#flip) : Exchanges keys with their values\n* [groupBy()](#groupby) : Groups associative array elements or objects\n* [join()](#join) : Returns concatenated elements as string with separator\n* [ltrim()](#ltrim) : Removes the passed characters from the left of all strings\n* [map()](#map) : Applies a callback to each element and returns the results\n* [partition()](#partition) : Breaks the list into the given number of groups\n* [pipe()](#pipe) : Applies a callback to the whole map\n* [pluck()](#pluck) : Creates a key/value mapping (alias)\n* [prefix()](#prefix) : Adds a prefix to each map entry\n* [reduce()](#reduce) : Computes a single value from the map content\n* [rekey()](#rekey) : Changes the keys according to the passed function\n* [replace()](#replace) : Replaces elements recursively\n* [rtrim()](#rtrim) : Removes the passed characters from the right of all strings\n* [splice()](#splice) : Replaces a slice by new elements\n* [strAfter()](#strafter) : Returns the strings after the passed value\n* [strBefore()](#strbefore) : Returns the strings before the passed value\n* [strLower()](#strlower) : Converts all alphabetic characters to lower case\n* [strReplace()](#strreplace) : Replaces all occurrences of the search string with the replacement string\n* [strUpper()](#strupper) : Converts all alphabetic characters to upper case\n* [suffix()](#suffix) : Adds a suffix to each map entry\n* [toJson()](#tojson) : Returns the elements in JSON format\n* [toUrl()](#tourl) : Creates a HTTP query string\n* [transform()](#transform) : Applies a callback to each element which creates new key/value pairs\n* [transpose()](#transpose) : Exchanges rows and columns for a two dimensional map\n* [traverse()](#traverse) : Traverses trees of nested items passing each item to the callback\n* [trim()](#trim) : Removes the passed characters from the left/right of all strings\n* [walk()](#walk) : Applies the given callback to all elements\n* [zip()](#zip) : Merges the values of all arrays at the corresponding index\n\n### Misc\n\n* [delimiter()](#delimiter) : Sets or returns the seperator for paths to multi-dimensional arrays\n* [getIterator()](#getiterator) : Returns an iterator for the elements\n* [jsonSerialize()](#jsonserialize) : Specifies the data which should be serialized to JSON\n* [method()](#method) : Registers a custom method\n* [offsetExists()](#offsetexists) : Checks if the key exists\n* [offsetGet()](#offsetget) : Returns an element by key\n* [offsetSet()](#offsetset) : Overwrites an element\n* [offsetUnset()](#offsetunset) : Removes an element by key\n* [sep()](#sep) : Sets the seperator for paths to multi-dimensional arrays in the current map\n\n\n\n## Method documentation\n\n### is_map() function\n\nTests if the variable is a map object\n\n```php\nfunction is_map( $var ) : bool\n```\n\n* @param **mixed** `$var` Variable to test\n\n**Examples:**\n\n```php\nis_map( new Map() );\n// true\n\nis_map( [] );\n// false\n```\n\n\n### map() function\n\nReturns a new map for the passed elements.\n\n```php\nfunction map( $elements = [] ) : \\Aimeos\\Map\n```\n\n* @param **mixed** `$elements` List of elements or single value\n* @return **\\Aimeos\\Map** Map instance\n\n**Examples:**\n\n```php\n// array\nmap( [] );\n\n// null\nmap( null );\n\n// scalar\nmap( 'a' );\n\n// object\nmap( new \\stdClass() );\n\n// map object\nmap( new Map() );\n\n// iterable object\nmap( new ArrayObject() );\n\n// closure evaluated lazily\nmap( function() {\n    return [];\n} );\n```\n\n**See also:**\n\n* [rekey()](#rekey) - Changes the keys according to the passed function\n* [transform()](#transform) - Creates new key/value pairs using the passed function and returns a new map for the result\n\n\n### __construct()\n\nCreates a new map object.\n\n```php\npublic function __construct( $elements = [] )\n```\n\n* @param **mixed** `$elements` Single element, list of elements, Map object, iterable objects or iterators, everything else\n\n**Examples:**\n\n```php\n// array\nnew Map( [] );\n\n// null\nnew Map( null );\n\n// scalar\nnew Map( 'a' );\n\n// object\nnew Map( new \\stdClass() );\n\n// map object\nnew Map( new Map() );\n\n// iterable object\nnew Map( new ArrayObject() );\n\n// closure evaluated lazily\nnew Map( function() {\n    return [];\n} );\n```\n\n\n### __call()\n\nHandles dynamic calls to custom methods for the class.\n\n```php\npublic function __call( string $name, array $params )\n```\n\n* @param **string** `$name` Method name\n* @param **array\u0026#60;mixed\u0026#62;** `$params` List of parameters\n* @return **mixed** Result from called function or new map with results from the element methods\n\nCalls a custom method added by [Map::method()](#method). The called method\nhas access to the internal array by using `$this-\u003eitems`.\n\n**Examples:**\n\n```php\nMap::method( 'case', function( $case = CASE_LOWER ) {\n    return new self( array_change_key_case( $this-\u003eitems, $case ) );\n} );\n\nMap::from( ['a' =\u003e 'bar'] )-\u003ecase( CASE_UPPER );\n// ['A' =\u003e 'bar']\n```\n\nThis does also allow calling object methods if the items are objects:\n\n```php\n$item = new MyClass(); // with method setStatus() (returning $this) and getCode() implemented\nMap::from( [$item, $item] )-\u003esetStatus( 1 )-\u003egetCode()-\u003etoArray();\n```\n\nThis will call the `setStatus()` method of each element in the map and\nuse their return values to create a new map. On the new map, the `getCode()`\nmethod is called for every element and its return values are also stored in a new\nmap. This last map is then returned and the map keys from the original map are\npreserved in the returned map.\n\nIf the elements are not objects, they are skipped and if this applies to all\nelements, an empty map is returned. In case the map contains objects of mixed\ntypes and one of them doesn't implement the called method, an error will be thrown.\n\n**See also:**\n\n* [__callStatic()](#__callStatic) - Handles static calls to custom methods for the class\n* [call()](#call) - Calls the given method on all items and returns the result\n\n\n### __callStatic()\n\nHandles static calls to custom methods for the class.\n\n```php\npublic static function __callStatic( string $name, array $params )\n```\n\n* @param **string** `$name` Method name\n* @param **array\u0026#60;mixed\u0026#62;** `$params` List of parameters\n* @return **mixed** Result from called function or new map with results from the element methods\n* @throws **\\BadMethodCallException** If no method has been registered for that name\n\nCalls a custom method added by [Map::method()](#method) statically. The called method\nhas no access to the internal array because no object is available.\n\n**Examples:**\n\n```php\nMap::method( 'foo', function( $arg1, $arg2 ) {} );\nMap::foo( $arg1, $arg2 );\n```\n\n**See also:**\n\n* [__call()](#__call) - Handles dynamic calls to custom methods for the class\n* [call()](#call) - Calls the given method on all items and returns the result\n\n\n### after()\n\nReturns the elements after the given one.\n\n```php\npublic function after( $value ) : self\n```\n\n* @param **\\Closure\u0026#124;int\u0026#124;string** `$value` Value or function with (item, key) parameters\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with the elements after the given one\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( [0 =\u003e 'b', 1 =\u003e 'a'] )-\u003eafter( 'b' );\n// [1 =\u003e 'a']\n\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003eafter( 1 );\n// ['b' =\u003e 0]\n\nMap::from( [0 =\u003e 'b', 1 =\u003e 'a'] )-\u003eafter( 'c' );\n// []\n\nMap::from( ['a', 'c', 'b'] )-\u003eafter( function( $item, $key ) {\n    return $item \u003e= 'c';\n} );\n// [2 =\u003e 'b']\n```\n\n**See also:**\n\n* [before()](#before) - Returns the elements before the given one\n\n\n### all()\n\nReturns the elements as a plain array.\n\n```php\npublic function all() : array\n```\n\n* @return **array** Plain array\n\n**Examples:**\n\n```php\nMap::from( ['a'] )-\u003eall();\n// ['a']\n```\n\nThis method is for compatibility to Laravel Collections. Use [`to()`](#to) instead if possible.\n\n**See also:**\n\n* [to()](#to) - Returns the elements as a plain array\n* [toArray()](#toarray) - Returns the elements as a plain array\n\n\n### any()\n\nTests if at least one element satisfies the callback function.\n\n```php\npublic function any( \\Closure $callback ) : bool\n```\n\n* @param \\Closure $callback Anonymous function with (item, key) parameter\n* @return bool TRUE if at least one element satisfies the callback function, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003eany( function( $item, $key ) {\n    return $item === 'a';\n} );\n// TRUE\n\nMap::from( ['a', 'b'] )-\u003eany( function( $item, $key ) {\n    return !is_string( $item );\n} );\n// FALSE\n```\n\n**See also:**\n\n* [some()](#some) - Tests if at least one element passes the test or is part of the map\n* [every()](#every) - Verifies that all elements pass the test of the given callback\n\n\n### arsort()\n\nSorts all elements in reverse order and maintains the key association.\n\n```php\npublic function arsort( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `arsort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe keys are preserved using this method and no new map is created.\n\nThe `$options` parameter modifies how the values are compared. Possible parameter values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\n**Examples:**\n\n```php\nMap::from( ['b' =\u003e 0, 'a' =\u003e 1] )-\u003earsort();\n// ['a' =\u003e 1, 'b' =\u003e 0]\n\nMap::from( ['a', 'b'] )-\u003earsort();\n// ['b', 'a']\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003earsort();\n// [1 =\u003e 'b', 0 =\u003e 'C']\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003earsort( SORT_STRING|SORT_FLAG_CASE );\n// [0 =\u003e 'C', 1 =\u003e 'b'] because 'C' -\u003e 'c' and 'c' \u003e 'b'\n```\n\n**See also:**\n\n* [arsorted()](#arsorted) - Sorts a copy of all elements in reverse order and maintains the key association\n\n\n### arsorted()\n\nSorts a copy of all elements in reverse order and maintains the key association.\n\n```php\npublic function arsorted( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `arsort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe keys are preserved using this method and a new map is created.\n\nThe `$options` parameter modifies how the values are compared. Possible parameter values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\n**Examples:**\n\n```php\nMap::from( ['b' =\u003e 0, 'a' =\u003e 1] )-\u003earsorted();\n// ['a' =\u003e 1, 'b' =\u003e 0]\n\nMap::from( ['a', 'b'] )-\u003earsorted();\n// ['b', 'a']\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003earsorted();\n// [1 =\u003e 'b', 0 =\u003e 'C']\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003earsorted( SORT_STRING|SORT_FLAG_CASE );\n// [0 =\u003e 'C', 1 =\u003e 'b'] because 'C' -\u003e 'c' and 'c' \u003e 'b'\n```\n\n**See also:**\n\n* [arsort()](#arsort) - Sorts all elements in reverse order and maintains the key association\n\n\n### asort()\n\nSorts all elements and maintains the key association.\n\n```php\npublic function asort( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `asort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe keys are preserved using this method and no new map is created.\n\nThe parameter modifies how the values are compared. Possible parameter values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003easort();\n// ['b' =\u003e 0, 'a' =\u003e 1]\n\nMap::from( [0 =\u003e 'b', 1 =\u003e 'a'] )-\u003easort();\n// [1 =\u003e 'a', 0 =\u003e 'b']\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003easort();\n// [0 =\u003e 'C', 1 =\u003e 'b'] because 'C' \u003c 'b'\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003easort( SORT_STRING|SORT_FLAG_CASE );\n// [1 =\u003e 'b', 0 =\u003e 'C'] because 'C' -\u003e 'c' and 'c' \u003e 'b'\n```\n\n**See also:**\n\n* [asorted()](#asorted) - Sorts a copy of all elements and maintains the key association\n\n\n### asorted()\n\nSorts a copy of all elements and maintains the key association.\n\n```php\npublic function asorted( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `asort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe keys are preserved using this method and a new map is created.\n\nThe parameter modifies how the values are compared. Possible parameter values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003easorted();\n// ['b' =\u003e 0, 'a' =\u003e 1]\n\nMap::from( [0 =\u003e 'b', 1 =\u003e 'a'] )-\u003easorted();\n// [1 =\u003e 'a', 0 =\u003e 'b']\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003easorted();\n// [0 =\u003e 'C', 1 =\u003e 'b'] because 'C' \u003c 'b'\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003easorted( SORT_STRING|SORT_FLAG_CASE );\n// [1 =\u003e 'b', 0 =\u003e 'C'] because 'C' -\u003e 'c' and 'c' \u003e 'b'\n```\n\n**See also:**\n\n* [asort()](#asort) - Sorts all elements and maintains the key association\n\n\n### at()\n\nReturns the value at the given position.\n\n```php\npublic function at( int $pos )\n```\n\n* @param **int** `$pos` Position of the value in the map\n* @return **mixed\u0026#134;null** Value at the given position or NULL if no value is available\n\nThe position starts from zero and a position of \"0\" returns the first element\nof the map, \"1\" the second and so on. If the position is negative, the sequence\nwill start from the end of the map.\n\n**Examples:**\n\n```php\nMap::from( [1, 3, 5] )-\u003eat( 0 );\n// 1\n\nMap::from( [1, 3, 5] )-\u003eat( 1 );\n// 3\n\nMap::from( [1, 3, 5] )-\u003eat( -1 );\n// 5\n\nMap::from( [1, 3, 5] )-\u003eat( 3 );\n// NULL\n```\n\n**See also:**\n\n* [index()](#index) - Returns the numerical index of the given key\n* [pos()](#pos) - Returns the numerical index of the value\n\n\n### avg()\n\nReturns the average of all integer and float values in the map.\n\n```php\npublic function avg( $col = null ) : float\n```\n\n* @param **Closure\u0026#124;string\u0026#124;null** `$col` Closure, key or path to the values in the nested array or object to compute the average for\n* @return **float** Average of all elements or 0 if there are no elements in the map\n\nNon-numeric values will be removed before calculation.\n\nThis does also work for multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. \"key1/key2/key3\"\nto get \"val\" from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\n**Examples:**\n\n```php\nMap::from( [1, 3, 5] )-\u003eavg();\n// 3\n\nMap::from( [1, null, 5] )-\u003eavg();\n// 3\n\nMap::from( [1, 'sum', 5] )-\u003eavg();\n// 2\n\nMap::from( [['p' =\u003e 30], ['p' =\u003e 50], ['p' =\u003e 10]] )-\u003eavg( 'p' );\n// 30\n\nMap::from( [['i' =\u003e ['p' =\u003e 30]], ['i' =\u003e ['p' =\u003e 50]]] )-\u003eavg( 'i/p' );\n// 40\n\nMap::from( [['i' =\u003e ['p' =\u003e 30]], ['i' =\u003e ['p' =\u003e 50]]] )-\u003eavg( fn( $val, $key ) =\u003e $val['i']['p'] ?? null );\n// 40\n\nMap::from( [['p' =\u003e 30], ['p' =\u003e 50], ['p' =\u003e 10]] )-\u003eavg( fn( $val, $key ) =\u003e $key \u003c 1 ? $val : null );\n// 30\n```\n\n**See also:**\n\n* [count()](#count) - Returns the total number of elements\n* [max()](#max) - Returns the maximum value of all elements\n* [min()](#min) - Returns the minium value of all elements\n* [percentage()](#percentage) - Returns the percentage of all elements passing the test\n* [sum()](#sum) - Returns the sum of all values in the map\n\n\n### before()\n\nReturns the elements before the given one.\n\n```php\npublic function before( $value ) : self\n```\n\n* @param **\\Closure\u0026#124;int\u0026#124;string** `$value` Value or function with (item, key) parameters\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with the elements before the given one\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003ebefore( 0 );\n// ['a' =\u003e 1]\n\nMap::from( [0 =\u003e 'b', 1 =\u003e 'a'] )-\u003ebefore( 'a' );\n// [0 =\u003e 'b']\n\nMap::from( [0 =\u003e 'b', 1 =\u003e 'a'] )-\u003ebefore( 'c' );\n// []\n\nMap::from( ['a', 'c', 'b'] )-\u003ebefore( function( $item, $key ) {\n    return $key \u003e= 1;\n} );\n// [0 =\u003e 'a']\n```\n\n**See also:**\n\n* [after()](#after) - Returns the elements after the given one\n\n\n### bool()\n\nReturns an element by key and casts it to boolean if possible.\n\n```php\npublic function bool( $key, $default = false ) : bool\n```\n\n* @param **int\u0026#124;string** `$key` Key or path to the requested item\n* @param **mixed** `$default` Default value if key isn't found (will be casted to bool)\n* @return **bool** Value from map or default value\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e true] )-\u003ebool( 'a' );\n// true\n\nMap::from( ['a' =\u003e '1'] )-\u003ebool( 'a' );\n// true (casted to boolean)\n\nMap::from( ['a' =\u003e 1.1] )-\u003ebool( 'a' );\n// true (casted to boolean)\n\nMap::from( ['a' =\u003e '10'] )-\u003ebool( 'a' );\n// true (casted to boolean)\n\nMap::from( ['a' =\u003e 'abc'] )-\u003ebool( 'a' );\n// true (casted to boolean)\n\nMap::from( ['a' =\u003e ['b' =\u003e ['c' =\u003e true]]] )-\u003ebool( 'a/b/c' );\n// true\n\nMap::from( [] )-\u003ebool( 'c', function() { return rand( 1, 2 ); } );\n// true (value returned by closure is casted to boolean)\n\nMap::from( [] )-\u003ebool( 'a', true );\n// true (default value used)\n\nMap::from( [] )-\u003ebool( 'a' );\n// false\n\nMap::from( ['b' =\u003e ''] )-\u003ebool( 'b' );\n// false (casted to boolean)\n\nMap::from( ['b' =\u003e null] )-\u003ebool( 'b' );\n// false (null is not scalar)\n\nMap::from( ['b' =\u003e [true]] )-\u003ebool( 'b' );\n// false (arrays are not scalar)\n\nMap::from( ['b' =\u003e '#resource'] )-\u003ebool( 'b' );\n// false (resources are not scalar)\n\nMap::from( ['b' =\u003e new \\stdClass] )-\u003ebool( 'b' );\n// false (objects are not scalar)\n\nMap::from( [] )-\u003ebool( 'c', new \\Exception( 'error' ) );\n// throws exception\n```\n\n**See also:**\n\n* [cast()](#cast) - Casts all entries to the passed type\n* [float()](#float) - Returns an element by key and casts it to float if possible\n* [get()](#get) - Returns an element from the map by key\n* [int()](#int) - Returns an element by key and casts it to integer if possible\n* [string()](#string) - Returns an element by key and casts it to string if possible\n\n\n### call()\n\nCalls the given method on all items and returns the result.\n\n```php\npublic function call( string $name, array $params = [] ) : self\n```\n\n* @param **string** `$name` Method name\n* @param **array\u0026#60;mixed\u0026#62;** `$params` List of parameters\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with results from all elements\n\nThis method can call methods on the map entries that are also implemented\nby the map object itself and are therefore not reachable when using the\nmagic `__call()` method. If some entries are not objects, they will be skipped.\n\nThe keys from the original map are preserved in the returned in the new map.\n\n**Examples:**\n\n```php\n$item = new MyClass( ['myprop' =\u003e 'val'] ); // implements methods get() and toArray()\n\nMap::from( [$item, $item] )-\u003ecall( 'get', ['myprop'] );\n// ['val', 'val']\n\nMap::from( [$item, $item] )-\u003ecall( 'toArray' );\n// [['myprop' =\u003e 'val'], ['myprop' =\u003e 'val']]\n```\n\n**See also:**\n\n* [__call()](#__call) - Handles dynamic calls to custom methods for the class\n* [__callStatic()](#__callStatic) - Handles static calls to custom methods for the class\n\n\n### cast()\n\nCasts all entries to the passed type.\n\n```php\npublic function cast( string $type = 'string' ) : self\n```\n\n* @param **string** `$type` Type to cast the values to (\"string\", \"bool\", \"int\", \"float\", \"array\", \"object\")\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map with casted elements\n\nCasting arrays and objects to scalar values won't return anything useful!\n\n**Examples:**\n\n```php\nMap::from( [true, 1, 1.0, 'yes'] )-\u003ecast();\n// ['1', '1', '1.0', 'yes']\n\nMap::from( [true, 1, 1.0, 'yes'] )-\u003ecast( 'bool' );\n// [true, true, true, true]\n\nMap::from( [true, 1, 1.0, 'yes'] )-\u003ecast( 'int' );\n// [1, 1, 1, 0]\n\nMap::from( [true, 1, 1.0, 'yes'] )-\u003ecast( 'float' );\n// [1.0, 1.0, 1.0, 0.0]\n\nMap::from( [new stdClass, new stdClass] )-\u003ecast( 'array' );\n// [[], []]\n\nMap::from( [[], []] )-\u003ecast( 'object' );\n// [new stdClass, new stdClass]\n```\n\n**See also:**\n\n* [bool()](#bool) - Returns an element by key and casts it to boolean if possible\n* [int()](#int) - Returns an element by key and casts it to integer if possible\n* [float()](#float) - Returns an element by key and casts it to float if possible\n* [string()](#string) - Returns an element by key and casts it to string if possible\n\n\n### chunk()\n\nChunks the map into arrays with the given number of elements.\n\n```php\npublic function chunk( int $size, bool $preserve = false ) : self\n```\n\n* @param **int** `$size` Maximum size of the sub-arrays\n* @param **bool** `$preserve` Preserve keys in new map\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with elements chunked in sub-arrays\n* @throws **\\InvalidArgumentException** If size is smaller than 1\n\nThe last chunk may contain less elements than the given number.\n\nThe sub-arrays of the returned map are plain PHP arrays. If you need Map\nobjects, then wrap them with [Map::from()](#from) when you iterate over the map.\n\n**Examples:**\n\n```php\nMap::from( [0, 1, 2, 3, 4] )-\u003echunk( 3 );\n// [[0, 1, 2], [3, 4]]\n\nMap::from( ['a' =\u003e 0, 'b' =\u003e 1, 'c' =\u003e 2] )-\u003echunk( 2 );\n// [['a' =\u003e 0, 'b' =\u003e 1], ['c' =\u003e 2]]\n```\n\n**See also:**\n\n* [partition()](#partition) - Breaks the list into the given number of groups\n\n\n### clear()\n\nRemoves all elements from the current map.\n\n```php\npublic function clear() : self\n```\n\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( [0, 1] )-\u003eclear();\n// internal : []\n```\n\n**See also:**\n\n* [except()](#except) - Returns a new map without the passed element keys\n* [only()](#only) - Returns only those elements specified by the keys\n* [reject()](#reject) - Removes all matched elements\n* [remove()](#remove) - Removes an element by key\n\n\n### clone()\n\nClones the map and all objects within.\n\n```php\npublic function clone() : self\n```\n\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with cloned objects\n\nThe objects within the Map are NOT the same as before but new cloned objects.\nThis is different to [`copy()`](#copy), which doesn't clone the objects within.\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( [new \\stdClass, new \\stdClass] )-\u003eclone();\n// [new \\stdClass, new \\stdClass]\n```\n\n**See also:**\n\n* [copy()](#copy) - Creates a new copy\n\n\n### col()\n\nReturns the values of a single column/property from an array of arrays or list of elements in a new map.\n\n```php\npublic function col( string $valuecol = null, string $indexcol = null ) : self\n```\n\n* @param **string\u0026#124;null** `$valuecol` Name or path of the value property\n* @param **string\u0026#124;null** `$indexcol` Name or path of the index property\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with mapped entries\n\nIf $indexcol is omitted, it's value is NULL or not set, the result will be indexed from 0-n.\nItems with the same value for $indexcol will overwrite previous items and only the last one\nwill be part of the resulting map.\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\n**Examples:**\n\n```php\nMap::from( [['id' =\u003e 'i1', 'val' =\u003e 'v1'], ['id' =\u003e 'i2', 'val' =\u003e 'v2']] )-\u003ecol( 'val' );\n// ['v1', 'v2']\n\nMap::from( [['id' =\u003e 'i1', 'val' =\u003e 'v1'], ['id' =\u003e 'i2', 'val' =\u003e 'v2']] )-\u003ecol( 'val', 'id' );\n// ['i1' =\u003e 'v1', 'i2' =\u003e 'v2']\n\nMap::from( [['id' =\u003e 'i1', 'val' =\u003e 'v1'], ['id' =\u003e 'i2', 'val' =\u003e 'v2']] )-\u003ecol( null, 'id' );\n// ['i1' =\u003e ['id' =\u003e 'i1', 'val' =\u003e 'v1'], 'i2' =\u003e ['id' =\u003e 'i2', 'val' =\u003e 'v2']]\n\nMap::from( [['id' =\u003e 'ix', 'val' =\u003e 'v1'], ['id' =\u003e 'ix', 'val' =\u003e 'v2']] )-\u003ecol( null, 'id' );\n// ['ix' =\u003e ['id' =\u003e 'ix', 'val' =\u003e 'v2']]\n\nMap::from( [['foo' =\u003e ['bar' =\u003e 'one', 'baz' =\u003e 'two']]] )-\u003ecol( 'foo/baz', 'foo/bar' );\n// ['one' =\u003e 'two']\n\nMap::from( [['foo' =\u003e ['bar' =\u003e 'one']]] )-\u003ecol( 'foo/baz', 'foo/bar' );\n// ['one' =\u003e null]\n\nMap::from( [['foo' =\u003e ['baz' =\u003e 'two']]] )-\u003ecol( 'foo/baz', 'foo/bar' );\n// ['two']\n```\n\n**See also:**\n\n* [map()](#map) - Applies a callback to each element and returns the results\n* [pluck()](#pluck) - Creates a key/value mapping (alias)\n* [rekey()](#pluck) - Changes the keys according to the passed function\n\n\n### collapse()\n\nCollapses all sub-array elements recursively to a new map.\n\n```php\npublic function collapse( int $depth = null ) : self\n```\n\n* @param **int\u0026#124;null** `$depth` Number of levels to collapse for multi-dimensional arrays or NULL for all\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with all sub-array elements added into it recursively, up to the specified depth\n\nThe keys are preserved and already existing elements will be overwritten. This\nis also true for numeric keys! This method is similar than [flat()](#flat) but replaces\nalready existing elements.\n\nA value smaller than 1 for depth will return the same map elements. Collapsing\ndoes also work if elements implement the \"Traversable\" interface (which the Map\nobject does).\n\n**Examples:**\n\n```php\nMap::from( [0 =\u003e ['a' =\u003e 0, 'b' =\u003e 1], 1 =\u003e ['c' =\u003e 2, 'd' =\u003e 3]] )-\u003ecollapse();\n// ['a' =\u003e 0, 'b' =\u003e 1, 'c' =\u003e 2, 'd' =\u003e 3]\n\nMap::from( [0 =\u003e ['a' =\u003e 0, 'b' =\u003e 1], 1 =\u003e ['a' =\u003e 2]] )-\u003ecollapse();\n// ['a' =\u003e 2, 'b' =\u003e 1]\n\nMap::from( [0 =\u003e [0 =\u003e 0, 1 =\u003e 1], 1 =\u003e [0 =\u003e ['a' =\u003e 2, 0 =\u003e 3], 1 =\u003e 4]] )-\u003ecollapse();\n// [0 =\u003e 3, 1 =\u003e 4, 'a' =\u003e 2]\n\nMap::from( [0 =\u003e [0 =\u003e 0, 'a' =\u003e 1], 1 =\u003e [0 =\u003e ['b' =\u003e 2, 0 =\u003e 3], 1 =\u003e 4]] )-\u003ecollapse( 1 );\n// [0 =\u003e ['b' =\u003e 2, 0 =\u003e 3], 1 =\u003e 4, 'a' =\u003e 1]\n\nMap::from( [0 =\u003e [0 =\u003e 0, 'a' =\u003e 1], 1 =\u003e Map::from( [0 =\u003e ['b' =\u003e 2, 0 =\u003e 3], 1 =\u003e 4] )] )-\u003ecollapse();\n// [0 =\u003e 3, 'a' =\u003e 1, 'b' =\u003e 2, 1 =\u003e 4]\n```\n\n**See also:**\n\n* [flat()](#flat) - Flattens multi-dimensional elements without overwriting elements\n\n\n### combine()\n\nCombines the values of the map as keys with the passed elements as values.\n\n```php\npublic function combine( iterable $values ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$values` Values of the new map\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\n**Examples:**\n\n```php\nMap::from( ['name', 'age'] )-\u003ecombine( ['Tom', 29] );\n// ['name' =\u003e 'Tom', 'age' =\u003e 29]\n```\n\n**See also:**\n\n* [zip()](#zip) - Merges the values of all arrays at the corresponding index\n\n\n### concat()\n\nPushs all of the given elements onto the map without creating a new map.\n\n```php\npublic function concat( iterable $elements ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe keys of the passed elements are NOT preserved!\n\n**Examples:**\n\n```php\nMap::from( ['foo'] )-\u003econcat( ['bar'] );\n// ['foo', 'bar']\n\nMap::from( ['foo'] )-\u003econcat( new Map( ['bar' =\u003e 'baz'] ) );\n// ['foo', 'baz']\n```\n\n**See also:**\n\n* [merge()](#merge) - Merges the map with the given elements without returning a new map\n* [union()](#union) - Builds a union of the elements and the given elements without returning a new map\n\n\n### contains()\n\nDetermines if an item exists in the map.\n\n```php\npublic function contains( $key, string $operator = null, $value = null ) : bool\n```\n\nThis method combines the power of the `where()` method with `some()` to check\nif the map contains at least one of the passed values or conditions.\n\n* @param **\\Closure\u0026#124;iterable\u0026#124;mixed** `$values` Anonymous function with (item, key) parameter, element or list of elements to test against\n* @param **string\u0026#124;null** `$op` Operator used for comparison\n* @param **mixed** `$value` Value used for comparison\n* @return **bool** TRUE if at least one element is available in map, FALSE if the map contains none of them\n\nCheck the [`where()`](#where)] method for available operators.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003econtains( 'a' );\n// true\n\nMap::from( ['a', 'b'] )-\u003econtains( ['a', 'c'] );\n// true\n\nMap::from( ['a', 'b'] )-\u003econtains( function( $item, $key ) {\n    return $item === 'a'\n} );\n// true\n\nMap::from( [['type' =\u003e 'name']] )-\u003econtains( 'type', 'name' );\n// true\n\nMap::from( [['type' =\u003e 'name']] )-\u003econtains( 'type', '!=', 'name' );\n// false\n```\n\n**See also:**\n\n* [in()](#in) - Tests if element is included\n* [includes()](#includes) - Tests if element is included\n* [where()](#where) - Filters the list of elements by a given condition\n\n\n### copy()\n\nCreates a new map with the same elements.\n\n```php\npublic function copy() : self\n```\n\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nBoth maps share the same array until one of the map objects modifies the\narray. Then, the array is copied and the copy is modfied (copy on write).\n\n**Examples:**\n\n```php\n$m = Map::from( ['foo', 'bar'] );\n\n$m2 = $m-\u003ecopy();\n// internal: ['foo', 'bar'] both two maps\n```\n\n**See also:**\n\n* [clone()](#clone) - Clones the map and all objects within\n\n\n### count()\n\nCounts the number of elements in the map.\n\n```php\npublic function count() : int\n```\n\n* @return **int** Number of elements\n\n**Examples:**\n\n```php\nMap::from( ['foo', 'bar'] )-\u003ecount();\n// 2\n```\n\n**See also:**\n\n* [avg()](#avg) - Returns the average of all integer and float values in the map\n* [countBy()](#countby) - Counts how often the same values are in the map\n* [max()](#max) - Returns the maximum value of all elements\n* [min()](#min) - Returns the minium value of all elements\n* [percentage()](#percentage) - Returns the percentage of all elements passing the test\n* [sum()](#sum) - Returns the sum of all values in the map\n\n\n### countBy()\n\nCounts how often the same values are in the map.\n\n```php\npublic function countBy( $col = null ) : self\n```\n\n* @param **\\Closure\u0026#124;string\u0026#124;null** `$col` Key as \"key1/key2/key3\" or closure with (value, key) parameters returning the values for counting\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with values as keys and their count as value\n\nThis does also work for multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. \"key1/key2/key3\"\nto get \"val\" from ['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]. The same applies to\npublic properties of objects or objects implementing __isset() and __get() methods.\n\n**Examples:**\n\n```php\nMap::from( [1, 'foo', 2, 'foo', 1] )-\u003ecountBy();\n// [1 =\u003e 2, 'foo' =\u003e 2, 2 =\u003e 1]\n\nMap::from( [1.11, 3.33, 3.33, 9.99] )-\u003ecountBy();\n// ['1.11' =\u003e 1, '3.33' =\u003e 2, '9.99' =\u003e 1]\n\nMap::from( [['i' =\u003e ['p' =\u003e 1.11]], ['i' =\u003e ['p' =\u003e 3.33]], ['i' =\u003e ['p' =\u003e 3.33]]] )-\u003ecountBy( 'i/p' );\n// ['1.11' =\u003e 1, '3.33' =\u003e 2]\n\nMap::from( ['a@gmail.com', 'b@yahoo.com', 'c@gmail.com'] )-\u003ecountBy( function( $email ) {\n    return substr( strrchr( $email, '@' ), 1 );\n} );\n// ['gmail.com' =\u003e 2, 'yahoo.com' =\u003e 1]\n```\n\n**See also:**\n\n* [avg()](#avg) - Returns the average of all integer and float values in the map\n* [groupBy()](#groupby) - Groups associative array elements or objects by the passed key or closure\n* [max()](#max) - Returns the maximum value of all elements\n* [min()](#min) - Returns the minium value of all elements\n* [percentage()](#percentage) - Returns the percentage of all elements passing the test\n* [sum()](#sum) - Returns the sum of all values in the map\n\n\n### dd()\n\nDumps the map content and terminates the script.\n\n```php\npublic function dd( callable $callback = null ) : void\n```\n\n* @param **callable\u0026#124;null** `$callback` Function receiving the map elements as parameter (optional)\n\nThe `dd()` method is very helpful to see what are the map elements passed\nbetween two map methods in a method call chain. It stops execution of the\nscript afterwards to avoid further output.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003esort()-\u003edd()-\u003efirst();\n/*\nArray\n(\n    [0] =\u003e bar\n    [1] =\u003e foo\n)\n*/\n```\n\nThe `first()` method isn't executed at all.\n\n\n### delimiter()\n\nSets or returns the seperator for paths to values in multi-dimensional arrays or objects.\n\n```php\npublic static function delimiter( ?string $char = null ) : string\n```\n\n* @param **string** `$char` Separator character, e.g. \".\" for \"key.to.value\" instaed of \"key/to/value\"\n* @return **string** Separator used up to now\n\nThe static method only changes the separator for new maps created afterwards.\nAlready existing maps will continue to use the previous separator. To change\nthe separator of an existing map, use the [sep()](#sep) method instead.\n\n**Examples:**\n\n```php\nMap::delimiter( '.' );\n// '/'\n\nMap::from( ['foo' =\u003e ['bar' =\u003e 'baz']] )-\u003eget( 'foo.bar' );\n// 'baz'\n```\n\n**See also:**\n\n* [sep()](#sep) - Sets the seperator for paths to values in multi-dimensional arrays or objects\n\n\n### diff()\n\nReturns the keys/values in the map whose values are not present in the passed elements in a new map.\n\n```php\npublic function diff( iterable $elements, callable $callback = null ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements\n* @param **callable\u0026#124;null** `$callback` Function with (valueA, valueB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003ediff( ['bar'] );\n// ['a' =\u003e 'foo']\n```\n\nIf a callback is passed, the given function will be used to compare the values.\nThe function must accept two parameters (value A and B) and must return\n-1 if value A is smaller than value B, 0 if both are equal and 1 if value A is\ngreater than value B. Both, a method name and an anonymous function can be passed:\n\n```php\nMap::from( [0 =\u003e 'a'] )-\u003ediff( [0 =\u003e 'A'], 'strcasecmp' );\n// []\n\nMap::from( ['b' =\u003e 'a'] )-\u003ediff( ['B' =\u003e 'A'], 'strcasecmp' );\n// []\n\nMap::from( ['b' =\u003e 'a'] )-\u003ediff( ['c' =\u003e 'A'], function( $valA, $valB ) {\n    return strtolower( $valA ) \u003c=\u003e strtolower( $valB );\n} );\n// []\n```\n\nAll examples will return an empty map because both contain the same values\nwhen compared case insensitive.\n\nThe keys are preserved using this method.\n\n**See also:**\n\n* [diffAssoc()](#diffassoc) - Returns the keys/values in the map whose keys AND values are not present in the passed elements in a new map\n* [diffKeys()](#diffkeys) - Returns the elements missing in the given list by keys\n\n\n### diffAssoc()\n\nReturns the keys/values in the map whose keys AND values are not present in the passed elements in a new map.\n\n```php\npublic function diffAssoc( iterable $elements, callable $callback = null ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements\n* @param **callable\u0026#124;null** `$callback` Function with (valueA, valueB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003ediffAssoc( new Map( ['foo', 'b' =\u003e 'bar'] ) );\n// ['a' =\u003e 'foo']\n```\n\nIf a callback is passed, the given function will be used to compare the values.\nThe function must accept two parameters (valA, valB) and must return\n-1 if value A is smaller than value B, 0 if both are equal and 1 if value A is\ngreater than value B. Both, a method name and an anonymous function can be passed:\n\n```php\nMap::from( [0 =\u003e 'a'] )-\u003ediffAssoc( [0 =\u003e 'A'], 'strcasecmp' );\n// []\n\nMap::from( ['b' =\u003e 'a'] )-\u003ediffAssoc( ['B' =\u003e 'A'], 'strcasecmp' );\n// []\n\nMap::from( ['b' =\u003e 'a'] )-\u003ediffAssoc( ['c' =\u003e 'A'], function( $valA, $valB ) {\n    return strtolower( $valA ) \u003c=\u003e strtolower( $valB );\n} );\n// ['b' =\u003e 'a']\n```\n\nThe first and second example will return an empty map because both contain the\nsame values when compared case insensitive. In the third example, the keys doesn't\nmatch (\"b\" vs. \"c\").\n\nThe keys are preserved using this method.\n\n**See also:**\n\n* [diff()](#diff) - Returns the keys/values in the map whose values are not present in the passed elements in a new map\na new map\n* [diffKeys()](#diffkeys) - Returns the elements missing in the given list by keys\n\n\n### diffKeys()\n\nReturns the key/value pairs from the map whose keys are not present in the passed elements in a new map.\n\n```php\npublic function diffKeys( iterable $elements, callable $callback = null ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements\n* @param **callable\u0026#124;null** `$callback` Function with (keyA, keyB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003ediffKeys( new Map( ['foo', 'b' =\u003e 'baz'] ) );\n// ['a' =\u003e 'foo']\n```\n\nIf a callback is passed, the given function will be used to compare the keys.\nThe function must accept two parameters (key A and B) and must return\n-1 if key A is smaller than key B, 0 if both are equal and 1 if key A is\ngreater than key B. Both, a method name and an anonymous function can be passed:\n\n```php\nMap::from( [0 =\u003e 'a'] )-\u003ediffKeys( [0 =\u003e 'A'], 'strcasecmp' );\n// []\n\nMap::from( ['b' =\u003e 'a'] )-\u003ediffKeys( ['B' =\u003e 'X'], 'strcasecmp' );\n// []\n\nMap::from( ['b' =\u003e 'a'] )-\u003ediffKeys( ['c' =\u003e 'a'], function( $keyA, $keyB ) {\n    return strtolower( $keyA ) \u003c=\u003e strtolower( $keyB );\n} );\n// ['b' =\u003e 'a']\n```\n\nThe first and second example will return an empty map because both contain\nthe same keys when compared case insensitive. The third example will return\n['b' =\u003e 'a'] because the keys doesn't match (\"b\" vs. \"c\").\n\nThe keys are preserved using this method.\n\n**See also:**\n\n* [diff()](#diff) - Returns the keys/values in the map whose values are not present in the passed elements in a new map\n* [diffAssoc()](#diffassoc) - Returns the keys/values in the map whose keys AND values are not present in the passed elements in a new map\n\n\n### dump()\n\nDumps the map content using the given function (print_r by default).\n\n```php\npublic function dump( callable $callback = null ) : self\n```\n\n* @param **callable\u0026#124;null** `$callback` Function receiving the map elements as parameter (optional)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Same map for fluid interface\n\nThe `dump()` method is very helpful to see what are the map elements passed\nbetween two map methods in a method call chain.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003edump()-\u003easort()-\u003edump( 'var_dump' );\n/*\nArray\n(\n    [a] =\u003e foo\n    [b] =\u003e bar\n)\n\narray(1) {\n  [\"b\"]=\u003e\n  string(3) \"bar\"\n  [\"a\"]=\u003e\n  string(3) \"foo\"\n}\n*/\n```\n\n\n### duplicates()\n\nReturns the duplicate values from the map.\n\n```php\npublic function duplicates( $col = null ) : self\n```\n\n* @param **\\Closure\u0026#124;string\u0026#124;null** `$col` Key, path of the nested array or anonymous function with ($item, $key) parameters returning the value for comparison\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nFor nested arrays, you have to pass the name of the column of the nested array which\nshould be used to check for duplicates.\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\nThe keys in the result map are preserved.\n\n**Examples:**\n\n```php\nMap::from( [1, 2, '1', 3] )-\u003eduplicates()\n// [2 =\u003e '1']\n\nMap::from( [['p' =\u003e '1'], ['p' =\u003e 1], ['p' =\u003e 2]] )-\u003eduplicates( 'p' )\n// [1 =\u003e ['p' =\u003e 1]]\n\nMap::from( [['i' =\u003e ['p' =\u003e '1']], ['i' =\u003e ['p' =\u003e 1]]] )-\u003eduplicates( 'i/p' )\n// [1 =\u003e ['i' =\u003e ['p' =\u003e 1]]]\n\nMap::from( [['i' =\u003e ['p' =\u003e '1']], ['i' =\u003e ['p' =\u003e 1]]] )-\u003eunique( fn( $item, $key ) =\u003e $item['i']['p'] );\n// [1 =\u003e ['i' =\u003e ['p' =\u003e 1]]]\n```\n\n**See also:**\n\n* [reject()](#reject) - Removes all matched elements\n* [unique()](#unique) - Returns only unique elements from the map in a new map\n\n\n### each()\n\nExecutes a callback over each entry until FALSE is returned.\n\n```php\npublic function each( \\Closure $callback ) : self\n```\n\n* @param **\\Closure** `$callback` Function with (value, key) parameters and returns TRUE/FALSE\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Same map for fluid interface\n\n**Examples:**\n\n```php\n$result = [];\nMap::from( [0 =\u003e 'a', 1 =\u003e 'b'] )-\u003eeach( function( $value, $key ) use ( \u0026$result ) {\n    $result[$key] = strtoupper( $value );\n    return false;\n} );\n// $result = [0 =\u003e 'A']\n```\n\nThe `$result` array will contain `[0 =\u003e 'A']` because FALSE is returned\nafter the first entry and all other entries are then skipped.\n\n\n### empty()\n\nDetermines if the map is empty or not.\n\n```php\npublic function empty() : bool\n```\n\n* @return **bool** TRUE if map is empty, FALSE if not\n\nThe method is equivalent to isEmpty().\n\n**Examples:**\n\n```php\nMap::from( [] )-\u003eempty();\n// true\n\nMap::from( ['a'] )-\u003eempty();\n// false\n```\n\n**See also:**\n\n* [isEmpty()](#isempty) - Determines if the map is empty or not\n\n\n### equals()\n\nTests if the passed elements are equal to the elements in the map.\n\n```php\npublic function equals( iterable $elements ) : bool\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements to test against\n* @return **bool** TRUE if both are equal, FALSE if not\n\nThe method differs to [is()](#is) in the fact that it doesn't care about the keys\nby default. The elements are only loosely compared and the keys are ignored.\n\nValues are compared by their string values:\n```php\n(string) $item1 === (string) $item2\n```\n\n**Examples:**\n\n```php\nMap::from( ['a'] )-\u003eequals( ['a', 'b'] );\n// false\n\nMap::from( ['a', 'b'] )-\u003eequals( ['b'] );\n// false\n\nMap::from( ['a', 'b'] )-\u003eequals( ['b', 'a'] );\n// true\n```\n\n**See also:**\n\n* [is()](#is) - Tests if the map consists of the same keys and values\n\n\n### every()\n\nVerifies that all elements pass the test of the given callback.\n\n```php\npublic function every( \\Closure $callback ) : bool\n```\n\n* @param **\\Closure** `$callback` Function with (value, key) parameters and returns TRUE/FALSE\n* @return **bool** True if all elements pass the test, false if if fails for at least one element\n\n**Examples:**\n\n```php\nMap::from( [0 =\u003e 'a', 1 =\u003e 'b'] )-\u003eevery( function( $value, $key ) {\n    return is_string( $value );\n} );\n// true\n\nMap::from( [0 =\u003e 'a', 1 =\u003e 100] )-\u003eevery( function( $value, $key ) {\n    return is_string( $value );\n} );\n// false\n```\n\n**See also:**\n\n* [some()](#some) - Tests if at least one element passes the test or is part of the map\n* [any()](#any) - Tests if at least one element satisfies the callback function\n\n\n### except()\n\nReturns a new map without the passed element keys.\n\n```php\npublic function except( $keys ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string\u0026#62;\u0026#124;array\u0026#60;int\u0026#124;string\u0026#62;\u0026#124;string\u0026#124;int** `$keys` List of keys to remove\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe keys in the result map are preserved.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 2, 'c' =\u003e 3] )-\u003eexcept( 'b' );\n// ['a' =\u003e 1, 'c' =\u003e 3]\n\nMap::from( [1 =\u003e 'a', 2 =\u003e 'b', 3 =\u003e 'c'] )-\u003eexcept( [1, 3] );\n// [2 =\u003e 'b']\n```\n\n**See also:**\n\n* [clear()](#clear) - Removes all elements from the current map\n* [only()](#only) - Returns only those elements specified by the keys\n* [reject()](#reject) - Removes all matched elements\n* [remove()](#remove) - Removes an element by key\n\n\n### explode()\n\nCreates a new map with the string splitted by the delimiter.\n\n```php\npublic static function explode( string $delimiter , string $string , int $limit = PHP_INT_MAX ) : self\n```\n\n* @param **string** `$delimiter` Delimiter character, string or empty string\n* @param **string** `$string` String to split\n* @param **int** `$limit` Maximum number of element with the last element containing the rest of the string\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with splitted parts\n\nA limit of \"0\" is treated the same as \"1\". If limit is negative, the rest of\nthe string is dropped and not part of the returned map.\n\nThis method creates a lazy Map and the string is split after calling\nanother method that operates on the Map contents.\n\n**Examples:**\n\n```php\nMap::explode( ',', 'a,b,c' );\n// ['a', 'b', 'c']\n\nMap::explode( '\u003c--\u003e', 'a a\u003c--\u003eb b\u003c--\u003ec c' );\n// ['a a', 'b b', 'c c']\n\nMap::explode( '', 'string' );\n// ['s', 't', 'r', 'i', 'n', 'g']\n\nMap::explode( '|', 'a|b|c', 2 );\n// ['a', 'b|c']\n\nMap::explode( '', 'string', 2 );\n// ['s', 't', 'ring']\n\nMap::explode( '|', 'a|b|c|d', -2 );\n// ['a', 'b']\n\nMap::explode( '', 'string', -3 );\n// ['s', 't', 'r']\n```\n\n\n### fill()\n\nCreates a new map filled with given value.\n\n```php\npublic static function fill( int $num, $value, int $start = 0 ) : self\n```\n\n* @param **int** `$num` Number of elements to create\n* @param **mixed** `$value` Value to fill the map with\n* @param **int** `$start` Start index for the elements\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with filled elements\n\n**Examples:**\n\n```php\nMap::fill( 3, 'a' );\n// [0 =\u003e 'a', 1 =\u003e 'a', 2 =\u003e 'a']\n\nMap::fill( 3, 'a', 2 );\n// [2 =\u003e 'a', 3 =\u003e 'a', 4 =\u003e 'a']\n\nMap::fill( 3, 'a', -2 );\n// [-2 =\u003e 'a', -1 =\u003e 'a', 0 =\u003e 'a'] (PHP 8)\n// [-2 =\u003e 'a', 0 =\u003e 'a', 1 =\u003e 'a'] (PHP 7)\n```\n\n\n### filter()\n\nRuns a filter over each element of the map and returns a new map.\n\n```php\npublic function filter( callable $callback = null ) : self\n```\n\n* @param **callable\u0026#124;null** `$callback` Function with (item, key) parameters and returns TRUE/FALSE\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nIf no callback is passed, all values which are empty, null or false will be\nremoved if their value converted to boolean is FALSE:\n```php\n(bool) $value === false\n```\n\nThe keys in the result map are preserved.\n\n**Examples:**\n\n```php\nMap::from( [null, 0, 1, '', '0', 'a'] )-\u003efilter();\n// [1, 'a']\n\nMap::from( [2 =\u003e 'a', 6 =\u003e 'b', 13 =\u003e 'm', 30 =\u003e 'z'] )-\u003efilter( function( $value, $key ) {\n    return $key \u003c 10 \u0026\u0026 $value \u003c 'n';\n} );\n// ['a', 'b']\n```\n\n**See also:**\n\n* [grep()](#grep) - Applies a regular expression to all elements\n* [where()](#where) - Filters the list of elements by a given condition\n\n\n### find()\n\nReturns the first matching element where the callback returns TRUE.\n\n```php\npublic function find( \\Closure $callback, $default = null, bool $reverse = false )\n```\n\n* @param **\\Closure** `$callback` Function with (value, key) parameters and returns TRUE/FALSE\n* @param **mixed** `$default` Default value, closure or exception if the callback only returns FALSE\n* @param **bool** `$reverse` TRUE to test elements from back to front, FALSE for front to back (default)\n* @return **mixed\u0026#124;null** First matching value, passed default value or an exception\n\n**Examples:**\n\n```php\nMap::from( ['a', 'c', 'e'] )-\u003efind( function( $value, $key ) {\n    return $value \u003e= 'b';\n} );\n// 'c'\n\nMap::from( ['a', 'c', 'e'] )-\u003efind( function( $value, $key ) {\n    return $value \u003e= 'b';\n}, null, true );\n// 'e' because $reverse = true\n\nMap::from( [] )-\u003efind( function( $value, $key ) {\n    return $value \u003e= 'b';\n}, 'none' );\n// 'none'\n\nMap::from( [] )-\u003efind( function( $value, $key ) {\n    return $value \u003e= 'b';\n}, fn() =\u003e 'none' );\n// 'none'\n\nMap::from( [] )-\u003efind( function( $value, $key ) {\n    return $value \u003e= 'b';\n}, new \\Exception( 'error' ) );\n// throws \\Exception\n```\n\n**See also:**\n\n* [findKey()](#findkey) - Returns the first matching key where the callback returns TRUE\n\n\n### findKey()\n\nReturns the first matching key where the callback returns TRUE.\n\n```php\npublic function findKey( \\Closure $callback, $default = null, bool $reverse = false )\n```\n\n* @param **\\Closure** `$callback` Function with (value, key) parameters and returns TRUE/FALSE\n* @param **mixed** `$default` Default value, closure or exception if the callback only returns FALSE\n* @param **bool** `$reverse` TRUE to test elements from back to front, FALSE for front to back (default)\n* @return **mixed\u0026#124;null** First matching value, passed default value or an exception\n\n**Examples:**\n\n```php\nMap::from( ['a', 'c', 'e'] )-\u003efindKey( function( $value, $key ) {\n    return $value \u003e= 'b';\n} );\n// 1 because array has keys 0, 1 and 2\n\nMap::from( ['a', 'c', 'e'] )-\u003efindKey( function( $value, $key ) {\n    return $value \u003e= 'b';\n}, null, true );\n// 2 because array is reversed and 'e' \u003e= 'b'\n\nMap::from( [] )-\u003efindKey( function( $value, $key ) {\n    return $value \u003e= 'b';\n}, fn() =\u003e 'none' );\n// default value 'none'\n\nMap::from( [] )-\u003efindKey( function( $value, $key ) {\n    return $value \u003e= 'b';\n}, new \\Exception( 'error' ) );\n// throws exception\n```\n\n**See also:**\n\n* [find()](#find) - Returns the first matching element where the callback returns TRUE\n\n\n### first()\n\nReturns the first element from the map.\n\n```php\npublic function first( $default = null )\n```\n\n* @param **mixed** `$default` Default value, closure or exception if the map contains no elements\n* @return **mixed** First value of map, (generated) default value or an exception\n\nUsing this method doesn't affect the internal array pointer.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003efirst();\n// 'a'\n\nMap::from( [] )-\u003efirst( 'x' );\n// 'x'\n\nMap::from( [] )-\u003efirst( new \\Exception( 'error' ) );\n// throws \\Exception\n\nMap::from( [] )-\u003efirst( function() { return rand(); } );\n// random integer\n```\n\n**See also:**\n\n* [firstKey()](#firstkey) - Returns the key of the first element from the map\n* [last()](#last) - Returns the last element from the map\n* [lastKey()](#lastkey) - Returns the key of the last element from the map\n\n\n### firstKey()\n\nReturns the key of the first element from the map.\n\n```php\npublic function firstKey( $default = null )\n```\n\n* @param **mixed** `$default` Default value, closure or exception if the map contains no elements\n* @return **mixed** First key of map, (generated) default value or an exception\n\nUsing this method doesn't affect the internal array pointer.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 2] )-\u003efirstKey();\n// 'a'\n\nMap::from( [] )-\u003efirstKey( 'x' );\n// 'x'\n\nMap::from( [] )-\u003efirstKey( new \\Exception( 'error' ) );\n// throws \\Exception\n\nMap::from( [] )-\u003efirstKey( function() { return rand(); } );\n// random integer\n```\n\n**See also:**\n\n* [first()](#first) - Returns the first element from the map\n* [last()](#last) - Returns the last element from the map\n* [lastKey()](#lastkey) - Returns the last key from the map\n\n\n### flat()\n\nCreates a new map with all sub-array elements added recursively.\n\n```php\npublic function flat( int $depth = null ) : self\n```\n\n* @param **int\u0026#124;null** `$depth` Number of levels to flatten multi-dimensional arrays\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with all sub-array elements added into it recursively, up to the specified depth\n\nThe keys are not preserved and the new map elements will be numbered from\n0-n. A value smaller than 1 for depth will return the same map elements\nindexed from 0-n. Flattening does also work if elements implement the\n\"Traversable\" interface (which the Map object does).\n\nThis method is similar than [collapse()](#collapse) but doesn't replace existing elements.\nKeys are NOT preserved using this method!\n\n**Examples:**\n\n```php\nMap::from( [[0, 1], [2, 3]] )-\u003eflat();\n// [0, 1, 2, 3]\n\nMap::from( [[0, 1], [[2, 3], 4]] )-\u003eflat();\n// [0, 1, 2, 3, 4]\n\nMap::from( [[0, 1], [[2, 3], 4]] )-\u003eflat( 1 );\n// [0, 1, [2, 3], 4]\n\nMap::from( [[0, 1], Map::from( [[2, 3], 4] )] )-\u003eflat();\n// [0, 1, 2, 3, 4]\n```\n\n**See also:**\n\n* [collapse()](#collapse) - Collapses all sub-array elements recursively to a new map\n\n\n### flip()\n\nExchanges the keys with their values and vice versa.\n\n```php\npublic function flip() : self\n```\n\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with keys as values and values as keys\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'X', 'b' =\u003e 'Y'] )-\u003eflip();\n// ['X' =\u003e 'a', 'Y' =\u003e 'b']\n```\n\n\n### float()\n\nReturns an element by key and casts it to float if possible.\n\n```php\npublic function float( $key, $default = 0.0 ) : float\n```\n\n* @param **int\u0026#124;string** `$key` Key or path to the requested item\n* @param **mixed** `$default` Default value if key isn't found (will be casted to float)\n* @return **float** Value from map or default value\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e true] )-\u003efloat( 'a' );\n// 1.0 (casted to float)\n\nMap::from( ['a' =\u003e 1] )-\u003efloat( 'a' );\n// 1.0 (casted to float)\n\nMap::from( ['a' =\u003e '1.1'] )-\u003efloat( 'a' );\n// 1.1 (casted to float)\n\nMap::from( ['a' =\u003e '10'] )-\u003efloat( 'a' );\n// 10.0 (casted to float)\n\nMap::from( ['a' =\u003e ['b' =\u003e ['c' =\u003e 1.1]]] )-\u003efloat( 'a/b/c' );\n// 1.1\n\nMap::from( [] )-\u003efloat( 'c', function() { return 1.1; } );\n// 1.1\n\nMap::from( [] )-\u003efloat( 'a', 1 );\n// 1.0 (default value used)\n\nMap::from( [] )-\u003efloat( 'a' );\n// 0.0\n\nMap::from( ['b' =\u003e ''] )-\u003efloat( 'b' );\n// 0.0 (casted to float)\n\nMap::from( ['a' =\u003e 'abc'] )-\u003efloat( 'a' );\n// 0.0 (casted to float)\n\nMap::from( ['b' =\u003e null] )-\u003efloat( 'b' );\n// 0.0 (null is not scalar)\n\nMap::from( ['b' =\u003e [true]] )-\u003efloat( 'b' );\n// 0.0 (arrays are not scalar)\n\nMap::from( ['b' =\u003e '#resource'] )-\u003efloat( 'b' );\n// 0.0 (resources are not scalar)\n\nMap::from( ['b' =\u003e new \\stdClass] )-\u003efloat( 'b' );\n// 0.0 (objects are not scalar)\n\nMap::from( [] )-\u003efloat( 'c', new \\Exception( 'error' ) );\n// throws exception\n```\n\n**See also:**\n\n* [bool()](#bool) - Returns an element by key and casts it to boolean if possible\n* [cast()](#cast) - Casts all entries to the passed type\n* [get()](#get) - Returns an element from the map by key\n* [int()](#int) - Returns an element by key and casts it to integer if possible\n* [string()](#string) - Returns an element by key and casts it to string if possible\n\n\n### from()\n\nCreates a new map instance if the value isn't one already.\n\n```php\npublic static function from( $elements = [] ) : self\n```\n\n* @param **mixed** `$elements` List of elements or single value\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\n**Examples:**\n\n```php\n// array\nMap::from( [] );\n\n// null\nMap::from( null );\n\n// scalar\nMap::from( 'a' );\n\n// object\nMap::from( new \\stdClass() );\n\n// map object\nMap::from( new Map() );\n\n// iterable object\nMap::from( new ArrayObject() );\n\n// closure evaluated lazily\nMap::from( function() {\n    return [];\n} );\n```\n\n**See also:**\n\n* [fromJson()](#fromjson) - Creates a new map instance from a JSON string\n\n\n### fromJson()\n\nCreates a new map instance from a JSON string.\n\n```php\npublic static function fromJson( string $json, int $options = JSON_BIGINT_AS_STRING ) : self\n```\n\n* @param **int** `$options` Combination of JSON_* constants\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map from decoded JSON string\n* @throws **\\RuntimeException** If the passed JSON string is invalid\n\nThere are several options available for decoding the JSON string which are described in\nthe [PHP json_decode() manual](https://www.php.net/manual/en/function.json-decode.php).\nThe parameter can be a single JSON_* constant or a bitmask of several constants combine\nby bitwise OR (\u0026#124;), e.g.:\n\nThis method creates a lazy Map and the string is decoded after calling\nanother method that operates on the Map contents. Thus, the exception in\ncase of an error isn't thrown immediately but after calling the next method.\n\n```php\nJSON_BIGINT_AS_STRING|JSON_INVALID_UTF8_IGNORE\n```\n\n**Examples:**\n\n```php\nMap::fromJson( '[\"a\", \"b\"]' );\n// ['a', 'b']\n\nMap::fromJson( '{\"a\": \"b\"}' );\n// ['a' =\u003e 'b']\n\nMap::fromJson( '\"\"' );\n['']\n```\n\n**See also:**\n\n* [from()](#from) - Creates a new map instance if the value isn't one already\n\n\n### get()\n\nReturns an element from the map by key.\n\n```php\npublic function get( $key, $default = null )\n```\n\n* @param **int\u0026#124;string** `$key` Key or path to the requested item\n* @param **mixed** `$default` Default value if no element matches\n* @return **mixed** Value from map or default value\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'X', 'b' =\u003e 'Y'] )-\u003eget( 'a' );\n// 'X'\n\nMap::from( ['a' =\u003e 'X', 'b' =\u003e 'Y'] )-\u003eget( 'c', 'Z' );\n// 'Z'\n\nMap::from( ['a' =\u003e ['b' =\u003e ['c' =\u003e 'Y']]] )-\u003eget( 'a/b/c' );\n// 'Y'\n\nMap::from( [] )-\u003eget( 'c', new \\Exception( 'error' ) );\n// throws \\Exception\n\nMap::from( [] )-\u003eget( 'c', function() { return rand(); } );\n// random integer\n```\n\n**See also:**\n\n* [bool()](#bool) - Returns an element by key and casts it to boolean if possible\n* [int()](#int) - Returns an element by key and casts it to integer if possible\n* [float()](#float) - Returns an element by key and casts it to float if possible\n* [pull()](#pull) - Returns and removes an element from the map by its key\n* [set()](#set) - Sets an element in the map by key without returning a new map\n* [string()](#string) - Returns an element by key and casts it to string if possible\n\n\n### getIterator()\n\nReturns an iterator for the elements.\n\n```php\npublic function getIterator() : \\ArrayIterator\n```\n\n* @return **\\Iterator** Over map elements\n\nThis method will be used by e.g. `foreach()` to loop over all entries.\n\n**Examples:**\n\n```php\nforeach( Map::from( ['a', 'b'] ) as $value ) {\n    // ...\n}\n```\n\n\n### grep()\n\nReturns only items which matches the regular expression.\n\n```php\npublic function grep( string $pattern, int $flags = 0 ) : self\n```\n\n* @param **string** `$pattern` Regular expression pattern, e.g. \"/ab/\"\n* @param **int** `$flags` PREG_GREP_INVERT to return elements not matching the pattern\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map containing only the matched elements\n\nAll items are converted to string first before they are compared to the\nregular expression. Thus, fractions of \".0\" will be removed in float numbers\nwhich may result in unexpected results. The keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['ab', 'bc', 'cd'] )-\u003egrep( '/b/' );\n// ['ab', 'bc']\n\nMap::from( ['ab', 'bc', 'cd'] )-\u003egrep( '/a/', PREG_GREP_INVERT );\n// ['bc', 'cd']\n\nMap::from( [1.5, 0, 1.0, 'a'] )-\u003egrep( '/^(\\d+)?\\.\\d+$/' );\n// [1.5]\n// float 1.0 is converted to string \"1\"\n```\n\n**See also:**\n\n* [filter()](#filter) - Runs a filter over each element of the map and returns a new map\n* [where()](#where) - Filters the list of elements by a given condition\n\n\n### groupBy()\n\nGroups associative array elements or objects by the passed key or closure.\n\n```php\npublic function groupBy( $key ) : self\n```\n\n* @param **\\Closure\u0026#124;string\u0026#124;int** `$key` Closure function with (item, idx) parameters returning the key or the key itself to group by\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with elements grouped by the given key\n\nInstead of overwriting items with the same keys like to the [col()](#col) method does,\n[groupBy()](#groupby) keeps all entries in sub-arrays. It's preserves the keys of the\norignal map entries too.\n\nThis does also work for multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. \"key1/key2/key3\"\nto get \"val\" from ['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]. The same applies to\npublic properties of objects or objects implementing __isset() and __get() methods.\n\n**Examples:**\n\n```php\n$list = [\n    10 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-abc'],\n    20 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-def'],\n    30 =\u003e ['aid' =\u003e 456, 'code' =\u003e 'x-def']\n];\n\nMap::from( $list )-\u003egroupBy( 'aid' );\n/*\n[\n    123 =\u003e [\n        10 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-abc'],\n        20 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-def']\n    ],\n    456 =\u003e [\n        30 =\u003e ['aid' =\u003e 456, 'code' =\u003e 'x-def']\n    ]\n]\n*/\n\nMap::from( $list )-\u003egroupBy( function( $item, $key ) {\n    return substr( $item['code'], -3 );\n} );\n/*\n[\n    'abc' =\u003e [\n        10 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-abc']\n    ],\n    'def' =\u003e [\n        20 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-def'],\n        30 =\u003e ['aid' =\u003e 456, 'code' =\u003e 'x-def']\n    ]\n]\n*/\n```\n\nIn case the passed key doesn't exist in one or more items, these items are stored\nin a sub-array using an empty string as key:\n\n```php\n$list = [\n    10 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-abc'],\n    20 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-def'],\n    30 =\u003e ['aid' =\u003e 456, 'code' =\u003e 'x-def']\n];\n\nMap::from( $list )-\u003egroupBy( 'xid' );\n/*\n[\n    '' =\u003e [\n        10 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-abc'],\n        20 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-def'],\n        30 =\u003e ['aid' =\u003e 456, 'code' =\u003e 'x-def']\n    ]\n]\n*/\n```\n\n**See also:**\n\n* [countBy()](#countby) - Counts how often the same values are in the map\n\n\n### has()\n\nDetermines if a key or several keys exists in the map.\n\n```php\npublic function has( $key ) : bool\n```\n\n* @param **array\u0026#60;int\u0026#124;string\u0026#60;\u0026#124;int\u0026#124;string** `$key` Key or path to the requested item\n* @return **bool** TRUE if key is available in map, FALSE if not\n\nIf several keys are passed as array, all keys must exist in the map to\nreturn TRUE.\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'X', 'b' =\u003e 'Y'] )-\u003ehas( 'a' );\n// true\n\nMap::from( ['a' =\u003e 'X', 'b' =\u003e 'Y'] )-\u003ehas( ['a', 'b'] );\n// false\n\nMap::from( ['a' =\u003e ['b' =\u003e ['c' =\u003e 'Y']]] )-\u003ehas( 'a/b/c' );\n// true\n\nMap::from( ['a' =\u003e 'X', 'b' =\u003e 'Y'] )-\u003ehas( 'c' );\n// false\n\nMap::from( ['a' =\u003e 'X', 'b' =\u003e 'Y'] )-\u003ehas( ['a', 'c'] );\n// false\n\nMap::from( ['a' =\u003e 'X', 'b' =\u003e 'Y'] )-\u003ehas( 'X' );\n// false\n```\n\n\n### if()\n\nExecutes callbacks depending on the condition.\n\n```php\npublic function if( $condition, \\Closure $then, \\Closure $else = null ) : self\n```\n\n* @param **\\Closure\u0026#124;bool** `$condition` Boolean or function with (map) parameter returning a boolean\n* @param **\\Closure** `$then` Function with (map) parameter\n* @param **\\Closure\u0026#124;null** `$else` Function with (map) parameter (optional)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map for fluid interface\n\nIf callbacks for \"then\" and/or \"else\" are passed, these callbacks will be\nexecuted and their returned value is passed back within a Map object. In\ncase no \"then\" or \"else\" closure is given, the method will return the same\nmap object if the condition is true or an empty map object if it's false.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003eif(\n    'a' == 'b',\n    function( Map $_ ) { echo \"then\"; }\n);\n// no output\n\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003eif(\n    function( Map $map ) { return $map-\u003ehas( 'a' ); },\n    function( Map $_ ) { echo \"then\"; },\n    function( Map $_ ) { echo \"else\"; }\n);\n// then\n\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003eif(\n    fn( Map $map ) =\u003e $map-\u003ehas( 'c' ),\n    function( Map $_ ) { echo \"then\"; },\n    function( Map $_ ) { echo \"else\"; }\n);\n// else\n\nMap::from( ['a', 'b'] )-\u003eif( true, function( $map ) {\n    return $map-\u003epush( 'c' );\n} );\n// ['a', 'b', 'c']\n\nMap::from( ['a', 'b'] )-\u003eif( false, null, function( $map ) {\n  return $map-\u003epop();\n} );\n// ['b']\n```\n\nSince PHP 7.4, you can also pass arrow function like `fn($map) =\u003e $map-\u003ehas('c')`\n(a short form for anonymous closures) as parameters. The automatically have access\nto previously defined variables but can not modify them. Also, they can not have\na void return type and must/will always return something. Details about\n[PHP arrow functions](https://www.php.net/manual/en/functions.arrow.php)\n\n**See also:**\n\n* [ifAny()](#ifany) - Executes callbacks depending if the map contains elements or not\n* [ifEmpty()](#ifempty) - Executes callbacks depending if the map is empty or not\n\n\n### ifAny()\n\n* Executes callbacks depending if the map contains elements or not.\n\n```php\npublic function ifAny( \\Closure $then = null, \\Closure $else = null ) : self\n```\n\n* @param **\\Closure\u0026#124;null** `$then` Function with (map, condition) parameter (optional)\n* @param **\\Closure\u0026#124;null** `$else` Function with (map, condition) parameter (optional)\n* @return **self\u003cint\u0026#124;string,mixed\u003e** New map for fluid interface\n\nIf callbacks for \"then\" and/or \"else\" are passed, these callbacks will be\nexecuted and their returned value is passed back within a Map object. In\ncase no \"then\" or \"else\" closure is given, the method will return the same\nmap object.\n\n**Examples:**\n\n```php\nMap::from( ['a'] )-\u003eifAny( function( $map ) {\n  $map-\u003epush( 'b' );\n} );\n// ['a', 'b']\n\nMap::from( [] )-\u003eifAny( null, function( $map ) {\n  return $map-\u003epush( 'b' );\n} );\n// ['b']\n\nMap::from( ['a'] )-\u003eifAny( function( $map ) {\n  return 'c';\n} );\n// ['c']\n```\n\nSince PHP 7.4, you can also pass arrow function like `fn($map) =\u003e $map-\u003ehas('c')`\n(a short form for anonymous closures) as parameters. The automatically have access\nto previously defined variables but can not modify them. Also, they can not have\na void return type and must/will always return something. Details about\n[PHP arrow functions](https://www.php.net/manual/en/functions.arrow.php)\n\n**See also:**\n\n* [if()](#if) - Executes callbacks depending on the condition\n* [ifEmpty()](#ifempty) - Executes callbacks depending if the map is empty or not\n\n\n### ifEmpty()\n\n* Executes callbacks depending if the map is empty or not.\n\n```php\npublic function ifEmpty( \\Closure $then = null, \\Closure $else = null ) : self\n```\n\n* @param **\\Closure\u0026#124;null** `$then` Function with (map, condition) parameter (optional)\n* @param **\\Closure\u0026#124;null** `$else` Function with (map, condition) parameter (optional)\n* @return **self\u003cint\u0026#124;string,mixed\u003e** New map for fluid interface\n\nIf callbacks for \"then\" and/or \"else\" are passed, these callbacks will be\nexecuted and their returned value is passed back within a Map object. In\ncase no \"then\" or \"else\" closure is given, the method will return the same\nmap object.\n\n**Examples:**\n\n```php\nMap::from( [] )-\u003eifEmpty( function( $map ) {\n    $map-\u003epush( 'a' );\n} );\n// ['a']\n\nMap::from( ['a'] )-\u003eifEmpty( null, function( $map ) {\n    return $map-\u003epush( 'b' );\n} );\n// ['a', 'b']\n```\n\nSince PHP 7.4, you can also pass arrow function like `fn($map) =\u003e $map-\u003ehas('c')`\n(a short form for anonymous closures) as parameters. The automatically have access\nto previously defined variables but can not modify them. Also, they can not have\na void return type and must/will always return something. Details about\n[PHP arrow functions](https://www.php.net/manual/en/functions.arrow.php)\n\n**See also:**\n\n* [if()](#if) - Executes callbacks depending on the condition\n* [ifAny()](#ifany) - Executes callbacks depending if the map contains elements or not\n\n\n### implements()\n\nTests if all entries in the map are objects implementing the given interface.\n\n```php\npublic function implements( string $interface, $throw = false ) : bool\n```\n\n* @param **string** `$interface` Name of the interface that must be implemented\n* @param **\\Throwable\u0026#124;bool** `$throw` Passing TRUE or an exception name will throw the exception instead of returning FALSE\n* @return **bool** TRUE if all entries implement the interface or FALSE if at least one doesn't\n* @throws **\\UnexpectedValueException\u0026#124;\\Throwable** If one entry doesn't implement the interface\n\n**Examples:**\n\n```php\nMap::from( [new Map(), new Map()] )-\u003eimplements( '\\Countable' );\n// true\n\nMap::from( [new Map(), new \\stdClass()] )-\u003eimplements( '\\Countable' );\n// false\n\nMap::from( [new Map(), 123] )-\u003eimplements( '\\Countable' );\n// false\n\nMap::from( [new Map(), 123] )-\u003eimplements( '\\Countable', true );\n// throws \\UnexpectedValueException\n\nMap::from( [new Map(), 123] )-\u003eimplements( '\\Countable', '\\RuntimeException' );\n// throws \\RuntimeException\n```\n\n\n### in()\n\nTests if the passed element or elements are part of the map.\n\n```php\npublic function in( $element, bool $strict = false ) : bool\n```\n\n* @param **mixed\u0026#124;array** `$element` Element or elements to search for in the map\n* @param **bool** `$strict` TRUE to check the type too, using FALSE '1' and 1 will be the same\n* @return **bool** TRUE if all elements are available in map, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003ein( 'a' );\n// true\n\nMap::from( ['a', 'b'] )-\u003ein( ['a', 'b'] );\n// true\n\nMap::from( ['a', 'b'] )-\u003ein( 'x' );\n// false\n\nMap::from( ['a', 'b'] )-\u003ein( ['a', 'x'] );\n// false\n\nMap::from( ['1', '2'] )-\u003ein( 2, true );\n// false\n```\n\n**See also:**\n\n* [compare()](#compare) - Compares the value against all map elements\n* [contains()](#contains) - Tests if an item exists in the map\n* [includes()](#includes) - Tests if element is included\n* [none()](#none) - Tests if none of the elements are part of the map\n\n\n### includes()\n\nTests if the passed element or elements are part of the map (alias).\n\n```php\npublic function includes( $element, bool $strict = false ) : bool\n```\n\n* @param **mixed\u0026#124;array** `$element` Element or elements to search for in the map\n* @param **bool** `$strict` TRUE to check the type too, using FALSE '1' and 1 will be the same\n* @return **bool** TRUE if all elements are available in map, FALSE if not\n\nThis method is an alias for [in()](#in). For performance reasons, `in()` should be preferred\nbecause it uses one method call less than `includes()`.\n\n**See also:**\n\n* [compare()](#compare) - Compares the value against all map elements\n* [contains()](#contains) - Tests if an item exists in the map\n* [in()](#in) - Tests if element is included\n* [none()](#none) - Tests if none of the elements are part of the map\n\n\n### index()\n\nReturns the numerical index of the given key.\n\n```php\npublic function index( $value ) : ?int\n```\n\n* @param **\\Closure\u0026#124;string\u0026#124;int** `$value` Key to search for or function with (key) parameters return TRUE if key is found\n* @return **int\u0026#124;null** Position of the found value (zero based) or NULL if not found\n\n**Examples:**\n\n```php\nMap::from( [4 =\u003e 'a', 8 =\u003e 'b'] )-\u003eindex( '8' );\n// 1\n\nMap::from( [4 =\u003e 'a', 8 =\u003e 'b'] )-\u003eindex( function( $key ) {\n    return $key == '8';\n} );\n// 1\n```\n\nBoth examples will return \"1\" because the value \"b\" is at the second position\nand the returned index is zero based so the first item has the index \"0\".\n\n**See also:**\n\n* [at()](#at) - Returns the value at the given position\n* [pos()](#pos) - Returns the numerical index of the value\n\n\n### insertAfter()\n\nInserts the value or values after the given element.\n\n```php\npublic function insertAfter( $element, $value ) : self\n```\n\n* @param **mixed** `$element` Element after the value is inserted\n* @param **mixed** `$value` Element or list of elements to insert\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nNumerical array indexes are not preserved.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003einsertAfter( 'foo', 'baz' );\n// ['a' =\u003e 'foo', 0 =\u003e 'baz', 'b' =\u003e 'bar']\n\nMap::from( ['foo', 'bar'] )-\u003einsertAfter( 'foo', ['baz', 'boo'] );\n// ['foo', 'baz', 'boo', 'bar']\n\nMap::from( ['foo', 'bar'] )-\u003einsertAfter( null, 'baz' );\n// ['foo', 'bar', 'baz']\n```\n\n**See also:**\n\n* [insertAt()](#insertat) - Inserts the item at the given position in the map\n* [insertBefore()](#insertbefore) - Inserts the value or values before the given element\n\n\n### insertAt()\n\nInserts the item at the given position in the map.\n\n```php\npublic function insertAt( int $pos, $element, $key = null ) : self\n```\n\n* @param **int** `$pos` Position the element it should be inserted at\n* @param **mixed** `$element` Element to be inserted\n* @param **mixed\u0026#124;null** `$key` Element key or NULL to assign an integer key automatically\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003einsertAt( 0, 'baz' );\n// [0 =\u003e 'baz', 'a' =\u003e 'foo', 'b' =\u003e 'bar']\n\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003einsertAt( 1, 'baz', 'c' );\n// ['a' =\u003e 'foo', 'c' =\u003e 'baz', 'b' =\u003e 'bar']\n\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003einsertAt( 5, 'baz' );\n// ['a' =\u003e 'foo', 'b' =\u003e 'bar', 'c' =\u003e 'baz']\n\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003einsertAt( -1, 'baz', 'c' );\n// ['a' =\u003e 'foo', 'c' =\u003e 'baz', 'b' =\u003e 'bar']\n```\n\n**See also:**\n\n* [insertAfter()](#insertafter) - Inserts the value or values after the given element\n* [insertBefore()](#insertbefore) - Inserts the value or values before the given element\n\n\n### insertBefore()\n\nInserts the value or values before the given element.\n\n```php\npublic function insertBefore( $element, $value ) : self\n```\n\n* @param **mixed** `$element` Element before the value is inserted\n* @param **mixed** `$value` Element or list of elements to insert\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nNumerical array indexes are not preserved.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003einsertBefore( 'bar', 'baz' );\n// ['a' =\u003e 'foo', 0 =\u003e 'baz', 'b' =\u003e 'bar']\n\nMap::from( ['foo', 'bar'] )-\u003einsertBefore( 'bar', ['baz', 'boo'] );\n// ['foo', 'baz', 'boo', 'bar']\n\nMap::from( ['foo', 'bar'] )-\u003einsertBefore( null, 'baz' );\n// ['foo', 'bar', 'baz']\n```\n\n**See also:**\n\n* [insertAfter()](#insertafter) - Inserts the value or values after the given element\n* [insertAt()](#insertat) - Inserts the item at the given position in the map\n\n\n### inString()\n\nTests if the passed value or value are part of the strings in the map.\n\nThis method is deprecated in favor of the multi-byte aware [strContains()](#strcontains) method.\n\n```php\npublic function inString( $value, bool $case = true ) : bool\n```\n\n* @param **array\u0026#124;string** `$value` Value or values to compare the map elements, will be casted to string type\n* @param **bool** `$case` TRUE if comparison is case sensitive, FALSE to ignore upper/lower case\n* @return **bool** TRUE If at least one element matches, FALSE if value is not in any string of the map\n\nAll scalar values (bool, float, int and string) are casted to string values before\ncomparing to the given value. Non-scalar values in the map are ignored.\n\n**Examples:**\n\n```php\nMap::from( ['abc'] )-\u003einString( 'c' );\n// true ('abc' contains 'c')\n\nMap::from( ['abc'] )-\u003einString( 'bc' );\n// true ('abc' contains 'bc')\n\nMap::from( [12345] )-\u003einString( '23' );\n// true ('12345' contains '23')\n\nMap::from( [123.4] )-\u003einString( 23.4 );\n// true ('123.4' contains '23.4')\n\nMap::from( [12345] )-\u003einString( false );\n// true ('12345' contains '')\n\nMap::from( [12345] )-\u003einString( true );\n// true ('12345' contains '1')\n\nMap::from( [false] )-\u003einString( false );\n// true  ('' contains '')\n\nMap::from( ['abc'] )-\u003einString( '' );\n// true ('abc' contains '')\n\nMap::from( [''] )-\u003einString( false );\n// true ('' contains '')\n\nMap::from( ['abc'] )-\u003einString( 'BC', false );\n// true ('abc' contains 'BC' when case-insentive)\n\nMap::from( ['abc', 'def'] )-\u003einString( ['de', 'xy'] );\n// true ('def' contains 'de')\n\nMap::from( ['abc', 'def'] )-\u003einString( ['E', 'x'] );\n// false (doesn't contain \"E\" when case sensitive)\n\nMap::from( ['abc', 'def'] )-\u003einString( 'E' );\n// false (doesn't contain \"E\" when case sensitive)\n\nMap::from( [23456] )-\u003einString( true );\n// false ('23456' doesn't contain '1')\n\nMap::from( [false] )-\u003einString( 0 );\n// false ('' doesn't contain '0')\n```\n\n**See also:**\n\n* [strContains()](#strcontains) - Tests if at least one of the passed strings is part of at least one entry\n* [strContainsAll()](#strcontainsall) - Tests if all of the entries contains one of the passed strings\n\n\n### int()\n\nReturns an element by key and casts it to integer if possible.\n\n```php\npublic function int( $key, $default = 0 ) : int\n```\n\n* @param **int\u0026#124;string** `$key` Key or path to the requested item\n* @param **mixed** `$default` Default value if key isn't found (will be casted to int)\n* @return **int** Value from map or default value\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e true] )-\u003eint( 'a' );\n// 1\n\nMap::from( ['a' =\u003e '1'] )-\u003eint( 'a' );\n// 1 (casted to integer)\n\nMap::from( ['a' =\u003e 1.1] )-\u003eint( 'a' );\n// 1 (casted to integer)\n\nMap::from( ['a' =\u003e '10'] )-\u003eint( 'a' );\n// 10 (casted to integer)\n\nMap::from( ['a' =\u003e ['b' =\u003e ['c' =\u003e 1]]] )-\u003eint( 'a/b/c' );\n// 1\n\nMap::from( [] )-\u003eint( 'c', function() { return rand( 1, 1 ); } );\n// 1\n\nMap::from( [] )-\u003eint( 'a', 1 );\n// 1 (default value used)\n\nMap::from( [] )-\u003eint( 'a' );\n// 0\n\nMap::from( ['b' =\u003e ''] )-\u003eint( 'b' );\n// 0 (casted to integer)\n\nMap::from( ['a' =\u003e 'abc'] )-\u003eint( 'a' );\n// 0 (casted to integer)\n\nMap::from( ['b' =\u003e null] )-\u003eint( 'b' );\n// 0 (null is not scalar)\n\nMap::from( ['b' =\u003e [true]] )-\u003eint( 'b' );\n// 0 (arrays are not scalar)\n\nMap::from( ['b' =\u003e '#resource'] )-\u003eint( 'b' );\n// 0 (resources are not scalar)\n\nMap::from( ['b' =\u003e new \\stdClass] )-\u003eint( 'b' );\n// 0 (objects are not scalar)\n\nMap::from( [] )-\u003eint( 'c', new \\Exception( 'error' ) );\n// throws exception\n```\n\n**See also:**\n\n* [bool()](#bool) - Returns an element by key and casts it to boolean if possible\n* [cast()](#cast) - Casts all entries to the passed type\n* [get()](#get) - Returns an element from the map by key\n* [float()](#float) - Returns an element by key and casts it to float if possible\n* [string()](#string) - Returns an element by key and casts it to string if possible\n\n\n### intersect()\n\nReturns all values in a new map that are available in both, the map and the given elements.\n\n```php\npublic function intersect( iterable $elements, callable $callback = null ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements\n* @param **callable\u0026#124;null** `$callback` Function with (valueA, valueB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003eintersect( ['bar'] );\n// ['b' =\u003e 'bar']\n```\n\nIf a callback is passed, the given function will be used to compare the values.\nThe function must accept two parameters (vaA, valB) and must return\n-1 if value A is smaller than value B, 0 if both are equal and 1 if value A is\ngreater than value B. Both, a method name and an anonymous function can be passed:\n\n```php\nMap::from( [0 =\u003e 'a'] )-\u003eintersect( [0 =\u003e 'A'], 'strcasecmp' );\n// ['a']\n\nMap::from( ['b' =\u003e 'a'] )-\u003eintersect( ['B' =\u003e 'A'], 'strcasecmp' );\n// ['a']\n\nMap::from( ['b' =\u003e 'a'] )-\u003eintersect( ['c' =\u003e 'A'], function( $valA, $valB ) {\n    return strtolower( $valA ) \u003c=\u003e strtolower( $valB );\n} );\n// ['a']\n```\n\n**See also:**\n\n* [intersectAssoc()](#intersectassoc) - Returns all values in a new map that are available in both, the map and the given elements while comparing the keys too\n* [intersectKeys()](#intersectkeys) - Returns all values in a new map that are available in both, the map and the given elements by comparing the keys only\n\n\n### intersectAssoc()\n\nReturns all values in a new map that are available in both, the map and the given elements while comparing the keys too.\n\n```php\npublic function intersectAssoc( iterable $elements, callable $callback = null ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements\n* @param **callable\u0026#124;null** `$callback` Function with (valueA, valueB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003eintersectAssoc( new Map( ['foo', 'b' =\u003e 'bar'] ) );\n// ['a' =\u003e 'foo']\n```\n\nIf a callback is passed, the given function will be used to compare the values.\nThe function must accept two parameters (valA, valB) and must return\n-1 if value A is smaller than value B, 0 if both are equal and 1 if value A is\ngreater than value B. Both, a method name and an anonymous function can be passed:\n\n```php\nMap::from( [0 =\u003e 'a'] )-\u003eintersectAssoc( [0 =\u003e 'A'], 'strcasecmp' );\n// [0 =\u003e 'a']\n\nMap::from( ['b' =\u003e 'a'] )-\u003eintersectAssoc( ['B' =\u003e 'A'], 'strcasecmp' );\n// ['b' =\u003e 'a']\n\nMap::from( ['b' =\u003e 'a'] )-\u003eintersectAssoc( ['c' =\u003e 'A'], function( $valA, $valB ) {\n    return strtolower( $valA ) \u003c=\u003e strtolower( $valB );\n} );\n// []\n```\n\n**See also:**\n\n* [intersect()](#intersect) - Returns all values in a new map that are available in both, the map and the given elements\n* [intersectKeys()](#intersectkeys) - Returns all values in a new map that are available in both, the map and the given elements by comparing the keys only\n\n\n### intersectKeys()\n\nReturns all values in a new map that are available in both, the map and the given elements by comparing the keys only.\n\n```php\npublic function intersectKeys( iterable $elements, callable $callback = null ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements\n* @param **callable\u0026#124;null** `$callback` Function with (keyA, keyB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'foo', 'b' =\u003e 'bar'] )-\u003eintersectKeys( new Map( ['foo', 'b' =\u003e 'baz'] ) );\n// ['b' =\u003e 'bar']\n```\n\nIf a callback is passed, the given function will be used to compare the keys.\nThe function must accept two parameters (key A and B) and must return\n-1 if key A is smaller than key B, 0 if both are equal and 1 if key A is\ngreater than key B. Both, a method name and an anonymous function can be passed:\n\n```php\nMap::from( [0 =\u003e 'a'] )-\u003eintersectKeys( [0 =\u003e 'A'], 'strcasecmp' );\n// [0 =\u003e 'a']\n\nMap::from( ['b' =\u003e 'a'] )-\u003eintersectKeys( ['B' =\u003e 'X'], 'strcasecmp' );\n// ['b' =\u003e 'a']\n\nMap::from( ['b' =\u003e 'a'] )-\u003eintersectKeys( ['c' =\u003e 'a'], function( $keyA, $keyB ) {\n    return strtolower( $keyA ) \u003c=\u003e strtolower( $keyB );\n} );\n// []\n```\n\n**See also:**\n\n* [intersect()](#intersect) - Returns all values in a new map that are available in both, the map and the given elements\n* [intersectAssoc()](#intersectassoc) - Returns all values in a new map that are available in both, the map and the given elements while comparing the keys too\n\n\n### is()\n\nTests if the map consists of the same keys and values\n\n```php\npublic function is( iterable $list, bool $strict = false ) : bool\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$list` List of key/value pairs to compare with\n* @param **bool** `$strict` TRUE for comparing order of elements too, FALSE for key/values only\n* @return **bool** TRUE if given list is equal, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003eis( ['b', 'a'] );\n// true\n\nMap::from( ['a', 'b'] )-\u003eis( ['b', 'a'], true );\n// false\n\nMap::from( [1, 2] )-\u003eis( ['1', '2'] );\n// false\n```\n\n**See also:**\n\n* [equals()](#equals) - Tests if the passed elements are equal to the elements in the map\n\n\n### isEmpty()\n\nDetermines if the map is empty or not.\n\n```php\npublic function isEmpty() : bool\n```\n\n* @return **bool** TRUE if map is empty, FALSE if not\n\nThe method is equivalent to [empty()](#empty).\n\n**Examples:**\n\n```php\nMap::from( [] )-\u003eisEmpty();\n// true\n\nMap::from( ['a'] )-isEmpty();\n// false\n```\n\n**See also:**\n\n* [empty()](#empty) - Determines if the map is empty or not\n\n\n### isList()\n\nChecks if the map contains a list of subsequentially numbered keys.\n\n```php\npublic function isList() : bool\n```\n\n* @return bool TRUE if the map is a list, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( [] )-\u003eisList();\n// true\n\nMap::from( [1, 3, 2] )-\u003eisList();\n// true, keys are 0, 1 and 2\n\nMap::from( [0 =\u003e 1, 1 =\u003e 2, 2 =\u003e 3] )-\u003eisList();\n// true, keys are consecutive\n\nMap::from( [1 =\u003e 1, 2 =\u003e 2, 3 =\u003e 3] )-\u003eisList();\n// false, keys doesn't start with 0\n\nMap::from( [0 =\u003e 1, 2 =\u003e 2, 3 =\u003e 3] )-\u003eisList();\n// false, keys are not consecutive\n\nMap::from( ['a' =\u003e 1, 1 =\u003e 2, 'c' =\u003e 3] )-\u003eisList();\n// false, keys are not all numeric\n```\n\n**See also:**\n\n* [isObject()](#isobject) - Determines if all entries are objects\n* [isNumeric()](#isnumeric) - Determines if all entries are numeric values\n* [isScalar()](#isscalar) - Determines if all entries are scalar values\n* [isString()](#isstring) - Determines if all entries are string values\n\n\n### isObject()\n\nDetermines if all entries are objects.\n\n```php\npublic function isObject() : bool\n```\n\n* @return **bool** TRUE if all map entries are objects, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( [] )-\u003eisObject();\n// true\n\nMap::from( [new stdClass] )-\u003eisObject();\n// true\n\nMap::from( [1] )-\u003eisObject();\n// false\n```\n\n**See also:**\n\n* [isList()](#islist) - Checks if the map contains a list of subsequentially numbered keys\n* [isNumeric()](#isnumeric) - Determines if all entries are numeric values\n* [isScalar()](#isscalar) - Determines if all entries are scalar values\n* [isString()](#isstring) - Determines if all entries are string values\n\n\n### isNumeric()\n\nDetermines if all entries are numeric values.\n\n```php\npublic function isNumeric() : bool\n```\n\n* @return **bool** TRUE if all map entries are numeric values, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( [] )-\u003eisNumeric();\n// true\n\nMap::from( [1] )-\u003eisNumeric();\n// true\n\nMap::from( [1.1] )-\u003eisNumeric();\n// true\n\nMap::from( [010] )-\u003eisNumeric();\n// true\n\nMap::from( [0x10] )-\u003eisNumeric();\n// true\n\nMap::from( [0b10] )-\u003eisNumeric();\n// true\n\nMap::from( ['010'] )-\u003eisNumeric();\n// true\n\nMap::from( ['10'] )-\u003eisNumeric();\n// true\n\nMap::from( ['10.1'] )-\u003eisNumeric();\n// true\n\nMap::from( [' 10 '] )-\u003eisNumeric();\n// true\n\nMap::from( ['10e2'] )-\u003eisNumeric();\n// true\n\nMap::from( ['0b10'] )-\u003eisNumeric();\n// false\n\nMap::from( ['0x10'] )-\u003eisNumeric();\n// false\n\nMap::from( ['null'] )-\u003eisNumeric();\n// false\n\nMap::from( [null] )-\u003eisNumeric();\n// false\n\nMap::from( [true] )-\u003eisNumeric();\n// false\n\nMap::from( [[]] )-\u003eisNumeric();\n// false\n\nMap::from( [''] )-\u003eisNumeric();\n// false\n```\n\n**See also:**\n\n* [isList()](#islist) - Checks if the map contains a list of subsequentially numbered keys\n* [isObject()](#isobject) - Determines if all entries are objects\n* [isScalar()](#isscalar) - Determines if all entries are scalar values\n* [isString()](#isstring) - Determines if all entries are string values\n\n\n### isScalar()\n\nDetermines if all entries are scalar values.\n\n```php\npublic function isScalar() : bool\n```\n\n* @return **bool** TRUE if all map entries are scalar values, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( [] )-\u003eisScalar();\n// true\n\nMap::from( [1] )-\u003eisScalar();\n// true\n\nMap::from( [1.1] )-\u003eisScalar();\n// true\n\nMap::from( ['abc'] )-\u003eisScalar();\n// true\n\nMap::from( [true, false] )-\u003eisScalar();\n// true\n\nMap::from( [new stdClass] )-\u003eisScalar();\n// false\n\nMap::from( [resource] )-\u003eisScalar();\n// false\n\nMap::from( [null] )-\u003eisScalar();\n// false\n\nMap::from( [[1]] )-\u003eisScalar();\n// false\n```\n\n**See also:**\n\n* [isList()](#islist) - Checks if the map contains a list of subsequentially numbered keys\n* [isObject()](#isobject) - Determines if all entries are objects\n* [isNumeric()](#isnumeric) - Determines if all entries are numeric values\n* [isString()](#isstring) - Determines if all entries are string values\n\n\n### isString()\n\nDetermines if all entries are string values.\n\n```php\npublic function isString() : bool\n```\n\n* @return **bool** TRUE if all map entries are string values, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( ['abc'] )-\u003eisString();\n// true\n\nMap::from( [] )-\u003eisString();\n// true\n\nMap::from( [1] )-\u003eisString();\n// false\n\nMap::from( [1.1] )-\u003eisString();\n// false\n\nMap::from( [true, false] )-\u003eisString();\n// false\n\nMap::from( [new stdClass] )-\u003eisString();\n// false\n\nMap::from( [resource] )-\u003eisString();\n// false\n\nMap::from( [null] )-\u003eisString();\n// false\n\nMap::from( [[1]] )-\u003eisString();\n// false\n```\n\n**See also:**\n\n* [isList()](#islist) - Checks if the map contains a list of subsequentially numbered keys\n* [isObject()](#isobject) - Determines if all entries are objects\n* [isNumeric()](#isnumeric) - Determines if all entries are numeric values\n* [isScalar()](#isscalar) - Determines if all entries are scalar values\n\n\n### join()\n\nConcatenates the string representation of all elements.\n\n```php\npublic function join( $glue = '' ) : string\n```\n\n* @param **string** `$glue` Character or string added between elements\n* @return **string** String of concatenated map elements\n\nObjects that implement `__toString()` does also work, otherwise (and in case\nof arrays) a PHP notice is generated. NULL and FALSE values are treated as\nempty strings.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b', false] )-\u003ejoin();\n// 'ab'\n\nMap::from( ['a', 'b', null, false] )-\u003ejoin( '-' );\n// 'a-b--'\n```\n\n\n### jsonSerialize()\n\nSpecifies the data which should be serialized to JSON by json_encode().\n\n```php\npublic function jsonSerialize()\n```\n\n* @return **array\u0026#60;int\u0026#124;string,mixed\u0026#62;** Data to serialize to JSON\n\n**Examples:**\n\n```php\njson_encode( Map::from( ['a', 'b'] ) );\n// [\"a\", \"b\"]\n\njson_encode( Map::from( ['a' =\u003e 0, 'b' =\u003e 1] ) );\n// {\"a\":0,\"b\":1}\n```\n\n\n### keys()\n\nReturns the keys of the map elements in a new map object.\n\n```php\npublic function keys() : self\n```\n\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] );\n// [0, 1]\n\nMap::from( ['a' =\u003e 0, 'b' =\u003e 1] );\n// ['a', 'b']\n```\n\n\n### krsort()\n\nSorts the elements by their keys in reverse order.\n\n```php\npublic function krsort( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `krsort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe parameter modifies how the keys are compared. Possible values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\nThe keys are preserved using this method and no new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['b' =\u003e 0, 'a' =\u003e 1] )-\u003ekrsort();\n// ['a' =\u003e 1, 'b' =\u003e 0]\n\nMap::from( [1 =\u003e 'a', 0 =\u003e 'b'] )-\u003ekrsort();\n// [0 =\u003e 'b', 1 =\u003e 'a']\n```\n\n**See also:**\n\n* [krsorted()](#krsorted) - Sorts a copy of the elements by their keys in reverse order\n\n\n### krsorted()\n\nSorts a copy of the elements by their keys in reverse order.\n\n```php\npublic function krsorted( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `krsort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe parameter modifies how the keys are compared. Possible values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\nThe keys are preserved using this method and a new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['b' =\u003e 0, 'a' =\u003e 1] )-\u003ekrsorted();\n// ['a' =\u003e 1, 'b' =\u003e 0]\n\nMap::from( [1 =\u003e 'a', 0 =\u003e 'b'] )-\u003ekrsorted();\n// [0 =\u003e 'b', 1 =\u003e 'a']\n```\n\n**See also:**\n\n* [krsort()](#krsort) - Sorts the elements by their keys in reverse order\n\n\n### krsorted()\n\nSorts a copy of the elements by their keys in reverse order.\n\n```php\npublic function krsorted( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `krsort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe parameter modifies how the keys are compared. Possible values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\nThe keys are preserved using this method and a new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['b' =\u003e 0, 'a' =\u003e 1] )-\u003ekrsorted();\n// ['a' =\u003e 1, 'b' =\u003e 0]\n\nMap::from( [1 =\u003e 'a', 0 =\u003e 'b'] )-\u003ekrsorted();\n// [0 =\u003e 'b', 1 =\u003e 'a']\n```\n\n\n### ksort()\n\nSorts the elements by their keys.\n\n```php\npublic function ksort( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `ksort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe parameter modifies how the keys are compared. Possible values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\nThe keys are preserved using this method and no new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['b' =\u003e 0, 'a' =\u003e 1] )-\u003eksort();\n// ['a' =\u003e 1, 'b' =\u003e 0]\n\nMap::from( [1 =\u003e 'a', 0 =\u003e 'b'] )-\u003eksort();\n// [0 =\u003e 'b', 1 =\u003e 'a']\n```\n\n\n### ksorted()\n\nSorts a copy of the elements by their keys.\n\n```php\npublic function ksorted( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `ksort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe parameter modifies how the keys are compared. Possible values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\nThe keys are preserved using this method and a new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['b' =\u003e 0, 'a' =\u003e 1] )-\u003eksorted();\n// ['a' =\u003e 1, 'b' =\u003e 0]\n\nMap::from( [1 =\u003e 'a', 0 =\u003e 'b'] )-\u003eksorted();\n// [0 =\u003e 'b', 1 =\u003e 'a']\n```\n\n\n### last()\n\nReturns the last element from the map.\n\n```php\npublic function last( $default = null )\n```\n\n* @param **mixed** `$default` Default value, closure or exception if the map contains no elements\n* @return **mixed** Last value of map, (generated) default value or an exception\n\nUsing this method doesn't affect the internal array pointer.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003elast();\n// 'b'\n\nMap::from( [] )-\u003elast( 'x' );\n// 'x'\n\nMap::from( [] )-\u003elast( new \\Exception( 'error' ) );\n// throws \\Exception\n\nMap::from( [] )-\u003elast( function() { return rand(); } );\n// random integer\n```\n\n**See also:**\n\n* [first()](#first) - Returns the first element from the map\n* [firstKey()](#firstkey) - Returns the key of the first element from the map\n* [lastKey()](#lastkey) - Returns the key of the last element from the map\n\n\n### lastKey()\n\nReturns the key of the last element from the map.\n\n```php\npublic function lastKey( $default = null )\n```\n\n* @param **mixed** `$default` Default value, closure or exception if the map contains no elements\n* @return **mixed** Last key of map, (generated) default value or an exception\n\nUsing this method doesn't affect the internal array pointer.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 2] )-\u003elastKey();\n// 'b'\n\nMap::from( [] )-\u003elastKey( 'x' );\n// 'x'\n\nMap::from( [] )-\u003elastKey( new \\Exception( 'error' ) );\n// throws \\Exception\n\nMap::from( [] )-\u003elastKey( function() { return rand(); } );\n// random integer\n```\n\n**See also:**\n\n* [first()](#first) - Returns the first element from the map\n* [firstKey()](#firstkey) - Returns the key of the first element from the map\n* [last()](#last) - Returns the last element from the map\n\n\n### ltrim()\n\nRemoves the passed characters from the left of all strings.\n\n```php\npublic function ltrim( string $chars = \" \\n\\r\\t\\v\\x00\" ) : self\n```\n\n* @param **string** `$chars` List of characters to trim\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( [\" abc\\n\", \"\\tcde\\r\\n\"] )-\u003eltrim();\n// [\"abc\\n\", \"cde\\r\\n\"]\n\nMap::from( [\"a b c\", \"cbxa\"] )-\u003eltrim( 'abc' );\n// [\" b c\", \"xa\"]\n```\n\n**See also:**\n\n* [ltrim()](#ltrim) - Removes the passed characters from the left of all strings\n* [rtrim()](#rtrim) - Removes the passed characters from the right of all strings\n* [trim()](#trim) - Removes the passed characters from the left/right of all strings\n\n\n### map()\n\nMaps new values to the existing keys using the passed function and returns a new map for the result.\n\n```php\npublic function map( callable $callback ) : self\n```\n\n* @param **callable** `$callback` Function with (value, key) parameters and returns computed result\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with the original keys and the computed values\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 2, 'b' =\u003e 4] )-\u003emap( function( $value, $key ) {\n    return $value * 2;\n} );\n// ['a' =\u003e 4, 'b' =\u003e 8]\n```\n\n**See also:**\n\n* [col()](#col) - Returns the values of a single column/property from an array of arrays or list of elements in a new map\n* [pluck()](#pluck) - Creates a key/value mapping (alias)\n* [rekey()](#pluck) - Changes the keys according to the passed function\n\n\n### max()\n\nReturns the maximum value of all elements.\n\n```php\npublic function max( $col = null )\n```\n\n* @param **Closure\u0026#124;string\u0026#124;null** `$col` Closure, key in the nested array or object to check for\n* @return **mixed** Maximum value or NULL if there are no elements in the map\n\nNULL values are removed before the comparison. If there are no values or all\nvalues are NULL, NULL is returned.\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\nBe careful comparing elements of different types because this can have\nunpredictable results due to the [PHP comparison rules](https://www.php.net/manual/en/language.operators.comparison.php)\n\n**Examples:**\n\n```php\nMap::from( [1, 3, 2, 5, 4] )-\u003emax();\n// 5\n\nMap::from( ['bar', 'foo', 'baz'] )-\u003emax();\n// 'foo'\n\nMap::from( [['p' =\u003e 30], ['p' =\u003e 50], ['p' =\u003e 10]] )-\u003emax( 'p' );\n// 50\n\nMap::from( [['i' =\u003e ['p' =\u003e 30]], ['i' =\u003e ['p' =\u003e 50]]] )-\u003emax( 'i/p' );\n// 50\n\nMap::from( [['i' =\u003e ['p' =\u003e 30]], ['i' =\u003e ['p' =\u003e 50]]] )-\u003emax( fn( $val, $key ) =\u003e $val['i']['p'] ?? null )\n// 50\n\nMap::from( [50, 10, 30] )-\u003emax( fn( $val, $key ) =\u003e $key \u003e 0 ? $val : null )\n// 30\n```\n\n**See also:**\n\n* [avg()](#avg) - Returns the average of all integer and float values in the map\n* [count()](#count) - Returns the total number of elements\n* [min()](#min) - Returns the minium value of all elements\n* [percentage()](#percentage) - Returns the percentage of all elements passing the test\n* [sum()](#sum) - Returns the sum of all values in the map\n\n\n### merge()\n\nMerges the map with the given elements without returning a new map.\n\n```php\npublic function merge( iterable $elements, bool $recursive = false ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements\n* @param **bool** `$recursive` TRUE to merge nested arrays too, FALSE for first level elements only\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nElements with the same non-numeric keys will be overwritten, elements with the\nsame numeric keys will be added.\n\nThe method is similar to [replace()](#replace) but doesn't replace elements with the same\nnumeric keys. If you want to be sure that all passed elements are added without\nreplacing existing ones, use [concat()](#concat) instead.\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003emerge( ['b', 'c'] );\n// ['a', 'b', 'b', 'c']\n\nMap::from( ['a' =\u003e 1, 'b' =\u003e 2] )-\u003emerge( ['b' =\u003e 4, 'c' =\u003e 6] );\n// ['a' =\u003e 1, 'b' =\u003e 4, 'c' =\u003e 6]\n\nMap::from( ['a' =\u003e 1, 'b' =\u003e 2] )-\u003emerge( ['b' =\u003e 4, 'c' =\u003e 6], true );\n// ['a' =\u003e 1, 'b' =\u003e [2, 4], 'c' =\u003e 6]\n```\n\n**See also:**\n\n* [concat()](#combine) - Adds all elements with new keys\n* [union()](#union) - Builds a union of the elements and the given elements without returning a new map\n\n\n### method()\n\nRegisters a custom method or returns the existing one.\n\n```php\npublic static function method( string $method, \\Closure $fcn = null ) : ?\\Closure\n```\n\n* @param **string** `$method` Method name\n* @param **\\Closure\u0026#124;null** `$fcn` Anonymous function or NULL to return the closure if available\n* @return **\\Closure\u0026#124;null** Registered anonymous function or NULL if none has been registered\n\nThe registed method has access to the class properties if called non-static.\n\n**Examples:**\n\n```php\nMap::method( 'foo', function( $arg1, $arg2 ) {\n    return array_merge( $this-\u003eelements, [$arg1, $arg2] );\n} );\n\nMap::method( 'foo' );\n// registered closure\n\nMap::method( 'foo2' );\n// NULL\n\nMap::from( ['bar'] )-\u003efoo( 'foo', 'baz' );\n// ['bar', 'foo', 'baz']\n\n\n\nMap::foo( 'foo', 'baz' );\n// error because `$this-\u003eelements` isn't available\n```\n\nStatic calls can't access `$this-\u003eelements` but can operate on the parameter values:\n\n```php\nMap::method( 'bar', function( $arg1, $arg2 ) {\n    return new static( [$arg1, $arg2] );\n} );\n\nMap::foo( 'foo', 'baz' );\n// ['foo', 'baz']\n```\n\n\n### min()\n\nReturns the minimum value of all elements.\n\n```php\npublic function min( $col = null )\n```\n\n* @param **Closure\u0026#124;string\u0026#124;null** `$col` Closure, key in the nested array or object to check for\n* @return **mixed** Minimum value or NULL if there are no elements in the map\n\nNULL values are removed before the comparison. If there are no values or all\nvalues are NULL, NULL is returned.\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\nBe careful comparing elements of different types because this can have\nunpredictable results due to the [PHP comparison rules](https://www.php.net/manual/en/language.operators.comparison.php)\n\n**Examples:**\n\n```php\nMap::from( [2, 3, 1, 5, 4] )-\u003emin();\n// 1\n\nMap::from( ['baz', 'foo', 'bar'] )-\u003emin();\n// 'bar'\n\nMap::from( [['p' =\u003e 30], ['p' =\u003e 50], ['p' =\u003e 10]] )-\u003emin( 'p' );\n// 10\n\nMap::from( [['i' =\u003e ['p' =\u003e 30]], ['i' =\u003e ['p' =\u003e 50]]] )-\u003emin( 'i/p' );\n// 30\n\nMap::from( [['i' =\u003e ['p' =\u003e 30]], ['i' =\u003e ['p' =\u003e 50]]] )-\u003emin( fn( $val, $key ) =\u003e $val['i']['p'] ?? null )\n// 30\n\nMap::from( [10, 50, 30] )-\u003emin( fn( $val, $key ) =\u003e $key \u003e 0 ? $val : null )\n// 30\n```\n\n**See also:**\n\n* [avg()](#avg) - Returns the average of all integer and float values in the map\n* [count()](#count) - Returns the total number of elements\n* [max()](#max) - Returns the maximum value of all elements\n* [percentage()](#percentage) - Returns the percentage of all elements passing the test\n* [sum()](#sum) - Returns the sum of all values in the map\n\n\n### none()\n\nTests if none of the elements are part of the map.\n\n```php\npublic function none( $element, bool $strict = false ) : bool\n```\n\n* @param **mixed\u0026#124;array** `$element` Element or elements to search for in the map\n* @param **bool** `$strict` TRUE to check the type too, using FALSE '1' and 1 will be the same\n* @return **bool** TRUE if none of the elements is part of the map, FALSE if at least one is\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003enone( 'x' );\n// true\n\nMap::from( ['1', '2'] )-\u003enone( 2, true );\n// true\n\nMap::from( ['a', 'b'] )-\u003enone( 'a' );\n// false\n\nMap::from( ['a', 'b'] )-\u003enone( ['a', 'b'] );\n// false\n\nMap::from( ['a', 'b'] )-\u003enone( ['a', 'x'] );\n// false\n```\n\n**See also:**\n\n* [contains()](#contains) - Tests if an item exists in the map\n* [includes()](#includes) - Tests if element is included\n* [in()](#in) - Tests if element is included\n\n\n### nth()\n\nReturns every nth element from the map.\n\n```php\npublic function nth( int $step, int $offset = 0 ) : self\n```\n\n* @param **int** `$step` Step width\n* @param **int** `$offset` Number of element to start from (0-based)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b', 'c', 'd', 'e', 'f'] )-\u003enth( 2 );\n// ['a', 'c', 'e']\n\nMap::from( ['a', 'b', 'c', 'd', 'e', 'f'] )-\u003enth( 2, 1 );\n// ['b', 'd', 'f']\n```\n\n\n### offsetExists()\n\nDetermines if an element exists at an offset.\n\n```php\npublic function offsetExists( $key )\n```\n\n* @param **int\u0026#124;string** `$key` Key to check for\n* @return **bool** TRUE if key exists, FALSE if not\n\n**Examples:**\n\n```php\n$map = Map::from( ['a' =\u003e 1, 'b' =\u003e 3, 'c' =\u003e null] );\n\nisset( $map['b'] );\n// true\n\nisset( $map['c'] );\n// false\n\nisset( $map['d'] );\n// false\n```\n\n**See also:**\n\n* [offsetGet()](#offsetget) - Returns an element at a given offset\n* [offsetSet()](#offsetset) - Sets the element at a given offset\n* [offsetUnset()](#offsetunset) - Unsets the element at a given offset\n\n\n### offsetGet()\n\nReturns an element at a given offset.\n\n```php\npublic function offsetGet( $key )\n```\n\n* @param **int\u0026#124;string** `$key` Key to return the element for\n* @return **mixed** Value associated to the given key\n\n**Examples:**\n\n```php\n$map = Map::from( ['a' =\u003e 1, 'b' =\u003e 3] );\n\n$map['b'];\n// 3\n```\n\n**See also:**\n\n* [offsetExists()](#offsetexists) - Determines if an element exists at an offset.\n* [offsetSet()](#offsetset) - Sets the element at a given offset\n* [offsetUnset()](#offsetunset) - Unsets the element at a given offset\n\n\n### offsetSet()\n\nSets the element at a given offset.\n\n```php\npublic function offsetSet( $key, $value )\n```\n\n* @param **int\u0026#124;string\u0026#124;null** `$key` Key to set the element for or NULL to append value\n* @param **mixed** `$value` New value set for the key\n\n**Examples:**\n\n```php\n$map = Map::from( ['a' =\u003e 1] );\n\n$map['b'] = 2;\n// ['a' =\u003e 1, 'b' =\u003e 2]\n\n$map[0] = 4;\n// ['a' =\u003e 1, 'b' =\u003e 2, 0 =\u003e 4]\n```\n\n**See also:**\n\n* [offsetExists()](#offsetexists) - Determines if an element exists at an offset.\n* [offsetGet()](#offsetget) - Returns an element at a given offset\n* [offsetUnset()](#offsetunset) - Unsets the element at a given offset\n\n\n### offsetUnset()\n\nUnsets the element at a given offset.\n\n```php\npublic function offsetUnset( $key )\n```\n\n* @param **int\u0026#124;string** `$key` Key for unsetting the item\n\n**Examples:**\n\n```php\n$map = Map::from( ['a' =\u003e 1] );\n\nunset( $map['a'] );\n// []\n```\n\n**See also:**\n\n* [offsetExists()](#offsetexists) - Determines if an element exists at an offset.\n* [offsetGet()](#offsetget) - Returns an element at a given offset\n* [offsetSet()](#offsetset) - Sets the element at a given offset\n\n\n### only()\n\nReturns a new map with only those elements specified by the given keys.\n\n```php\npublic function only( $keys ) : self\n```\n\n* @param **iterable\u0026#60;mixed\u0026#62;\u0026#124;array\u0026#60;mixed\u0026#62;\u0026#124;string\u0026#124;int** `$keys` Keys of the elements that should be returned\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with only the elements specified by the keys\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 0 =\u003e 'b'] )-\u003eonly( 'a' );\n// ['a' =\u003e 1]\n\nMap::from( ['a' =\u003e 1, 0 =\u003e 'b', 1 =\u003e 'c'] )-\u003eonly( [0, 1] );\n// [0 =\u003e 'b', 1 =\u003e 'c']\n```\n\n**See also:**\n\n* [clear()](#clear) - Removes all elements from the current map\n* [except()](#except) - Returns a new map without the passed element keys\n* [reject()](#reject) - Removes all matched elements\n* [remove()](#remove) - Removes an element by key\n\n\n### order()\n\nReturns a new map with elements ordered by the passed keys.\n\n```php\npublic function order( iterable $keys ) : self\n```\n\n* @param **iterable\u0026#60;mixed\u0026#62;** `$keys` Keys of the elements in the required order\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with elements ordered by the passed keys\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 1 =\u003e 'c', 0 =\u003e 'b'] )-\u003eorder( [0, 1, 'a'] );\n// [0 =\u003e 'b', 1 =\u003e 'c', 'a' =\u003e 1]\n\nMap::from( ['a' =\u003e 1, 1 =\u003e 'c', 0 =\u003e 'b'] )-\u003eorder( [0, 1, 2] );\n// [0 =\u003e 'b', 1 =\u003e 'c', 2 =\u003e null]\n\nMap::from( ['a' =\u003e 1, 1 =\u003e 'c', 0 =\u003e 'b'] )-\u003eorder( [0, 1] );\n// [0 =\u003e 'b', 1 =\u003e 'c']\n```\n\n\n### pad()\n\nFill up to the specified length with the given value\n\n```php\npublic function pad( int $size, $value = null ) : self\n```\n\n* @param **int** `$size` Total number of elements that should be in the list\n* @param **mixed** `$value` Value to fill up with if the map length is smaller than the given size\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nIn case the given number is smaller than the number of element that are\nalready in the list, the map is unchanged. If the size is positive, the\nnew elements are padded on the right, if it's negative then the elements\nare padded on the left.\n\nAssociative keys are preserved, numerical keys are replaced and numerical\nkeys are used for the new elements.\n\n**Examples:**\n\n```php\nMap::from( [1, 2, 3] )-\u003epad( 5 );\n// [1, 2, 3, null, null]\n\nMap::from( [1, 2, 3] )-\u003epad( -5 );\n// [null, null, 1, 2, 3]\n\nMap::from( [1, 2, 3] )-\u003epad( 5, '0' );\n// [1, 2, 3, '0', '0']\n\nMap::from( [1, 2, 3] )-\u003epad( 2 );\n// [1, 2, 3]\n\nMap::from( [10 =\u003e 1, 20 =\u003e 2] )-\u003epad( 3 );\n// [0 =\u003e 1, 1 =\u003e 2, 2 =\u003e null]\n\nMap::from( ['a' =\u003e 1, 'b' =\u003e 2] )-\u003epad( 3, 3 );\n// ['a' =\u003e 1, 'b' =\u003e 2, 0 =\u003e 3]\n```\n\n\n### partition()\n\nBreaks the list of elements into the given number of groups.\n\n```php\npublic function partition( $num ) : self\n```\n\n* @param **\\Closure\u0026#124;int** `$number` Function with (value, index) as arguments returning the bucket key or number of groups\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe keys of the original map are preserved in the returned map.\n\n**Examples:**\n\n```php\nMap::from( [1, 2, 3, 4, 5] )-\u003epartition( 3 );\n// [[0 =\u003e 1, 1 =\u003e 2], [2 =\u003e 3, 3 =\u003e 4], [4 =\u003e 5]]\n\nMap::from( [1, 2, 3, 4, 5] )-\u003epartition( function( $val, $idx ) {\n\treturn $idx % 3;\n} );\n// [0 =\u003e [0 =\u003e 1, 3 =\u003e 4], 1 =\u003e [1 =\u003e 2, 4 =\u003e 5], 2 =\u003e [2 =\u003e 3]]\n```\n\n**See also:**\n\n* [chunk()](#chunk) - Chunks the map into arrays with the given number of elements\n\n\n### percentage()\n\nReturns the percentage of all elements passing the test in the map.\n\n```php\npublic function percentage( \\Closure $fcn, int $precision = 2 ) : float\n```\n\n* @param **\\Closure** `$fcn` Closure to filter the values in the nested array or object to compute the percentage\n* @param **int** `$precision` Number of decimal digits use by the result value\n* @return **float** Percentage of all elements passing the test in the map\n\n**Examples:**\n\n```php\nMap::from( [30, 50, 10] )-\u003epercentage( fn( $val, $key ) =\u003e $val \u003c 50 );\n// 66.67\n\nMap::from( [] )-\u003epercentage( fn( $val, $key ) =\u003e true );\n// 0.0\n\nMap::from( [30, 50, 10] )-\u003epercentage( fn( $val, $key ) =\u003e $val \u003e 100 );\n// 0.0\n\nMap::from( [30, 50, 10] )-\u003epercentage( fn( $val, $key ) =\u003e $val \u003e 30, 3 );\n// 33.333\n\nMap::from( [30, 50, 10] )-\u003epercentage( fn( $val, $key ) =\u003e $val \u003e 30, 0 );\n// 33.0\n\nMap::from( [30, 50, 10] )-\u003epercentage( fn( $val, $key ) =\u003e $val \u003c 50, -1 );\n// 70.0\n```\n\n**See also:**\n\n* [avg()](#avg) - Returns the average of all integer and float values in the map\n* [count()](#count) - Returns the total number of elements\n* [max()](#max) - Returns the maximum value of all elements\n* [min()](#min) - Returns the minium value of all elements\n* [sum()](#sum) - Returns the sum of all values in the map\n\n\n### pipe()\n\nPasses the map to the given callback and return the result.\n\n```php\npublic function pipe( \\Closure $callback )\n```\n\n* @param **\\Closure** `$callback` Function with map as parameter which returns arbitrary result\n* @return **mixed** Result returned by the callback\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003epipe( function( $map ) {\n    return strrev( $map-\u003ejoin( '-' ) );\n} );\n// 'b-a'\n```\n\n\n### pluck()\n\nReturns the values of a single column/property from an array of arrays or list of elements in a new map (alias).\n\n```php\npublic function pluck( string $valuecol = null, string $indexcol = null ) : self\n```\n\n* @param **string\u0026#124;null** `$valuecol` Name or path of the value property\n* @param **string\u0026#124;null** `$indexcol` Name or path of the index property\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with mapped entries\n\nThis method is an alias for [col()](#col). For performance reasons, `col()` should\nbe preferred because it uses one method call less than `pluck()`.\n\n**See also:**\n\n* [col()](#col) - Returns the values of a single column/property from an array of arrays or list of elements in a new map\n* [map()](#map) - Applies a callback to each element and returns the results\n* [pluck()](#pluck) - Creates a key/value mapping (alias)\n* [rekey()](#pluck) - Changes the keys according to the passed function\n\n\n### pop()\n\nReturns and removes the last element from the map.\n\n```php\npublic function pop()\n```\n\n* @return **mixed** Last element of the map or null if empty\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003epop();\n// 'b', map contains ['a']\n```\n\n**See also:**\n\n* [push()](#push) - Adds an element onto the end of the map without returning a new map\n\n\n### pos\n\nReturns the numerical index of the value.\n\n```php\npublic function pos( $value ) : ?int\n```\n\n* @param **\\Closure\u0026#124;mixed** `$value` Value to search for or function with (item, key) parameters return TRUE if value is found\n* @return **int\u0026#124;null** Position of the found value (zero based) or NULL if not found\n\n**Examples:**\n\n```php\nMap::from( [4 =\u003e 'a', 8 =\u003e 'b'] )-\u003epos( 'b' );\n// 1\n\nMap::from( [4 =\u003e 'a', 8 =\u003e 'b'] )-\u003epos( function( $item, $key ) {\n    return $item === 'b';\n} );\n// 1\n```\n\nBoth examples will return \"1\" because the value \"b\" is at the second position\nand the returned index is zero based so the first item has the index \"0\".\n\n**See also:**\n\n* [at()](#at) - Returns the value at the given position\n* [index()](#index) - Returns the numerical index of the given key\n\n\n### prefix\n\nAdds a prefix in front of each map entry.\n\n```php\npublic function prefix( $prefix, int $depth = null ) : self\n```\n\n* @param **\\Closure\u0026#124;string** `$prefix` Function with map as parameter which returns arbitrary result\n* @param **int\u0026#124;null** `$depth` Maximum depth to dive into multi-dimensional arrays starting from \"1\"\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nBy default, nested arrays are walked recusively so all entries at all levels are prefixed.\nThe keys of the original map are preserved in the returned map.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003eprefix( '1-' );\n// ['1-a', '1-b']\n\nMap::from( ['a', ['b']] )-\u003eprefix( '1-' );\n// ['1-a', ['1-b']]\n\nMap::from( ['a', ['b']] )-\u003eprefix( '1-', 1 );\n// ['1-a', ['b']]\n\nMap::from( ['a', 'b'] )-\u003eprefix( function( $item, $key ) {\n    return ( ord( $item ) + ord( $key ) ) . '-';\n} );\n// ['145-a', '147-b']\n```\n\n**See also:**\n\n* [suffix()](#suffix) - Adds a suffix at the end of each map entry\n\n\n### prepend()\n\nPushes an element onto the beginning of the map without returning a new map (alias).\n\n```php\npublic function prepend( $value, $key = null ) : self\n```\n\n* @param **mixed** `$value` Item to add at the beginning\n* @param **int\u0026#124;string\u0026#124;null** `$key` Key for the item or NULL to reindex all numerical keys\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThis method is an alias for the [unshift()](#unshift) method. For performance reasons, `unshift()` should\nbe preferred because it uses one method call less than `prepend()`.\n\n**See also:**\n\n* [unshift()](#unshift) - Underlying method with same parameters and return value but better performance\n\n\n### pull()\n\nReturns and removes an element from the map by its key.\n\n```php\npublic function pull( $key, $default = null )\n```\n\n* @param **int\u0026#124;string** `$key` Key to retrieve the value for\n* @param **mixed** `$default` Default value if key isn't available\n* @return **mixed** Value from map or default value\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b', 'c'] )-\u003epull( 1 );\n// 'b', map contains ['a', 'c']\n\nMap::from( ['a', 'b', 'c'] )-\u003epull( 'x', 'none' );\n// 'none', map contains ['a', 'b', 'c']\n```\n\n**See also:**\n\n* [get()](#get) - Returns an element from the map by key\n\n\n### push()\n\nAdds an element onto the end of the map without returning a new map.\n\n```php\npublic function push( $value ) : self\n```\n\n* @param **mixed** `$value` Value to add to the end\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003epush( 'aa' );\n// ['a', 'b', 'aa']\n```\n\n**See also:**\n\n* [pop()](#pop) - Returns and removes the last element from the map\n\n\n### put()\n\nSets the given key and value in the map without returning a new map (alias).\n\n```php\npublic function put( $key, $value ) : self\n```\n\n* @param **int\u0026#124;string** `$key` Key to set the new value for\n* @param **mixed** `$value` New element that should be set\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThis method is an alias for [set()](#set). For performance reasons, `set()` should be\npreferred because it uses one method call less than `put()`.\n\n**See also:**\n\n* [set()](#set) - Underlying method with same parameters and return value but better performance\n\n\n### random()\n\nReturns one or more random element from the map.\n\n```php\npublic function random( int $max = 1 ) : self\n```\n\n* @param **int** `$max` Maximum number of elements that should be returned\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with key/element pairs from original map in random order\n* @throws **\\InvalidArgumentException** If requested number of elements is less than 1\n\nThe less elements are in the map, the less random the order will be, especially\nif the maximum number of values is high or close to the number of elements.\n\nThe keys of the original map are preserved in the returned map.\n\n**Examples:**\n\n```php\nMap::from( [2, 4, 8, 16] )-\u003erandom();\n// [2 =\u003e 8] or any other key/value pair\n\nMap::from( [2, 4, 8, 16] )-\u003erandom( 2 );\n// [3 =\u003e 16, 0 =\u003e 2] or any other key/value pair\n\nMap::from( [2, 4, 8, 16] )-\u003erandom( 5 );\n// [0 =\u003e 2,  1 =\u003e 4, 2 =\u003e 8, 3 =\u003e 16] in random order\n```\n\n\n### reduce()\n\nIteratively reduces the array to a single value using a callback function.\n\n```php\npublic function reduce( callable $callback, $initial = null )\n```\n\n* @param **callable** `$callback` Function with (result, value) parameters and returns result\n* @param **mixed** `$initial` Initial value when computing the result\n* @return **mixed** Value computed by the callback function\n\nAfterwards, the map will be empty.\n\n**Examples:**\n\n```php\nMap::from( [2, 8] )-\u003ereduce( function( $result, $value ) {\n    return $result += $value;\n}, 10 );\n// 20 because 10 + 2 + 8 and map equals []\n```\n\n\n### reject()\n\nRemoves all matched elements and returns a new map.\n\n```php\npublic function reject( $callback = true ) : self\n```\n\n* @param **Closure\u0026#124;mixed** `$callback` Function with (item) parameter which returns TRUE/FALSE or value to compare with\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThis method is the inverse of the [filter()](#filter) and should return TRUE\nif the item should be removed from the returned map.\n\nIf no callback is passed, all values which are NOT empty, null or false will be\nremoved. The keys of the original map are preserved in the returned map.\n\n**Examples:**\n\n```php\nMap::from( [2 =\u003e 'a', 6 =\u003e 'b', 13 =\u003e 'm', 30 =\u003e 'z'] )-\u003ereject( function( $value, $key ) {\n    return $value \u003c 'm';\n} );\n// [13 =\u003e 'm', 30 =\u003e 'z']\n\nMap::from( [2 =\u003e 'a', 13 =\u003e 'm', 30 =\u003e 'z'] )-\u003ereject( 'm' );\n// [2 =\u003e 'a', 30 =\u003e 'z']\n\nMap::from( [2 =\u003e 'a', 6 =\u003e null, 13 =\u003e 'm'] )-\u003ereject();\n// [6 =\u003e null]\n```\n\n**See also:**\n\n* [clear()](#clear) - Removes all elements from the current map\n* [duplicates()](#duplicates) - Returns the duplicate values from the map\n* [except()](#except) - Returns a new map without the passed element keys\n* [only()](#only) - Returns only those elements specified by the keys\n* [remove()](#remove) - Removes an element by key\n\n\n### rekey()\n\nChanges the keys according to the passed function.\n\n```php\npublic function rekey( callable $callback ) : self\n```\n\n* @param **callable** `$callback` Function with (value, key) parameters and returns new key\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with new keys and original values\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 2, 'b' =\u003e 4] )-\u003erekey( function( $value, $key ) {\n    return 'key-' . $key;\n} );\n// ['key-a' =\u003e 2, 'key-b' =\u003e 4]\n```\n\n**See also:**\n\n* [map()](#map) - Maps new values to the existing keys using the passed function and returns a new map for the result\n* [transform()](#transform) - Creates new key/value pairs using the passed function and returns a new map for the result\n\n### remove()\n\nRemoves one or more elements from the map by its keys without returning a new map.\n\n```php\npublic function remove( $keys ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string\u0026#62;\u0026#124;array\u0026#60;int\u0026#124;string\u0026#62;\u0026#124;string\u0026#124;int** `$keys` List of keys\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 2 =\u003e 'b'] )-\u003eremove( 'a' );\n// [2 =\u003e 'b']\n\nMap::from( ['a' =\u003e 1, 2 =\u003e 'b'] )-\u003eremove( [2, 'a'] );\n// []\n```\n\n**See also:**\n\n* [clear()](#clear) - Removes all elements from the current map\n* [except()](#except) - Returns a new map without the passed element keys\n* [only()](#only) - Returns only those elements specified by the keys\n* [reject()](#reject) - Removes all matched elements\n\n\n### replace()\n\nReplaces elements in the map with the given elements without returning a new map.\n\n```php\npublic function replace( iterable $elements, bool $recursive = true ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements\n* @param **bool** `$recursive` TRUE to replace recursively (default), FALSE to replace elements only\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe method is similar to [merge()](#merge) but also replaces elements with numeric keys.\nThese would be added by `merge()` with a new numeric key.\n\nThe keys are preserved in the returned map.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 2 =\u003e 'b'] )-\u003ereplace( ['a' =\u003e 2] );\n// ['a' =\u003e 2, 2 =\u003e 'b']\n\nMap::from( ['a' =\u003e 1, 'b' =\u003e ['c' =\u003e 3, 'd' =\u003e 4]] )-\u003ereplace( ['b' =\u003e ['c' =\u003e 9]] );\n// ['a' =\u003e 1, 'b' =\u003e ['c' =\u003e 9, 'd' =\u003e 4]]\n```\n\n\n### reverse()\n\nReverses the element order without returning a new map.\n\n```php\npublic function reverse() : self\n```\n\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003ereverse();\n// ['b', 'a']\n\nMap::from( ['name' =\u003e 'test', 'last' =\u003e 'user'] )-\u003ereverse();\n// ['last' =\u003e 'user', 'name' =\u003e 'test']\n```\n\n**See also:**\n\n* [reversed()](#reversed) - Reverses the element order in a copy of the map\n\n\n### reversed()\n\nReverses the element order in a copy of the map.\n\n```php\npublic function reversed() : self\n```\n\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with a reversed copy of the elements\n\nThe keys are preserved using this method and a new map is created before reversing the elements.\nThus, [reverse()](#reverse) should be preferred for performance reasons if possible.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003ereversed();\n// ['b', 'a']\n\nMap::from( ['name' =\u003e 'test', 'last' =\u003e 'user'] )-\u003ereversed();\n// ['last' =\u003e 'user', 'name' =\u003e 'test']\n```\n\n**See also:**\n\n* [reverse()](#reverse) - Reverses the element order without returning a new map\n\n\n### rsort()\n\nSorts all elements in reverse order without maintaining the key association.\n\n```php\npublic function rsort( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `rsort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe parameter modifies how the values are compared. Possible parameter values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\nThe keys are NOT preserved and elements get a new index. No new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003ersort();\n// [0 =\u003e 1, 1 =\u003e 0]\n\nMap::from( [0 =\u003e 'b', 1 =\u003e 'a'] )-\u003ersort();\n// [0 =\u003e 'b', 1 =\u003e 'a']\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003ersort();\n// [0 =\u003e 'b', 1 =\u003e 'C']\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003ersort( SORT_STRING|SORT_FLAG_CASE );\n// [0 =\u003e 'C', 1 =\u003e 'b'] because 'C' -\u003e 'c' and 'c' \u003e 'b'\n```\n\n**See also:**\n\n* [rsorted()](#rsorted) - Sorts a copy of all elements in reverse order without maintaining the key association\n\n\n### rsorted()\n\nSorts a copy of all elements in reverse order without maintaining the key association.\n\n```php\npublic function rsorted( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for `rsort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe parameter modifies how the values are compared. Possible parameter values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\nThe keys are NOT preserved, elements get a new index and a new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003ersorted();\n// [0 =\u003e 1, 1 =\u003e 0]\n\nMap::from( [0 =\u003e 'b', 1 =\u003e 'a'] )-\u003ersorted();\n// [0 =\u003e 'b', 1 =\u003e 'a']\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003ersorted();\n// [0 =\u003e 'b', 1 =\u003e 'C']\n\nMap::from( [0 =\u003e 'C', 1 =\u003e 'b'] )-\u003ersorted( SORT_STRING|SORT_FLAG_CASE );\n// [0 =\u003e 'C', 1 =\u003e 'b'] because 'C' -\u003e 'c' and 'c' \u003e 'b'\n```\n\n**See also:**\n\n* [rsort()](#rsort) - Sorts all elements in reverse order without maintaining the key association\n\n\n### rtrim()\n\nRemoves the passed characters from the right of all strings.\n\n```php\npublic function rtrim( string $chars = \" \\n\\r\\t\\v\\x00\" ) : self\n```\n\n* @param **string** `$chars` List of characters to trim\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( [\" abc\\n\", \"\\tcde\\r\\n\"] )-\u003ertrim();\n// [\" abc\", \"\\tcde\"]\n\nMap::from( [\"a b c\", \"cbxa\"] )-\u003ertrim( 'abc' );\n// [\"a b \", \"cbx\"]\n```\n\n**See also:**\n\n* [ltrim()](#ltrim) - Removes the passed characters from the left of all strings\n* [trim()](#trim) - Removes the passed characters from the left/right of all strings\n\n\n### search()\n\nSearches the map for a given value and return the corresponding key if successful.\n\n```php\npublic function search( $value, $strict = true )\n```\n\n* @param **mixed** `$value` Item to search for\n* @param **bool** `$strict` TRUE if type of the element should be checked too\n* @return **int\u0026#124;string\u0026#124;null** Key associated to the value or null if not found\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b', 'c'] )-\u003esearch( 'b' );\n// 1\n\nMap::from( [1, 2, 3] )-\u003esearch( '2', true );\n// null because the types doesn't match (int vs. string)\n```\n\n\n### sep()\n\nSets the seperator for paths to values in multi-dimensional arrays or objects.\n\n```php\npublic static function sep( string $char ) : self\n```\n\n* @param **string** `$char` Separator character, e.g. \".\" for \"key.to.value\" instead of \"key/to/value\"\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Same map for fluid interface\n\nThis method only changes the separator for the current map instance. To\nchange the separator for all maps created afterwards, use the static\n[Map::delimiter()](#delimiter) method instead.\n\n**Examples:**\n\n```php\nMap::from( ['foo' =\u003e ['bar' =\u003e 'baz']] )-\u003esep( '.' )-\u003eget( 'foo.bar' );\n// 'baz'\n```\n\n**See also:**\n\n* [delimiter()](#delimiter) - Sets or returns the seperator for paths to values in multi-dimensional arrays or objects\n\n\n### set()\n\nSets an element in the map by key without returning a new map.\n\n```php\npublic function set( $key, $value ) : self\n```\n\n* @param **int\u0026#124;string** `$key` Key to set the new value for\n* @param **mixed** `$value` New element that should be set\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( ['a'] )-\u003eset( 1, 'b' );\n// [0 =\u003e 'a', 1 =\u003e 'b']\n\nMap::from( ['a'] )-\u003eset( 0, 'b' );\n// [0 =\u003e 'b']\n```\n\n**See also:**\n\n* [get()](#get) - Returns an element from the map by key\n* [with()](#with) - Returns a copy of the map with the element at the given index replaced with the given value\n\n\n### shift()\n\nReturns and removes the first element from the map.\n\n```php\npublic function shift()\n```\n\n* @return **mixed\u0026#124;null** Value from map or null if not found\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003eshift();\n// 'a'\n\nMap::from( [] )-\u003eshift();\n// null\n```\n\n**Performance note:**\n\nThe bigger the list, the higher the performance impact because `shift()`\nreindexes all existing elements. Usually, it's better to [reverse()](#reverse)\nthe list and [pop()](#pop) entries from the list afterwards if a significant\nnumber of elements should be removed from the list:\n\n```php\n$map-\u003ereverse()-\u003epop();\n```\n\ninstead of\n\n```php\n$map-\u003eshift();\n```\n\n**See also:**\n\n* [unshift()](#unshift) - Pushes an element onto the beginning of the map without returning a new map\n\n\n### shuffle()\n\nShuffles the elements in the map without returning a new map.\n\n```php\npublic function shuffle( bool $assoc = false ) : self\n```\n\n* @param **bool** `$assoc` True to preserve keys, false to assign new keys\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( [2 =\u003e 'a', 4 =\u003e 'b'] )-\u003eshuffle();\n// ['a', 'b'] in random order with new keys\n\nMap::from( [2 =\u003e 'a', 4 =\u003e 'b'] )-\u003eshuffle( true );\n// [2 =\u003e 'a', 4 =\u003e 'b'] in random order with keys preserved\n```\n\n**See also:**\n\n* [shuffled()](#shuffled) - Shuffles the elements in a copy of the map.\n\n\n### shuffled()\n\nShuffles the elements in a copy of the map.\n\n```php\npublic function shuffled( bool $assoc = false ) : self\n```\n\n* @param **bool** `$assoc` True to preserve keys, false to assign new keys\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with a shuffled copy of the elements\n\n**Examples:**\n\n```php\nMap::from( [2 =\u003e 'a', 4 =\u003e 'b'] )-\u003eshuffled();\n// ['a', 'b'] in random order with new keys\n\nMap::from( [2 =\u003e 'a', 4 =\u003e 'b'] )-\u003eshuffled( true );\n// [2 =\u003e 'a', 4 =\u003e 'b'] in random order with keys preserved\n```\n\n**See also:**\n\n* [shuffle()](#shuffle) - Shuffles the elements in the map without returning a new map\n\n\n### skip()\n\nReturns a new map with the given number of items skipped.\n\n```php\npublic function skip( $offset ) : self\n```\n\n* @param **\\Closure\u0026#124;int** `$offset` Number of items to skip or function($item, $key) returning true for skipped items\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe keys of the items returned in the new map are the same as in the original one.\n\n**Examples:**\n\n```php\nMap::from( [1, 2, 3, 4] )-\u003eskip( 2 );\n// [2 =\u003e 3, 3 =\u003e 4]\n\nMap::from( [1, 2, 3, 4] )-\u003eskip( function( $item, $key ) {\n    return $item \u003c 4;\n} );\n// [3 =\u003e 4]\n```\n\n\n### slice()\n\nReturns a map with the slice from the original map.\n\n```php\npublic function slice( int $offset, int $length = null ) : self\n```\n\n* @param **int** `$offset` Number of elements to start from\n* @param **int\u0026#124;null** `$length` Number of elements to return or NULL for no limit\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe rules for offsets are:\n- If offset is non-negative, the sequence will start at that offset\n- If offset is negative, the sequence will start that far from the end\n\nSimilar for the length:\n- If length is given and is positive, then the sequence will have up to that many elements in it\n- If the array is shorter than the length, then only the available array elements will be present\n- If length is given and is negative then the sequence will stop that many elements from the end\n- If it is omitted, then the sequence will have everything from offset up until the end\n\nThe keys of the items returned in the new map are the same as in the original one.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b', 'c'] )-\u003eslice( 1 );\n// ['b', 'c']\n\nMap::from( ['a', 'b', 'c'] )-\u003eslice( 1, 1 );\n// ['b']\n\nMap::from( ['a', 'b', 'c', 'd'] )-\u003eslice( -2, -1 );\n// ['c']\n```\n\n**See also:**\n\n* [take()](#take) - Returns a new map with the given number of items.\n\n\n### some()\n\nTests if at least one element passes the test or is part of the map.\n\n```php\npublic function some( $values, bool $strict = false ) : bool\n```\n\n* @param **\\Closure\u0026#124;iterable\u0026#124;mixed** `$values` Anonymous function with (item, key) parameter, element or list of elements to test against\n* @param **bool** `$strict` TRUE to check the type too, using FALSE '1' and 1 will be the same\n* @return **bool** TRUE if at least one element is available in map, FALSE if the map contains none of them\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003esome( 'a' );\n// true\n\nMap::from( ['a', 'b'] )-\u003esome( ['a', 'c'] );\n// true\n\nMap::from( ['a', 'b'] )-\u003esome( function( $item, $key ) {\n    return $item === 'a'\n} );\n// true\n\nMap::from( ['a', 'b'] )-\u003esome( ['c', 'd'] );\n// false\n\nMap::from( ['1', '2'] )-\u003esome( [2], true );\n// false\n```\n\n**See also:**\n\n* [every()](#every) - Verifies that all elements pass the test of the given callback\n* [any()](#any) - Tests if at least one element satisfies the callback function\n\n\n### sort()\n\nSorts all elements without maintaining the key association.\n\n```php\npublic function sort( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for PHP `sort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe parameter modifies how the values are compared. Possible parameter values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\nThe keys are NOT preserved and elements get a new index. No new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003esort();\n// [0 =\u003e 0, 1 =\u003e 1]\n\nMap::from( [0 =\u003e 'b', 1 =\u003e 'a'] )-\u003esort();\n// [0 =\u003e 'a', 1 =\u003e 'b']\n```\n\n**See also:**\n\n* [sorted()](#sorted) - Sorts a copy of the elements using new keys\n\n\n### sorted()\n\nSorts a copy of the elements using new keys.\n\n```php\npublic function sorted( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for PHP `sort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe parameter modifies how the values are compared. Possible parameter values are:\n- SORT_REGULAR : compare elements normally (don't change types)\n- SORT_NUMERIC : compare elements numerically\n- SORT_STRING : compare elements as strings\n- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()`\n- SORT_NATURAL : compare elements as strings using \"natural ordering\" like `natsort()`\n- SORT_FLAG_CASE : use SORT_STRING\u0026#124;SORT_FLAG_CASE and SORT_NATURAL\u0026#124;SORT_FLAG_CASE to sort strings case-insensitively\n\nThe keys aren't preserved and elements get a new index and a new map is created\nbefore sorting the elements. Thus, [sort()](#sort) should be preferred for\nperformance reasons if possible. A new map is created by calling this method.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 0] )-\u003esorted();\n// [0 =\u003e 0, 1 =\u003e 1]\n\nMap::from( [0 =\u003e 'b', 1 =\u003e 'a'] )-\u003esorted();\n// [0 =\u003e 'a', 1 =\u003e 'b']\n```\n\n**See also:**\n\n* [sort()](#sort) - Sorts all elements without maintaining the key association\n\n\n### splice()\n\nRemoves a portion of the map and replace it with the given replacement, then return the updated map.\n\n```php\npublic function splice( int $offset, int $length = null, $replacement = [] ) : self\n```\n\n* @param **int** `$offset` Number of elements to start from\n* @param **int\u0026#124;null** `$length` Number of elements to remove, NULL for all\n* @param **mixed** `$replacement` List of elements to insert\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe rules for offsets are:\n- If offset is non-negative, the sequence will start at that offset\n- If offset is negative, the sequence will start that far from the end\n\nSimilar for the length:\n- If length is given and is positive, then the sequence will have up to that many elements in it\n- If the array is shorter than the length, then only the available array elements will be present\n- If length is given and is negative then the sequence will stop that many elements from the end\n- If it is omitted, then the sequence will have everything from offset up until the end\n\nNumerical array indexes are NOT preserved.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b', 'c'] )-\u003esplice( 1 );\n// ['b', 'c'] and map contains ['a']\n\nMap::from( ['a', 'b', 'c'] )-\u003esplice( 1, 1, ['x', 'y'] );\n// ['b'] and map contains ['a', 'x', 'y', 'c']\n```\n\n\n### strAfter()\n\nReturns the strings after the passed value.\n\n```php\npublic function strAfter( string $value, bool $case = false, string $encoding = 'UTF-8' ) : self\n```\n\n* @param **string** `$value` Character or string to search for\n* @param **bool** `$case` TRUE if search should be case insensitive, FALSE if case-sensitive\n* @param **string** `$encoding` Character encoding of the strings, e.g. \"UTF-8\" (default), \"ASCII\", \"ISO-8859-1\", etc.\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nAll scalar values (bool, int, float, string) will be converted to strings.\nNon-scalar values as well as empty strings will be skipped and are not part of the result.\n\n**Examples:**\n\n```php\nMap::from( ['äöüß'] )-\u003estrAfter( 'ö' );\n// ['üß']\n\nMap::from( ['abc'] )-\u003estrAfter( '' );\n// ['abc']\n\nMap::from( ['abc'] )-\u003estrAfter( 'b' );\n// ['c']\n\nMap::from( ['abc'] )-\u003estrAfter( 'c' );\n// ['']\n\nMap::from( ['abc'] )-\u003estrAfter( 'x' )\n// []\n\nMap::from( [''] )-\u003estrAfter( '' );\n// []\n\nMap::from( [1, 1.0, true, ['x'], new \\stdClass] )-\u003estrAfter( '' );\n// ['1', '1', '1']\n\nMap::from( [0, 0.0, false, []] )-\u003estrAfter( '' );\n// ['0', '0']\n```\n\n**See also:**\n\n* [strBefore()](#strbefore) - Returns the strings before the passed value\n\n\n### strBefore()\n\nReturns the strings before the passed value.\n\n```php\npublic function strBefore( string $value, bool $case = false, string $encoding = 'UTF-8' ) : self\n```\n\n* @param **string** `$value` Character or string to search for\n* @param **bool** `$case` TRUE if search should be case insensitive, FALSE if case-sensitive\n* @param **string** `$encoding` Character encoding of the strings, e.g. \"UTF-8\" (default), \"ASCII\", \"ISO-8859-1\", etc.\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nAll scalar values (bool, int, float, string) will be converted to strings.\nNon-scalar values as well as empty strings will be skipped and are not part of the result.\n\n**Examples:**\n\n```php\nMap::from( ['äöüß'] )-\u003estrBefore( 'ü' );\n// ['äö']\n\nMap::from( ['abc'] )-\u003estrBefore( '' );\n// ['abc']\n\nMap::from( ['abc'] )-\u003estrBefore( 'b' );\n// ['a']\n\nMap::from( ['abc'] )-\u003estrBefore( 'a' );\n// ['']\n\nMap::from( ['abc'] )-\u003estrBefore( 'x' )\n// []\n\nMap::from( [''] )-\u003estrBefore( '' );\n// []\n\nMap::from( [1, 1.0, true, ['x'], new \\stdClass] )-\u003estrBefore( '' );\n// ['1', '1', '1']\n\nMap::from( [0, 0.0, false, []] )-\u003estrBefore( '' );\n// ['0', '0']\n```\n\n**See also:**\n\n* [strAfter()](#strafter) - Returns the strings after the passed value\n\n\n### strCompare()\n\nCompares the value against all map elements.\n\n```php\npublic function strCompare( string $value, bool $case = true ) : bool\n```\n\n* @param **string** `$value` Value to compare map elements to\n* @param **bool** `$case` TRUE if comparison is case sensitive, FALSE to ignore upper/lower case\n* @return **bool** TRUE If at least one element matches, FALSE if value is not in map\n\nAll scalar values (bool, float, int and string) are casted to string values before\ncomparing to the given value. Non-scalar values in the map are ignored.\n\n**Examples:**\n\n```php\nMap::from( ['foo', 'bar'] )-\u003estrCompare( 'foo' );\n// true\n\nMap::from( ['foo', 'bar'] )-\u003estrCompare( 'Foo', false );\n// true (case insensitive)\n\nMap::from( [123, 12.3] )-\u003estrCompare( '12.3' );\n// true\n\nMap::from( [false, true] )-\u003estrCompare( '1' );\n// true\n\nMap::from( ['foo', 'bar'] )-\u003estrCompare( 'Foo' );\n// false (case sensitive)\n\nMap::from( ['foo', 'bar'] )-\u003estrCompare( 'baz' );\n// false\n\nMap::from( [new \\stdClass(), 'bar'] )-\u003estrCompare( 'foo' );\n// false\n```\n\n**See also:**\n\n* [contains()](#contains) - Tests if an item exists in the map\n* [in()](#in) - Tests if element is included\n* [includes()](#includes) - Tests if element is included\n\n\n### strContains()\n\nTests if at least one of the passed strings is part of at least one entry.\n\n```php\npublic function strContains( $value, string $encoding = 'UTF-8' ) : bool\n```\n\n* @param **array\u0026#124;string** `$value` The string or list of strings to search for in each entry\n* @param **string** `$encoding` Character encoding of the strings, e.g. \"UTF-8\" (default), \"ASCII\", \"ISO-8859-1\", etc.\n* @return **bool** TRUE if one of the entries contains one of the strings, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( ['abc'] )-\u003estrContains( '' );\n// true\n\nMap::from( ['abc'] )-\u003estrContains( 'a' );\n// true\n\nMap::from( ['abc'] )-\u003estrContains( 'bc' );\n// true\n\nMap::from( [12345] )-\u003estrContains( '23' );\n// true\n\nMap::from( [123.4] )-\u003estrContains( 23.4 );\n// true\n\nMap::from( [12345] )-\u003estrContains( false );\n// true ('12345' contains '')\n\nMap::from( [12345] )-\u003estrContains( true );\n// true ('12345' contains '1')\n\nMap::from( [false] )-\u003estrContains( false );\n// true  ('' contains '')\n\nMap::from( [''] )-\u003estrContains( false );\n// true ('' contains '')\n\nMap::from( ['abc'] )-\u003estrContains( ['b', 'd'] );\n// true\n\nMap::from( ['abc'] )-\u003estrContains( 'c', 'ASCII' );\n// true\n\nMap::from( ['abc'] )-\u003estrContains( 'd' );\n// false\n\nMap::from( ['abc'] )-\u003estrContains( 'cb' );\n// false\n\nMap::from( [23456] )-\u003estrContains( true );\n// false ('23456' doesn't contain '1')\n\nMap::from( [false] )-\u003estrContains( 0 );\n// false ('' doesn't contain '0')\n\nMap::from( ['abc'] )-\u003estrContains( ['d', 'e'] );\n// false\n\nMap::from( ['abc'] )-\u003estrContains( 'cb', 'ASCII' );\n// false\n```\n\n**See also:**\n\n* [strContainsAll()](#strcontainsall) - Tests if all of the entries contains one of the passed strings\n\n\n### strContainsAll()\n\nTests if all of the entries contains one of the passed strings.\n\n```php\npublic function strContainsAll( $value, string $encoding = 'UTF-8' ) : bool\n```\n\n* @param **array\u0026#124;string** `$value` The string or list of strings to search for in each entry\n* @param **string** `$encoding` Character encoding of the strings, e.g. \"UTF-8\" (default), \"ASCII\", \"ISO-8859-1\", etc.\n* @return **bool** TRUE if all of the entries contains at least one of the strings, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( ['abc', 'def'] )-\u003estrContainsAll( '' );\n// true\n\nMap::from( ['abc', 'cba'] )-\u003estrContainsAll( 'a' );\n// true\n\nMap::from( ['abc', 'bca'] )-\u003estrContainsAll( 'bc' );\n// true\n\nMap::from( [12345, '230'] )-\u003estrContainsAll( '23' );\n// true\n\nMap::from( [123.4, 23.42] )-\u003estrContainsAll( 23.4 );\n// true\n\nMap::from( [12345, '234'] )-\u003estrContainsAll( [true, false] );\n// true ('12345' contains '1' and '234' contains '')\n\nMap::from( ['', false] )-\u003estrContainsAll( false );\n// true ('' contains '')\n\nMap::from( ['abc', 'def'] )-\u003estrContainsAll( ['b', 'd'] );\n// true\n\nMap::from( ['abc', 'ecf'] )-\u003estrContainsAll( 'c', 'ASCII' );\n// true\n\nMap::from( ['abc', 'def'] )-\u003estrContainsAll( 'd' );\n// false\n\nMap::from( ['abc', 'cab'] )-\u003estrContainsAll( 'cb' );\n// false\n\nMap::from( [23456, '123'] )-\u003estrContains( true );\n// false ('23456' doesn't contain '1')\n\nMap::from( [false, '000'] )-\u003estrContains( 0 );\n// false ('' doesn't contain '0')\n\nMap::from( ['abc', 'acf'] )-\u003estrContainsAll( ['d', 'e'] );\n// false\n\nMap::from( ['abc', 'bca'] )-\u003estrContainsAll( 'cb', 'ASCII' );\n// false\n```\n\n**See also:**\n\n* [strContains()](#strcontains) - Tests if at least one of the passed strings is part of at least one entry\n\n\n### strEnds()\n\nTests if at least one of the entries ends with one of the passed strings.\n\n```php\npublic function strEnds( $value, string $encoding = 'UTF-8' ) : bool\n```\n\n* @param **array\u0026#124;string** `$value` The string or list of strings to search for in each entry\n* @param **string** `$encoding` Character encoding of the strings, e.g. \"UTF-8\" (default), \"ASCII\", \"ISO-8859-1\", etc.\n* @return **bool** TRUE if one of the entries ends with the string, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( ['abc'] )-\u003estrEnds( '' );\n// true\n\nMap::from( ['abc'] )-\u003estrEnds( 'c' );\n// true\n\nMap::from( ['abc'] )-\u003estrEnds( 'bc' );\n// true\n\nMap::from( ['abc'] )-\u003estrEnds( ['b', 'c'] );\n// true\n\nMap::from( ['abc'] )-\u003estrEnds( 'c', 'ASCII' );\n// true\n\nMap::from( ['abc'] )-\u003estrEnds( 'a' );\n// false\n\nMap::from( ['abc'] )-\u003estrEnds( 'cb' );\n// false\n\nMap::from( ['abc'] )-\u003estrEnds( ['d', 'b'] );\n// false\n\nMap::from( ['abc'] )-\u003estrEnds( 'cb', 'ASCII' );\n// false\n```\n\n**See also:**\n\n* [strEndsAll()](#strendsall) - Tests if all of the entries ends with at least one of the passed strings\n\n\n### strEndsAll()\n\nTests if all of the entries ends with at least one of the passed strings.\n\n```php\npublic function strEndsAll( $value, string $encoding = 'UTF-8' ) : bool\n```\n\n* @param **array\u0026#124;string** `$value` The string or list of strings to search for in each entry\n* @param **string** `$encoding` Character encoding of the strings, e.g. \"UTF-8\" (default), \"ASCII\", \"ISO-8859-1\", etc.\n* @return **bool** TRUE if all of the entries ends with at least one of the strings, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( ['abc', 'def'] )-\u003estrEndsAll( '' );\n// true\n\nMap::from( ['abc', 'bac'] )-\u003estrEndsAll( 'c' );\n// true\n\nMap::from( ['abc', 'cbc'] )-\u003estrEndsAll( 'bc' );\n// true\n\nMap::from( ['abc', 'def'] )-\u003estrEndsAll( ['c', 'f'] );\n// true\n\nMap::from( ['abc', 'efc'] )-\u003estrEndsAll( 'c', 'ASCII' );\n// true\n\nMap::from( ['abc', 'fed'] )-\u003estrEndsAll( 'd' );\n// false\n\nMap::from( ['abc', 'bca'] )-\u003estrEndsAll( 'ca' );\n// false\n\nMap::from( ['abc', 'acf'] )-\u003estrEndsAll( ['a', 'c'] );\n// false\n\nMap::from( ['abc', 'bca'] )-\u003estrEndsAll( 'ca', 'ASCII' );\n// false\n```\n\n**See also:**\n\n* [strEnds()](#strends) - Tests if at least one of the entries ends with one of the passed strings\n\n\n### string()\n\nReturns an element by key and casts it to string if possible.\n\n```php\npublic function string( $key, $default = '' ) : string\n```\n\n* @param **int\u0026#124;string** `$key` Key or path to the requested item\n* @param **mixed** `$default` Default value if key isn't found (will be casted to string)\n* @return **string** Value from map or default value\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e true] )-\u003estring( 'a' );\n// '1'\n\nMap::from( ['a' =\u003e 1] )-\u003estring( 'a' );\n// '1'\n\nMap::from( ['a' =\u003e 1.1] )-\u003estring( 'a' );\n// '1.1'\n\nMap::from( ['a' =\u003e 'abc'] )-\u003estring( 'a' );\n// 'abc'\n\nMap::from( ['a' =\u003e ['b' =\u003e ['c' =\u003e 'yes']]] )-\u003estring( 'a/b/c' );\n// 'yes'\n\nMap::from( [] )-\u003estring( 'c', function() { return 'no'; } );\n// 'no'\n\nMap::from( [] )-\u003estring( 'b' );\n// ''\n\nMap::from( ['b' =\u003e ''] )-\u003estring( 'b' );\n// ''\n\nMap::from( ['b' =\u003e null] )-\u003estring( 'b' );\n// ''\n\nMap::from( ['b' =\u003e [true]] )-\u003estring( 'b' );\n// ''\n\nMap::from( ['b' =\u003e '#resource'] )-\u003estring( 'b' );\n// '' (resources are not scalar)\n\nMap::from( ['b' =\u003e new \\stdClass] )-\u003estring( 'b' );\n// '' (objects are not scalar)\n\nMap::from( [] )-\u003estring( 'c', new \\Exception( 'error' ) );\n// throws exception\n```\n\n**See also:**\n\n* [bool()](#bool) - Returns an element by key and casts it to boolean if possible\n* [cast()](#cast) - Casts all entries to the passed type\n* [get()](#get) - Returns an element from the map by key\n* [float()](#float) - Returns an element by key and casts it to float if possible\n* [int()](#int) - Returns an element by key and casts it to integer if possible\n\n\n### strLower()\n\nConverts all alphabetic characters in strings to lower case.\n\n```php\npublic function strLower( string $encoding = 'UTF-8' ) : self\n```\n\n* @param **string** `$encoding` Character encoding of the strings, e.g. \"UTF-8\" (default), \"ASCII\", \"ISO-8859-1\", etc.\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( ['My String'] )-\u003estrLower();\n// [\"my string\"]\n\nMap::from( ['Τάχιστη'] )-\u003estrLower();\n// [\"τάχιστη\"]\n\nMap::from( ['Äpfel', 'Birnen'] )-\u003estrLower( 'ISO-8859-1' );\n// [\"äpfel\", \"birnen\"]\n```\n\n**See also:**\n\n* [strUpper()](#strupper) - Converts all alphabetic characters in strings to upper case\n\n\n### strReplace()\n\nReplaces all occurrences of the search string with the replacement string.\n\n```php\npublic function strReplace( $search, $replace, bool $case = false ) : self\n```\n\n* @param **array\u0026#124;string** `$search` String or list of strings to search for\n* @param **array\u0026#124;string** `$replace` String or list of strings of replacement strings\n* @param **bool** `$case` TRUE if replacements should be case insensitive, FALSE if case-sensitive\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nIf you use an array of strings for search or search/replacement, the order of\nthe strings matters! Each search string found is replaced by the corresponding\nreplacement string at the same position.\n\nIn case of array parameters and if the number of replacement strings is less\nthan the number of search strings, the search strings with no corresponding\nreplacement string are replaced with empty strings. Replacement strings with\nno corresponding search string are ignored.\n\nAn array parameter for the replacements is only allowed if the search parameter\nis an array of strings too!\n\nBecause the method replaces from left to right, it might replace a previously\ninserted value when doing multiple replacements. Entries which are non-string\nvalues are left untouched.\n\n**Examples:**\n\n```php\nMap::from( ['google.com', 'aimeos.com'] )-\u003estrReplace( '.com', '.de' );\n// ['google.de', 'aimeos.de']\n\nMap::from( ['google.com', 'aimeos.org'] )-\u003estrReplace( ['.com', '.org'], '.de' );\n// ['google.de', 'aimeos.de']\n\nMap::from( ['google.com', 'aimeos.org'] )-\u003estrReplace( ['.com', '.org'], ['.de'] );\n// ['google.de', 'aimeos']\n\nMap::from( ['google.com', 'aimeos.org'] )-\u003estrReplace( ['.com', '.org'], ['.fr', '.de'] );\n// ['google.fr', 'aimeos.de']\n\nMap::from( ['google.com', 'aimeos.com'] )-\u003estrReplace( ['.com', '.co'], ['.co', '.de', '.fr'] );\n// ['google.de', 'aimeos.de']\n\nMap::from( ['google.com', 'aimeos.com', 123] )-\u003estrReplace( '.com', '.de' );\n// ['google.de', 'aimeos.de', 123]\n\nMap::from( ['GOOGLE.COM', 'AIMEOS.COM'] )-\u003estrReplace( '.com', '.de', true );\n// ['GOOGLE.de', 'AIMEOS.de']\n```\n\n\n### strStarts()\n\nTests if at least one of the entries starts with at least one of the passed strings.\n\n```php\npublic function strStarts( $value, string $encoding = 'UTF-8' ) : bool\n```\n\n* @param **array\u0026#124;string** `$value` The string or list of strings to search for in each entry\n* @param **string** `$encoding` Character encoding of the strings, e.g. \"UTF-8\" (default), \"ASCII\", \"ISO-8859-1\", etc.\n* @return **bool** TRUE if one of the entries starts with one of the strings, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( ['abc'] )-\u003estrStarts( '' );\n// true\n\nMap::from( ['abc'] )-\u003estrStarts( 'a' );\n// true\n\nMap::from( ['abc'] )-\u003estrStarts( 'ab' );\n// true\n\nMap::from( ['abc'] )-\u003estrStarts( ['a', 'b'] );\n// true\n\nMap::from( ['abc'] )-\u003estrStarts( 'ab', 'ASCII' );\n// true\n\nMap::from( ['abc'] )-\u003estrStarts( 'b' );\n// false\n\nMap::from( ['abc'] )-\u003estrStarts( 'bc' );\n// false\n\nMap::from( ['abc'] )-\u003estrStarts( ['b', 'c'] );\n// false\n\nMap::from( ['abc'] )-\u003estrStarts( 'bc', 'ASCII' );\n// false\n```\n\n**See also:**\n\n* [strStartsAll()](#strstartsall) - Tests if all of the entries starts with one of the passed strings\n\n\n### strStartsAll()\n\nTests if all of the entries starts with one of the passed strings.\n\n```php\npublic function strStartsAll( $value, string $encoding = 'UTF-8' ) : bool\n```\n\n* @param **array\u0026#124;string** `$value` The string or list of strings to search for in each entry\n* @param **string** `$encoding` Character encoding of the strings, e.g. \"UTF-8\" (default), \"ASCII\", \"ISO-8859-1\", etc.\n* @return **bool** TRUE if one of the entries starts with one of the strings, FALSE if not\n\n**Examples:**\n\n```php\nMap::from( ['abc', 'def'] )-\u003estrStartsAll( '' );\n// true\n\nMap::from( ['abc', 'acb'] )-\u003estrStartsAll( 'a' );\n// true\n\nMap::from( ['abc', 'aba'] )-\u003estrStartsAll( 'ab' );\n// true\n\nMap::from( ['abc', 'def'] )-\u003estrStartsAll( ['a', 'd'] );\n// true\n\nMap::from( ['abc', 'acf'] )-\u003estrStartsAll( 'a', 'ASCII' );\n// true\n\nMap::from( ['abc', 'def'] )-\u003estrStartsAll( 'd' );\n// false\n\nMap::from( ['abc', 'bca'] )-\u003estrStartsAll( 'ab' );\n// false\n\nMap::from( ['abc', 'bac'] )-\u003estrStartsAll( ['a', 'c'] );\n// false\n\nMap::from( ['abc', 'cab'] )-\u003estrStartsAll( 'ab', 'ASCII' );\n// false\n```\n\n**See also:**\n\n* [strStarts()](#strstarts) - Tests if at least one of the entries starts with at least one of the passed strings\n\n\n### strUpper()\n\nConverts all alphabetic characters in strings to upper case.\n\n```php\npublic function strUpper( string $encoding = 'UTF-8' ) :self\n```\n\n* @param **string** `$encoding` Character encoding of the strings, e.g. \"UTF-8\" (default), \"ASCII\", \"ISO-8859-1\", etc.\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( ['My String'] )-\u003estrUpper();\n// [\"MY STRING\"]\n\nMap::from( ['τάχιστη'] )-\u003estrUpper();\n// [\"ΤΆΧΙΣΤΗ\"]\n\nMap::from( ['äpfel', 'birnen'] )-\u003estrUpper( 'ISO-8859-1' );\n// [\"ÄPFEL\", \"BIRNEN\"]\n```\n\n**See also:**\n\n* [strLower()](#strlower) - Converts all alphabetic characters in strings to lower case\n\n\n### suffix\n\nAdds a suffix at the end of each map entry.\n\n```php\npublic function suffix( $suffix, int $depth = null ) : self\n```\n\n* @param **\\Closure\u0026#124;string** `$suffix` Function with map as parameter which returns arbitrary result\n* @param **int\u0026#124;null** `$depth` Maximum depth to dive into multi-dimensional arrays starting from \"1\"\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nBy defaul, nested arrays are walked recusively so all entries at all levels are suffixed.\nThe keys are preserved using this method.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003esuffix( '-1' );\n// ['a-1', 'b-1']\n\nMap::from( ['a', ['b']] )-\u003esuffix( '-1' );\n// ['a-1', ['b-1']]\n\nMap::from( ['a', ['b']] )-\u003esuffix( '-1', 1 );\n// ['a-1', ['b']]\n\nMap::from( ['a', 'b'] )-\u003esuffix( function( $item, $key ) {\n    return '-' . ( ord( $item ) + ord( $key ) );\n} );\n// ['a-145', 'b-147']\n```\n\n**See also:**\n\n* [prefix()](#prefix) - Adds a prefix in front of each map entry\n\n\n### sum()\n\nReturns the sum of all integer and float values in the map.\n\n```php\npublic function sum( $col = null ) : float\n```\n\n* @param **Closure\u0026#124;string\u0026#124;null** `$col` Closure, key in the nested array or object to sum up\n* @return **float** Sum of all elements or 0 if there are no elements in the map\n\nNon-numeric values will be removed before calculation.\n\nThis does also work to map values from multi-dimensional arrays by passing the keys\nof the arrays separated by the delimiter (\"/\" by default), e.g. `key1/key2/key3`\nto get `val` from `['key1' =\u003e ['key2' =\u003e ['key3' =\u003e 'val']]]`. The same applies to\npublic properties of objects or objects implementing `__isset()` and `__get()` methods.\n\n**Examples:**\n\n```php\nMap::from( [1, 3, 5] )-\u003esum();\n// 9\n\nMap::from( [1, 'sum', 5] )-\u003esum();\n// 6\n\nMap::from( [['p' =\u003e 30], ['p' =\u003e 50], ['p' =\u003e 10]] )-\u003esum( 'p' );\n// 90\n\nMap::from( [['i' =\u003e ['p' =\u003e 30]], ['i' =\u003e ['p' =\u003e 50]]] )-\u003esum( 'i/p' );\n// 80\n\nMap::from( [['i' =\u003e ['p' =\u003e 30]], ['i' =\u003e ['p' =\u003e 50]]] )-\u003esum( fn( $val, $key ) =\u003e $val['i']['p'] ?? null )\n// 80\n\nMap::from( [30, 50, 10] )-\u003esum( fn( $val, $key ) =\u003e $val \u003c 50 );\n// 40\n```\n\n**See also:**\n\n* [avg()](#avg) - Returns the average of all integer and float values in the map\n* [count()](#count) - Returns the total number of elements\n* [max()](#max) - Returns the maximum value of all elements\n* [min()](#min) - Returns the minium value of all elements\n* [percentage()](#percentage) - Returns the percentage of all elements passing the test\n\n\n### take()\n\nReturns a new map with the given number of items.\n\n```php\npublic function take( int $size, $offset = 0 ) : self\n```\n\n* @param **int** `$size` Number of items to return\n* @param **\\Closure\u0026#124;int** `$offset` Number of items to skip or function($item, $key) returning true for skipped items\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe keys of the items returned in the new map are the same as in the original one.\n\n**Examples:**\n\n```php\nMap::from( [1, 2, 3, 4] )-\u003etake( 2 );\n// [0 =\u003e 1, 1 =\u003e 2]\n\nMap::from( [1, 2, 3, 4] )-\u003etake( 2, 1 );\n// [1 =\u003e 2, 2 =\u003e 3]\n\nMap::from( [1, 2, 3, 4] )-\u003etake( 2, -2 );\n// [2 =\u003e 3, 3 =\u003e 4]\n\nMap::from( [1, 2, 3, 4] )-\u003etake( 2, function( $item, $key ) {\n    return $item \u003c 2;\n} );\n// [1 =\u003e 2, 2 =\u003e 3]\n```\n\n**See also:**\n\n* [slice()](#slice) - Returns a map with the slice from the original map.\n\n\n### tap()\n\nPasses a clone of the map to the given callback.\n\n```php\npublic function tap( callable $callback ) : self\n```\n\n* @param **callable** `$callback` Function receiving ($map) parameter\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Same map for fluid interface\n\nUse it to \"tap\" into a chain of methods to check the state between two\nmethod calls. The original map is not altered by anything done in the\ncallback.\n\n**Examples:**\n\n```php\nMap::from( [3, 2, 1] )-\u003ersort()-\u003etap( function( $map ) {\n    print_r( $map-\u003eremove( 0 )-\u003etoArray() );\n} )-\u003efirst();\n// 1\n```\n\nIt will sort the list in reverse order(`[1, 2, 3]`), then prints the items (`[2, 3]`)\nwithout the first one in the function passed to `tap()` and returns the first item\n(\"1\") at the end.\n\n\n### times()\n\nCreates a new map by invoking the closure the given number of times.\n\n```php\npublic static function times( int $num, \\Closure $callback ) : self\n```\n\n* @param **int** `$num` Number of times the function is called\n* @param **\\Closure** `$callback` Function with (value, key) parameters and returns new value\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with the generated elements\n\nThis method creates a lazy Map and the entries are generated after calling\nanother method that operates on the Map contents. Thus, the passed callback\nis not called immediately!\n\n**Examples:**\n\n```php\nMap::times( 3, function( $num ) {\n    return $num * 10;\n} );\n// [0 =\u003e 0, 1 =\u003e 10, 2 =\u003e 20]\n\nMap::times( 3, function( $num, \u0026$key ) {\n    $key = $num * 2;\n    return $num * 5;\n} );\n// [0 =\u003e 0, 2 =\u003e 5, 4 =\u003e 10]\n\nMap::times( 2, function( $num ) {\n    return new \\stdClass();\n} );\n// [0 =\u003e new \\stdClass(), 1 =\u003e new \\stdClass()]\n```\n\n\n### to()\n\nReturns the elements as a plain array.\n\n```php\npublic function to() : array\n```\n\n* @return **array** Plain array\n\n**Examples:**\n\n```php\nMap::from( ['a'] )-\u003eto();\n// ['a']\n```\n\nThis is the preferred method for retrieving the plain array of the Map object.\n\n**See also:**\n\n* [all()](#all) - Returns the elements as a plain array\n* [toArray()](#toarray) - Returns the elements as a plain array\n\n\n### toArray()\n\nReturns the elements as a plain array.\n\n```php\npublic function toArray() : array\n```\n\n* @return **array** Plain array\n\n**Examples:**\n\n```php\nMap::from( ['a'] )-\u003etoArray();\n// ['a']\n```\n\n**See also:**\n\n* [all()](#all) - Returns the elements as a plain array\n* [to()](#to) - Returns the elements as a plain array\n\n\n### toJson()\n\nReturns the elements encoded as JSON string.\n\n```php\npublic function toJson( int $options = 0 ) : ?string\n```\n\n* @param **int** `$options` Combination of JSON_* constants\n* @return **string\u0026#124;null** Array encoded as JSON string or NULL on failure\n\nThere are several options available to modify the JSON string which are described in\nthe [PHP json_encode() manual](https://www.php.net/manual/en/function.json-encode.php).\nThe parameter can be a single JSON_* constant or a bitmask of several constants\ncombine by bitwise OR (\u0026#124;), e.g.:\n\n```php\nJSON_FORCE_OBJECT|JSON_HEX_QUOT\n```\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003etoJson();\n// '[\"a\",\"b\"]'\n\nMap::from( ['a' =\u003e 'b'] )-\u003etoJson();\n// '{\"a\":\"b\"}'\n\nMap::from( ['a', 'b'] )-\u003etoJson( JSON_FORCE_OBJECT );\n// '{\"0\":\"a\", \"1\":\"b\"}'\n```\n\n\n### toReversed()\n\nReverses the element order in a copy of the map (alias).\n\n```php\npublic function toReversed() : self\n```\n\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with a reversed copy of the elements\n\nThis method is an alias for [reversed()](#reversed). For performance reasons, reversed() should be\npreferred because it uses one method call less than toReversed().\n\n**See also:**\n\n* [reversed()](#reversed) - Underlying method with same parameters and return value but better performance\n\n\n### toSorted()\n\nSorts the elements in a copy of the map using new keys (alias).\n\n```php\npublic function toSorted( int $options = SORT_REGULAR ) : self\n```\n\n* @param **int** `$options` Sort options for PHP `sort()`\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with a sorted copy of the elements\n\nThis method is an alias for [sorted()](#sorted). For performance reasons, sorted()\nshould be preferred because it uses one method call less than toSorted(). A new map\nis created by calling this method.\n\n**See also:**\n\n* [sorted()](#sorted) - Underlying method with same parameters and return value but better performance\n\n\n### toUrl()\n\nCreates a HTTP query string from the map elements.\n\n```php\npublic function toUrl() : string\n```\n\n* @return **string** Parameter string for GET requests\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 1, 'b' =\u003e 2] )-\u003etoUrl();\n// a=1\u0026b=2\n\nMap::from( ['a' =\u003e ['b' =\u003e 'abc', 'c' =\u003e 'def'], 'd' =\u003e 123] )-\u003etoUrl();\n// a%5Bb%5D=abc\u0026a%5Bc%5D=def\u0026d=123\n```\n\n\n### transform()\n\nCreates new key/value pairs using the passed function and returns a new map for the result.\n\n```php\npublic function transform( \\Closure $callback ) : self\n```\n\n* @param **\\Closure** `$callback` Function with (value, key) parameters and returns an array of new key/value pair(s)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with the new key/value pairs\n\nIf a key is returned twice, the last value will overwrite previous values.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 2, 'b' =\u003e 4] )-\u003etransform( function( $value, $key ) {\n    return [$key . '-2' =\u003e $value * 2];\n} );\n// ['a-2' =\u003e 4, 'b-2' =\u003e 8]\n\nMap::from( ['a' =\u003e 2, 'b' =\u003e 4] )-\u003etransform( function( $value, $key ) {\n    return [$key =\u003e $value * 2, $key . $key =\u003e $value * 4];\n} );\n// ['a' =\u003e 4, 'aa' =\u003e 8, 'b' =\u003e 8, 'bb' =\u003e 16]\n\nMap::from( ['a' =\u003e 2, 'b' =\u003e 4] )-\u003etransform( function( $value, $key ) {\n    return $key \u003c 'b' ? [$key =\u003e $value * 2] : null;\n} );\n// ['a' =\u003e 4]\n\nMap::from( ['la' =\u003e 2, 'le' =\u003e 4, 'li' =\u003e 6] )-\u003etransform( function( $value, $key ) {\n    return [$key[0] =\u003e $value * 2];\n} );\n// ['l' =\u003e 12]\n```\n\n**See also:**\n\n* [map()](#map) - Maps new values to the existing keys using the passed function and returns a new map for the result\n* [rekey()](#rekey) - Changes the keys according to the passed function\n\n\n### transpose()\n\nExchanges rows and columns for a two dimensional map.\n\n```php\npublic function transpose() : self\n```\n\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\n**Examples:**\n\n```php\nMap::from( [\n  ['name' =\u003e 'A', 2020 =\u003e 200, 2021 =\u003e 100, 2022 =\u003e 50],\n  ['name' =\u003e 'B', 2020 =\u003e 300, 2021 =\u003e 200, 2022 =\u003e 100],\n  ['name' =\u003e 'C', 2020 =\u003e 400, 2021 =\u003e 300, 2022 =\u003e 200],\n] )-\u003etranspose();\n/*\n[\n  'name' =\u003e ['A', 'B', 'C'],\n  2020 =\u003e [200, 300, 400],\n  2021 =\u003e [100, 200, 300],\n  2022 =\u003e [50, 100, 200]\n]\n*/\n\nMap::from( [\n  ['name' =\u003e 'A', 2020 =\u003e 200, 2021 =\u003e 100, 2022 =\u003e 50],\n  ['name' =\u003e 'B', 2020 =\u003e 300, 2021 =\u003e 200],\n  ['name' =\u003e 'C', 2020 =\u003e 400]\n] );\n/*\n[\n  'name' =\u003e ['A', 'B', 'C'],\n  2020 =\u003e [200, 300, 400],\n  2021 =\u003e [100, 200],\n  2022 =\u003e [50]\n]\n*/\n```\n\n\n### traverse()\n\nTraverses trees of nested items passing each item to the callback.\n\n```php\npublic function traverse( \\Closure $callback = null, string $nestKey = 'children' ) : self\n```\n\n* @param **\\Closure\u0026#124;null** `$callback` Callback with (entry, key, level, $parent) arguments, returns the entry added to result\n* @param **string** `$nestKey` Key to the children of each item\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with all items as flat list\n\nThis does work for nested arrays and objects with public properties or\nobjects implementing `__isset()` and `__get()` methods. To build trees\nof nested items, use the [tree()](#tree) method.\n\n**Examples:**\n\n```php\nMap::from( [[\n  'id' =\u003e 1, 'pid' =\u003e null, 'name' =\u003e 'n1', 'children' =\u003e [\n    ['id' =\u003e 2, 'pid' =\u003e 1, 'name' =\u003e 'n2', 'children' =\u003e []],\n    ['id' =\u003e 3, 'pid' =\u003e 1, 'name' =\u003e 'n3', 'children' =\u003e []]\n  ]\n]] )-\u003etraverse();\n/*\n[\n  ['id' =\u003e 1, 'pid' =\u003e null, 'name' =\u003e 'n1', 'children' =\u003e [...]],\n  ['id' =\u003e 2, 'pid' =\u003e 1, 'name' =\u003e 'n2', 'children' =\u003e []],\n  ['id' =\u003e 3, 'pid' =\u003e 1, 'name' =\u003e 'n3', 'children' =\u003e []],\n]\n*/\n\nMap::from( [[\n  'id' =\u003e 1, 'pid' =\u003e null, 'name' =\u003e 'n1', 'children' =\u003e [\n    ['id' =\u003e 2, 'pid' =\u003e 1, 'name' =\u003e 'n2', 'children' =\u003e []],\n    ['id' =\u003e 3, 'pid' =\u003e 1, 'name' =\u003e 'n3', 'children' =\u003e []]\n  ]\n]] )-\u003etraverse( function( $entry, $key, $level ) {\n  return str_repeat( '-', $level ) . '- ' . $entry['name'];\n} );\n// ['- n1', '-- n2', '-- n3']\n\nMap::from( [[\n  'id' =\u003e 1, 'pid' =\u003e null, 'name' =\u003e 'n1', 'children' =\u003e [\n    ['id' =\u003e 2, 'pid' =\u003e 1, 'name' =\u003e 'n2', 'children' =\u003e []],\n    ['id' =\u003e 3, 'pid' =\u003e 1, 'name' =\u003e 'n3', 'children' =\u003e []]\n  ]\n]] )-\u003etraverse( function( \u0026$entry, $key, $level, $parent ) {\n  $entry['path'] = isset( $parent['path'] ) ? $parent['path'] . '/' . $entry['name'] : $entry['name'];\n  return $entry;\n} );\n/*\n[\n  ['id' =\u003e 1, 'pid' =\u003e null, 'name' =\u003e 'n1', 'children' =\u003e [...], 'path' =\u003e 'n1'],\n  ['id' =\u003e 2, 'pid' =\u003e 1, 'name' =\u003e 'n2', 'children' =\u003e [], 'path' =\u003e 'n1/n2'],\n  ['id' =\u003e 3, 'pid' =\u003e 1, 'name' =\u003e 'n3', 'children' =\u003e [], 'path' =\u003e 'n1/n3'],\n]\n*/\n\nMap::from( [[\n  'id' =\u003e 1, 'pid' =\u003e null, 'name' =\u003e 'n1', 'nodes' =\u003e [\n    ['id' =\u003e 2, 'pid' =\u003e 1, 'name' =\u003e 'n2', 'nodes' =\u003e []]\n  ]\n]] )-\u003etraverse( null, 'nodes' );\n/*\n[\n  ['id' =\u003e 1, 'pid' =\u003e null, 'name' =\u003e 'n1', 'nodes' =\u003e [...]],\n  ['id' =\u003e 2, 'pid' =\u003e 1, 'name' =\u003e 'n2', 'nodes' =\u003e []],\n]\n*/\n```\n\n**See also:**\n\n* [tree()](#tree) - Creates a tree structure from the list items\n\n\n### tree()\n\nCreates a tree structure from the list items.\n\n```php\npublic function tree( string $idKey, string $parentKey, string $nestKey = 'children' ) : self\n```\n\n* @param **string** `$idKey` Name of the key with the unique ID of the node\n* @param **string** `$parentKey` Name of the key with the ID of the parent node\n* @param **string** `$nestKey` Name of the key with will contain the children of the node\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map with one or more root tree nodes\n\nUse this method to rebuild trees e.g. from database records. To traverse\ntrees, use the [traverse()](#traverse) method.\n\n**Examples:**\n\n```php\nMap::from( [\n  ['id' =\u003e 1, 'pid' =\u003e null, 'lvl' =\u003e 0, 'name' =\u003e 'n1'],\n  ['id' =\u003e 2, 'pid' =\u003e 1, 'lvl' =\u003e 1, 'name' =\u003e 'n2'],\n  ['id' =\u003e 3, 'pid' =\u003e 2, 'lvl' =\u003e 2, 'name' =\u003e 'n3'],\n  ['id' =\u003e 4, 'pid' =\u003e 1, 'lvl' =\u003e 1, 'name' =\u003e 'n4'],\n  ['id' =\u003e 5, 'pid' =\u003e 3, 'lvl' =\u003e 2, 'name' =\u003e 'n5'],\n  ['id' =\u003e 6, 'pid' =\u003e 1, 'lvl' =\u003e 1, 'name' =\u003e 'n6'],\n] )-\u003etree( 'id', 'pid' );\n/*\n[1 =\u003e [\n  'id' =\u003e 1, 'pid' =\u003e null, 'lvl' =\u003e 0, 'name' =\u003e 'n1', 'children' =\u003e [\n    2 =\u003e ['id' =\u003e 2, 'pid' =\u003e 1, 'lvl' =\u003e 1, 'name' =\u003e 'n2', 'children' =\u003e [\n      3 =\u003e ['id' =\u003e 3, 'pid' =\u003e 2, 'lvl' =\u003e 2, 'name' =\u003e 'n3', 'children' =\u003e []]\n    ]],\n    4 =\u003e ['id' =\u003e 4, 'pid' =\u003e 1, 'lvl' =\u003e 1, 'name' =\u003e 'n4', 'children' =\u003e [\n      5 =\u003e ['id' =\u003e 5, 'pid' =\u003e 3, 'lvl' =\u003e 2, 'name' =\u003e 'n5', 'children' =\u003e []]\n    ]],\n    6 =\u003e ['id' =\u003e 6, 'pid' =\u003e 1, 'lvl' =\u003e 1, 'name' =\u003e 'n6', 'children' =\u003e []]\n  ]\n]]\n*/\n```\n\nTo build the tree correctly, the items must be in order or at least the\nnodes of the lower levels must come first. For a tree like this:\n\n```\nn1\n|- n2\n|  |- n3\n|- n4\n|  |- n5\n|- n6\n```\n\nAccepted item order:\n- in order: n1, n2, n3, n4, n5, n6\n- lower levels first: n1, n2, n4, n6, n3, n5\n\nIf your items are unordered, apply [usort()](#usort) first to the map entries, e.g.\n\n```php\nMap::from( [['id' =\u003e 3, 'lvl' =\u003e 2], ...] )-\u003eusort( function( $item1, $item2 ) {\n  return $item1['lvl'] \u003c=\u003e $item2['lvl'];\n} );\n```\n\n**See also:**\n\n* [traverse()](#traverse) - Traverses trees of nested items passing each item to the callback\n\n\n### trim()\n\nRemoves the passed characters from the left/right of all strings.\n\n```php\npublic function trim( string $chars = \" \\n\\r\\t\\v\\x00\" ) : self\n```\n\n* @param **string** `$chars` List of characters to trim\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\n**Examples:**\n\n```php\nMap::from( [\" abc\\n\", \"\\tcde\\r\\n\"] )-\u003etrim();\n// [\"abc\", \"cde\"]\n\nMap::from( [\"a b c\", \"cbax\"] )-\u003etrim( 'abc' );\n// [\" b \", \"x\"]\n```\n\n**See also:**\n\n* [ltrim()](#ltrim) - Removes the passed characters from the left of all strings\n* [rtrim()](#rtrim) - Removes the passed characters from the right of all strings\n\n\n### uasort()\n\nSorts all elements using a callback and maintains the key association.\n\n```php\npublic function uasort( callable $callback ) : self\n```\n\n* @param **callable** `$callback` Function with (itemA, itemB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe given callback will be used to compare the values. The callback must accept\ntwo parameters (item A and B) and must return -1 if item A is smaller than\nitem B, 0 if both are equal and 1 if item A is greater than item B. Both, a\nmethod name and an anonymous function can be passed.\n\nThe keys are preserved using this method and no new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'B', 'b' =\u003e 'a'] )-\u003euasort( 'strcasecmp' );\n// ['b' =\u003e 'a', 'a' =\u003e 'B']\n\nMap::from( ['a' =\u003e 'B', 'b' =\u003e 'a'] )-\u003euasort( function( $itemA, $itemB ) {\n    return strtolower( $itemA ) \u003c=\u003e strtolower( $itemB );\n} );\n// ['b' =\u003e 'a', 'a' =\u003e 'B']\n```\n\n**See also:**\n\n* [uasorted()](#uasorted) - Sorts a copy of all elements using a callback and maintains the key association\n\n\n### uasorted()\n\nSorts a copy of all elements using a callback and maintains the key association.\n\n```php\npublic function uasorted( callable $callback ) : self\n```\n\n* @param **callable** `$callback` Function with (itemA, itemB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe given callback will be used to compare the values. The callback must accept\ntwo parameters (item A and B) and must return -1 if item A is smaller than\nitem B, 0 if both are equal and 1 if item A is greater than item B. Both, a\nmethod name and an anonymous function can be passed.\n\nThe keys are preserved using this method and a new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'B', 'b' =\u003e 'a'] )-\u003euasorted( 'strcasecmp' );\n// ['b' =\u003e 'a', 'a' =\u003e 'B']\n\nMap::from( ['a' =\u003e 'B', 'b' =\u003e 'a'] )-\u003euasorted( function( $itemA, $itemB ) {\n    return strtolower( $itemA ) \u003c=\u003e strtolower( $itemB );\n} );\n// ['b' =\u003e 'a', 'a' =\u003e 'B']\n```\n\n**See also:**\n\n* [uasort()](#uasort) - Sorts all elements using a callback and maintains the key association\n\n\n### uksort()\n\nSorts the map elements by their keys using a callback.\n\n```php\npublic function uksort( callable $callback ) : self\n```\n\n* @param **callable** `$callback` Function with (keyA, keyB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe given callback will be used to compare the keys. The callback must accept\ntwo parameters (key A and B) and must return -1 if key A is smaller than\nkey B, 0 if both are equal and 1 if key A is greater than key B. Both, a\nmethod name and an anonymous function can be passed.\n\nThe keys are preserved using this method and no new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['B' =\u003e 'a', 'a' =\u003e 'b'] )-\u003euksort( 'strcasecmp' );\n// ['a' =\u003e 'b', 'B' =\u003e 'a']\n\nMap::from( ['B' =\u003e 'a', 'a' =\u003e 'b'] )-\u003euksort( function( $keyA, $keyB ) {\n    return strtolower( $keyA ) \u003c=\u003e strtolower( $keyB );\n} );\n// ['a' =\u003e 'b', 'B' =\u003e 'a']\n```\n\n**See also:**\n\n* [uksorted()](#uksorted) - Sorts a copy of the map elements by their keys using a callback\n\n\n### uksorted()\n\nSorts a copy of the map elements by their keys using a callback.\n\n```php\npublic function uksorted( callable $callback ) : self\n```\n\n* @param **callable** `$callback` Function with (keyA, keyB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe given callback will be used to compare the keys. The callback must accept\ntwo parameters (key A and B) and must return -1 if key A is smaller than\nkey B, 0 if both are equal and 1 if key A is greater than key B. Both, a\nmethod name and an anonymous function can be passed.\n\nThe keys are preserved using this method and a new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['B' =\u003e 'a', 'a' =\u003e 'b'] )-\u003euksorted( 'strcasecmp' );\n// ['a' =\u003e 'b', 'B' =\u003e 'a']\n\nMap::from( ['B' =\u003e 'a', 'a' =\u003e 'b'] )-\u003euksorted( function( $keyA, $keyB ) {\n    return strtolower( $keyA ) \u003c=\u003e strtolower( $keyB );\n} );\n// ['a' =\u003e 'b', 'B' =\u003e 'a']\n```\n\n**See also:**\n\n* [uksort()](#uksort) - Sorts the map elements by their keys using a callback\n\n\n### union()\n\nBuilds a union of the elements and the given elements without returning a new map.\nExisting keys in the map will not be overwritten\n\n```php\npublic function union( iterable $elements ) : self\n```\n\n* @param **iterable\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$elements` List of elements\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nIf list entries should be overwritten, use [merge()](#merge) instead.\nThe keys are preserved using this method and no new map is created.\n\n**Examples:**\n\n```php\nMap::from( [0 =\u003e 'a', 1 =\u003e 'b'] )-\u003eunion( [0 =\u003e 'c'] );\n// [0 =\u003e 'a', 1 =\u003e 'b'] because the key 0 isn't overwritten\n\nMap::from( ['a' =\u003e 1, 'b' =\u003e 2] )-\u003eunion( ['c' =\u003e 1] );\n// ['a' =\u003e 1, 'b' =\u003e 2, 'c' =\u003e 1]\n```\n\n**See also:**\n\n* [concat()](#combine) - Adds all elements with new keys\n* [merge()](#merge) - Merges the map with the given elements without returning a new map\n\n\n### unique()\n\nReturns only unique elements from the map in a new map.\n\n```php\npublic function unique( $col = null ) : self\n```\n\n* @param **\\Closure\u0026#124;string\u0026#124;null** `$col` Key, path of the nested array or anonymous function with ($item, $key) parameters returning the value for comparison\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nTwo elements are considered equal if comparing their string representions returns TRUE:\n\n```php\n(string) $elem1 === (string) $elem2\n```\n\nThe keys of the elements are preserved in the new map.\n\n**Examples:**\n\n```php\nMap::from( [0 =\u003e 'a', 1 =\u003e 'b', 2 =\u003e 'b', 3 =\u003e 'c'] )-\u003eunique();\n// [0 =\u003e 'a', 1 =\u003e 'b', 3 =\u003e 'c']\n\nMap::from( [['p' =\u003e '1'], ['p' =\u003e 1], ['p' =\u003e 2]] )-\u003eunique( 'p' );\n// [0 =\u003e ['p' =\u003e '1'], 2 =\u003e ['p' =\u003e 2]]\n\nMap::from( [['i' =\u003e ['p' =\u003e '1']], ['i' =\u003e ['p' =\u003e 1]]] )-\u003eunique( 'i/p' );\n// [0 =\u003e ['i' =\u003e ['p' =\u003e '1']]]\n\nMap::from( [['i' =\u003e ['p' =\u003e '1']], ['i' =\u003e ['p' =\u003e 1]]] )-\u003eunique( fn( $item, $key ) =\u003e $item['i']['p'] );\n// [0 =\u003e ['i' =\u003e ['p' =\u003e '1']]]\n```\n\n**See also:**\n\n* [duplicates()](#duplicates) - Returns the duplicate values from the map\n\n\n### unshift()\n\nPushes an element onto the beginning of the map without returning a new map.\n\n```php\npublic function unshift( $value, $key = null ) : self\n```\n\n* @param **mixed** `$value` Item to add at the beginning\n* @param **int\u0026#124;string\u0026#124;null** `$key` Key for the item or NULL to reindex all numerical keys\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe keys of the elements are only preserved in the new map if no key is passed.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'b'] )-\u003eunshift( 'd' );\n// ['d', 'a', 'b']\n\nMap::from( ['a', 'b'] )-\u003eunshift( 'd', 'first' );\n// ['first' =\u003e 'd', 0 =\u003e 'a', 1 =\u003e 'b']\n```\n\n**Performance note:**\n\nThe bigger the list, the higher the performance impact because `unshift()`\nneeds to create a new list and copies all existing elements to the new\narray. Usually, it's better to [push()](#push) new entries at the end and\n[reverse()](#reverse) the list afterwards:\n\n```php\n$map-\u003epush( 'a' )-\u003epush( 'b' )-\u003ereverse();\n```\n\ninstead of\n\n```php\n$map-\u003eunshift( 'a' )-\u003eunshift( 'b' );\n```\n\n**See also:**\n\n* [shift()](#shift) - Returns and removes the first element from the map\n\n\n### usort()\n\nSorts all elements using a callback without maintaining the key association.\n\n```php\npublic function usort( callable $callback ) : self\n```\n\n* @param **callable** `$callback` Function with (itemA, itemB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nThe given callback will be used to compare the values. The callback must accept\ntwo parameters (item A and B) and must return -1 if item A is smaller than\nitem B, 0 if both are equal and 1 if item A is greater than item B. Both, a\nmethod name and an anonymous function can be passed.\n\nThe keys are NOT preserved and elements get a new index. No new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'B', 'b' =\u003e 'a'] )-\u003eusort( 'strcasecmp' );\n// [0 =\u003e 'a', 1 =\u003e 'B']\n\nMap::from( ['a' =\u003e 'B', 'b' =\u003e 'a'] )-\u003eusort( function( $itemA, $itemB ) {\n    return strtolower( $itemA ) \u003c=\u003e strtolower( $itemB );\n} );\n// [0 =\u003e 'a', 1 =\u003e 'B']\n```\n\n**See also:**\n\n* [usorted()](#usorted) - Sorts a copy of all elements using a callback without maintaining the key association\n\n\n### usorted()\n\nSorts a copy of all elements using a callback without maintaining the key association.\n\n```php\npublic function usorted( callable $callback ) : self\n```\n\n* @param **callable** `$callback` Function with (itemA, itemB) parameters and returns -1 (\u003c), 0 (=) and 1 (\u003e)\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map\n\nThe given callback will be used to compare the values. The callback must accept\ntwo parameters (item A and B) and must return -1 if item A is smaller than\nitem B, 0 if both are equal and 1 if item A is greater than item B. Both, a\nmethod name and an anonymous function can be passed.\n\nThe keys are NOT preserved and elements get a new index and a new map is created.\n\n**Examples:**\n\n```php\nMap::from( ['a' =\u003e 'B', 'b' =\u003e 'a'] )-\u003eusorted( 'strcasecmp' );\n// [0 =\u003e 'a', 1 =\u003e 'B']\n\nMap::from( ['a' =\u003e 'B', 'b' =\u003e 'a'] )-\u003eusorted( function( $itemA, $itemB ) {\n    return strtolower( $itemA ) \u003c=\u003e strtolower( $itemB );\n} );\n// [0 =\u003e 'a', 1 =\u003e 'B']\n```\n\n**See also:**\n\n* [usort()](#usort) - Sorts all elements using a callback without maintaining the key association\n\n\n### values()\n\nResets the keys and return the values in a new map.\n\n```php\npublic function values() : self\n```\n\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map of the values\n\n**Examples:**\n\n```php\nMap::from( ['x' =\u003e 'b', 2 =\u003e 'a', 'c'] )-\u003evalues();\n// [0 =\u003e 'b', 1 =\u003e 'a', 2 =\u003e 'c']\n```\n\n\n### walk()\n\nApplies the given callback to all elements.\n\n```php\npublic function walk( callable $callback, $data = null, bool $recursive = true ) : self\n```\n\n* @param **callable** `$callback` Function with (item, key, data) parameters\n* @param **mixed** `$data` Arbitrary data that will be passed to the callback as third parameter\n* @param **bool** `$recursive` TRUE to traverse sub-arrays recursively (default), FALSE to iterate Map elements only\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** Updated map for fluid interface\n\nTo change the values of the Map, specify the value parameter as reference\n(`\u0026$value`). You can only change the values but not the keys nor the array\nstructure.\n\nBy default, Map elements which are arrays will be traversed recursively.\nTo iterate over the Map elements only, pass FALSE as third parameter.\n\n**Examples:**\n\n```php\nMap::from( ['a', 'B', ['c', 'd'], 'e'] )-\u003ewalk( function( \u0026$value ) {\n    $value = strtoupper( $value );\n} );\n// ['A', 'B', ['C', 'D'], 'E']\n\nMap::from( [66 =\u003e 'B', 97 =\u003e 'a'] )-\u003ewalk( function( $value, $key ) {\n    echo 'ASCII ' . $key . ' is ' . $value . \"\\n\";\n} );\n/*\nASCII 66 is B\nASCII 97 is a\n*/\n\nMap::from( [1, 2, 3] )-\u003ewalk( function( \u0026$value, $key, $data ) {\n    $value = $data[$value] ?? $value;\n}, [1 =\u003e 'one', 2 =\u003e 'two'] );\n// ['one', 'two', 3]\n```\n\n\n### where()\n\nFilters the list of elements by a given condition.\n\n```php\npublic function where( string $key, string $op, $value ) : self\n```\n\n* @param **string** `$key` Key or path of the value of the array or object used for comparison\n* @param **string** `$op` Operator used for comparison\n* @param **mixed** `$value` Value used for comparison\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map for fluid interface\n\nAvailable operators are:\n\n* '==' : Equal\n* '===' : Equal and same type\n* '!=' : Not equal\n* '!==' : Not equal and same type\n* '\u003c=' : Smaller than an equal\n* '\u003e=' : Greater than an equal\n* '\u003c' : Smaller\n* '\u003e' : Greater\n* 'in' : Array of value which are in the list of values\n* '-' : Values between array of start and end value, e.g. [10, 100] (inclusive)\n\nThe keys of the original map are preserved in the returned map.\n\n**Examples:**\n\n```php\nMap::from( [\n  ['id' =\u003e 1, 'type' =\u003e 'name'],\n  ['id' =\u003e 2, 'type' =\u003e 'short'],\n] )-\u003ewhere( 'type', '==', 'name' );\n/*\n[\n    ['id' =\u003e 1, 'type' =\u003e 'name']\n]\n*/\n\nMap::from( [\n  ['id' =\u003e 3, 'price' =\u003e 10],\n  ['id' =\u003e 4, 'price' =\u003e 50],\n] )-\u003ewhere( 'price', '\u003e', 20 );\n/*\n[\n    ['id' =\u003e 4, 'price' =\u003e 50]\n]\n*/\n\nMap::from( [\n  ['id' =\u003e 3, 'price' =\u003e 10],\n  ['id' =\u003e 4, 'price' =\u003e 50],\n] )-\u003ewhere( 'price', 'in', [10, 25] );\n/*\n[\n    ['id' =\u003e 3, 'price' =\u003e 10]\n]\n*/\n\nMap::from( [\n  ['id' =\u003e 3, 'price' =\u003e 10],\n  ['id' =\u003e 4, 'price' =\u003e 50],\n] )-\u003ewhere( 'price', '-', [10, 100] );\n/*\n[\n    ['id' =\u003e 3, 'price' =\u003e 10],\n    ['id' =\u003e 4, 'price' =\u003e 50]\n]\n*/\n\nMap::from( [\n  ['item' =\u003e ['id' =\u003e 3, 'price' =\u003e 10]],\n  ['item' =\u003e ['id' =\u003e 4, 'price' =\u003e 50]],\n] )-\u003ewhere( 'item/price', '\u003e', 30 );\n/*\n[\n    ['id' =\u003e 4, 'price' =\u003e 50]\n]\n*/\n```\n\n**See also:**\n\n* [filter()](#filter) - Runs a filter over each element of the map and returns a new map\n* [grep()](#grep) - Applies a regular expression to all elements\n\n\n### with()\n\nReturns a copy of the map with the element at the given index replaced with the given value.\n\n```php\npublic function with( $key, $value ) : self\n```\n\n* @param **int|string** `$key` Array key to set or replace\n* @param **mixed** `$value` New value for the given key\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map of the values\n\nThe original map stays untouched! This method is a shortcut for calling the\n[copy()](#copy) and [set()](#set) methods.\n\n**Examples:**\n\n```php\n$m = Map::from( ['a' =\u003e 1] );\n\n$m-\u003ewith( 2, 'b' );\n// ['a' =\u003e 1, 2 =\u003e 'b']\n\n$m-\u003ewith( 'a', 2 );\n// ['a' =\u003e 2]\n\n$m-\u003eall();\n// ['a' =\u003e 1]\n```\n\n**See also:**\n\n* [set()](#set) - Sets an element in the map by key without returning a new map\n\n\n### zip()\n\nMerges the values of all arrays at the corresponding index.\n\n```php\npublic function zip( $array1, ... ) : self\n```\n\n* @param **array\u0026#60;int\u0026#124;string,mixed\u0026#62;\u0026#124;\\Traversable\u0026#60;int\u0026#124;string,mixed\u0026#62;\u0026#124;\\Iterator\u0026#60;int\u0026#124;string,mixed\u0026#62;** `$array1` List of arrays to merge with at the same position\n* @return **self\u0026#60;int\u0026#124;string,mixed\u0026#62;** New map of arrays\n\n**Examples:**\n\n```php\nMap::from( [1, 2, 3] )-\u003ezip( ['one', 'two', 'three'], ['uno', 'dos', 'tres'] );\n/*\n[\n    [1, 'one', 'uno'],\n    [2, 'two', 'dos'],\n    [3, 'three', 'tres'],\n]\n*/\n```\n\n**See also:**\n\n* [combine()](#combine) - Combines the values of the map as keys with the passed elements as values\n\n\n\n## Custom methods\n\nMost of the time, it's enough to pass an anonymous function to the [pipe()](#pipe) method\nto implement custom functionality in map objects:\n\n```php\nMap::from( ['a', 'b'] )-\u003epipe( function( $map ) {\n    return strrev( $map-\u003ejoin( '-' ) );\n} );\n```\n\nIf you need some functionality more often and at different places in your source\ncode, than it's better to register a custom method once and only call it everywhere:\n\n```php\nMap::method( 'strrev', function( $sep ) {\n    return strrev( join( '-', $this-\u003elist() ) );\n} );\nMap::from( ['a', 'b'] )-\u003estrrev( '-' );\n```\n\nMake sure, you register the method before using it. You can pass arbitrary parameters\nto your function and it has access to the internas of the map. Thus, your function\ncan use `$this` to call all available methods:\n\n```php\nMap::method( 'notInBoth', function( iterable $elements ) {\n    return new self( $this-\u003ediff( $elements ) + Map::from( $elements )-\u003ediff( $this-\u003eitems ) );\n} );\n```\n\nYour custom method has access to `$this-\u003eitems` array which contains the map\nelements and can also use the internal `$this-\u003egetArray( iterable $list )` method to\nconvert iterable parameters (arrays, generators and objects implementing \\Traversable)\nto plain arrays:\n\n```php\nMap::method( 'mycombine', function( iterable $keys ) {\n    return new self( array_combine( $this-\u003egetArray( $keys ), $this-items ) );\n} );\n```\n\n\n\n## Performance\n\nThe performance most methods only depends on the array_* function that are used\ninternally by the Map class. If the methods of the Map class contains additional\ncode, it's optimized to be as fast as possible.\n\n### Creating Map vs. array\n\nCreating an map object with an array instead of creating a plain array only is\nsignificantly slower (ca. 10x) but in absolute values we are talking about nano\nseconds. It will only get notable if you create 10,000 map objects instead of\n10,000 arrays. Then, creating maps will last ca. 10ms longer.\n\nUsually, this isn't much of a problem because applications create arrays with\nlots of elements instead of 10,000+ arrays. Nevertheless, if your application\ncreates a very large number of arrays within one area, you should think about\navoiding map objects in that area.\n\nIf you use the [map()](#map-function) function or [Map::from()](#from) to create\nmap objects, then be aware that this adds another function call. Using these methods\nfor creating the map object lasts around 1.1x resp. 1.3x compared to the time for\n`new Map()`.\n\nConclusion: Using `new Map()` is fastest and `map()` is faster than `Map::from()`.\n\n### Populating Map vs. array\n\nAdding an element to a Map object using `$map[] = 'a'` is ca. 5x slower than\ndoing the same on a plain array. This is because the method [offsetSet()](#offsetset) will\nbe called instead of adding the new element to the array directly. This applies\nto the `$map-\u003epush( 'a' )` method too.\n\nWhen creating arrays in loops, you should populate the array first and then\ncreate a Map object from the the array:\n\n```php\n$list = [];\nfor( $i = 0; $i \u003c 1000; $i++ ) {\n\t$list[] = $i;\n}\n$map = map( $list );\n```\n\nThe array is **NOT** copied when creating the Map object so there's virtually no\nperformance loss using the Map afterwards.\n\n### Using Map methods vs. language constructs\n\nLanguage constructs such as `empty()`, `count()` or `isset()` are faster than\ncalling a method and using `$map-\u003eisEmpty()` or `$map-\u003ecount()` is ca. 4x\nslower.\n\nAgain, we are talking about nano seconds. For 10,000 calls to `empty( $array )`\ncompared to `$map-\u003eisEmpty()`, the costs are around 4ms in total.\n\n### Using Map methods vs. array_* functions\n\nUsing the Map methods instead of the array_* functions adds an additional method\ncall. Internally, the Map objects uses the same array_* functions but offers a\nmuch more usable interface.\n\nThe time for the additional method call is almost neglectable because the array_*\nmethods needs much longer to perform the operation on the array elements depending\non the size of the array.\n\n### Using anonymous functions\n\nSeveral Map methods support passing an anonymous function that is applied to\nevery element of the map. PHP needs some time to call the passed function and\nto execute its code. Depending on the number of elements, this may have a\nsignificant impact on performance!\n\nThe [pipe()](#pipe) method of the Map object is an exception because it receives the\nwhole map object instead of each element separately. Its performance mainly\ndepends on the implemented code:\n\n```php\n$map-\u003epipe( function( Map $map ) {\n\t// perform operations on the map\n} );\n```\n\n### Using shift() and unshift()\n\nBoth methods are costly, especially on large arrays. The used `array_shift()` and\n`array_unshift()` functions will reindex all numerical keys of the array.\n\nIf you want to reduce or create a large list of elements from the beginning in\nan iterative way, you should use [reverse()](#reverse) and [pop()](#pop)/[push()](#push)\ninstead of [shift()](#shift) and [unshift()](#unshift)/[prepend()](#prepend):\n\n```php\n$map-\u003ereverse()-\u003epop(); // use pop() until it returns NULL\n$map-\u003epush( 'z' )-\u003epush( 'y' )-\u003epush( 'x' )-\u003ereverse(); // use push() for adding\n```\n\n\n## Upgrade guide\n\n### 2.x -\u003e 3.x\n\n#### Use list() method\n\nWhen adding own methods to the Map object, don't access the `$this-\u003elist` class\nvariable directly. It's not guaranteed to be an array any more but will store\nthe value passed to the Map constructor. Instead, use the `list() method to get\na reference to the array of elements:\n\n```php\n$this-\u003elist();\n```\n\nAs it's a reference to the array of elements, you can modify it directly or even\nuse PHP functions that require a variable reference:\n\n```php\n$this-\u003elist()[] = 123;\nreset( $this-\u003elist() );\n```\n\n#### Renamed internal methods\n\nTwo internal methods have been renamed and you have to use their new name if you\nhave added own methods to the Map object:\n\n```php\n// instead of $this-\u003egetArray( $array )\n$this-\u003earray( $array )\n\n // instead of $this-\u003egetValue( $entry, array $parts )\n$this-\u003eval( $entry, array $parts )\n```\n\n### 1.x -\u003e 2.x\n\n#### jQuery style method calls\n\nYou can call methods of objects in a map like this:\n\n```php\n// MyClass implements setStatus() (returning $this) and getCode() (initialized by constructor)\n\n$map = Map::from( ['a' =\u003e new MyClass( 'x' ), 'b' =\u003e new MyClass( 'y' )] );\n$map-\u003esetStatus( 1 )-\u003egetCode()-\u003etoArray();\n```\n\nBefore, it was checked if the objects really implement `setStatus()` and `getCode()`.\n\nThis isn't the case any more to avoid returning an empty map if the method name is\nwrong or the called method is implemented using the `__call()` magic method. Now, PHP\ngenerates a fatal error if the method isn't implemented by all objects.\n\n#### Second equals() parameter\n\nThe second parameter of the [equals()](#equals) method (`$assoc`) to compare keys\ntoo has been removed. Use the [is()](#is) method instead:\n\n```php\n// 1.x\nmap( ['one' =\u003e 1] )-\u003eequals( ['one' =\u003e 1], true );\n\n// 2.x\nmap( ['one' =\u003e 1] )-\u003eis( ['one' =\u003e 1] );\n```\n\n#### New find() argument\n\nA default value or exception object can be passed to the [find()](#find) method now\nas second argument. The `$reverse` argument has been moved to the third position.\n\n```php\n// 1.x\nMap::from( ['a', 'c', 'e'] )-\u003efind( function( $value, $key ) {\n    return $value \u003e= 'b';\n}, true );\n\n// 2.x\nMap::from( ['a', 'c', 'e'] )-\u003efind( function( $value, $key ) {\n    return $value \u003e= 'b';\n}, null, true );\n```\n\n#### groupBy() semantic change\n\nIf the key passed to [groupBy()](#groupby) didn't exist, the items have been grouped\nusing the given key. Now, an empty string is used as key to offer easier checking and\nsorting of the keys.\n\n```php\nMap::from( [\n    10 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-abc'],\n] )-\u003egroupBy( 'xid' );\n\n// 1.x\n[\n    'xid' =\u003e [\n        10 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-abc']\n    ]\n]\n\n// 2.x\n[\n    '' =\u003e [\n        10 =\u003e ['aid' =\u003e 123, 'code' =\u003e 'x-abc']\n    ]\n]\n```\n\n#### offsetExists() semantic change\n\nTo be consistent with typical PHP behavior, the [offsetExists()](#offsetexists) method\nuse `isset()` instead of `array_key_exists()` now. This changes the behavior when dealing\nwith NULL values.\n\n```php\n$m = Map::from( ['foo' =\u003e null] );\n\n// 1.x\nisset( $m['foo'] ); // true\n\n// 2.x\nisset( $m['foo'] ); // false\n```\n\n#### Renamed split() method\n\nThe static `Map::split()` method has been renamed to [Map::explode()](#explode) and\nthe argument order has changed. This avoids conflicts with the Laravel split() method\nand is in line with the PHP `explode()` method.\n\n```php\n// 1.x\nMap::split( 'a,b,c', ',' );\n\n// 2.x\nMap::explode( ',', 'a,b,c' );\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faimeos%2Fmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faimeos%2Fmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faimeos%2Fmap/lists"}