PHP - Ds Map::first() Function

The PHP Ds\Map::first() function is used to retrieve the first pair in a map. The pairs refer to the keys and values of the map elements. This function returns an array containing the first key-value pair of the map.

This function throws an UnderflowException if the current map is empty, indicating there is no elements to retrieve.

Syntax

Following is the syntax of the PHP Ds\Map::first() function −

public Ds\Map::first(): Ds\Pair

Parameters

This function does not accept any parameter.

Return value

This function returns the first pair in a map.

Example 1

The following program demonstrates the usage of the PHP Ds\Map::first() function −

<?php 
   $map = new \Ds\Map([10, 20, 30, 40]); 
   echo "The map elements are: \n";
   print_r($map);
   echo "The first pair of a map: \n";
   #using the first() function
   print_r($map->first()); 
?>

Output

After executing the above program, it will display the following output −

The map elements are:
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => 0
            [value] => 10
        )

    [1] => Ds\Pair Object
        (
            [key] => 1
            [value] => 20
        )

    [2] => Ds\Pair Object
        (
            [key] => 2
            [value] => 30
        )

    [3] => Ds\Pair Object
        (
            [key] => 3
            [value] => 40
        )

)
The first pair of a map:
Ds\Pair Object
(
    [key] => 0
    [value] => 10
)

Example 2

Following is another example of the Ds\Map::first() function. We use this function to retrieve the first pair of this map (["Tutorials", "Point", "India"]) −

<?php 
   $map = new \Ds\Map(["Tutorials", "Point", "India"]); 
   echo "The map elements are: \n";
   print_r($map);
   echo "The first pair of a map: \n";
   #using the first() function
   print_r($map->first()); 
?>

Output

The above program generates the following output −

The map elements are:
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => 0
            [value] => Tutorials
        )

    [1] => Ds\Pair Object
        (
            [key] => 1
            [value] => Point
        )

    [2] => Ds\Pair Object
        (
            [key] => 2
            [value] => India
        )

)
The first pair of a map:
Ds\Pair Object
(
    [key] => 0
    [value] => Tutorials
)

Example 3

If the current map is empty, this function throws an "UnderflowException".

<?php 
   $map = new \Ds\Map([]); 
   echo "The map elements are: \n";
   print_r($map);
   echo "The first pair of a map: \n";
   #using the first() function
   print_r($map->first()); 
?>

Output

Once the above program is executed, it generates the following output −

The map elements are:
Ds\Map Object
(
)
The first pair of a map:
PHP Fatal error:  Uncaught UnderflowException: 
Unexpected empty state in C:\Apache24\htdocs\index.php:7
Stack trace:
#0 C:\Apache24\htdocs\index.php(7): Ds\Map->first()
#1 {main}
  thrown in C:\Apache24\htdocs\index.php on line 7