List_join

The list_join function can be used to group the elements of two arrays and categorize them into objects, based on an expression from each array.

Syntax

array list_join(array $leftArray, array $rightArray, &leftEvaluateBy, &rightEvaluateBy)

Groups the items of $leftArray and $rightArray base on the corresponding expressions (&leftEvaluateBy and &rightEvaluateBy) into an object. The collection of the generated objects is then enclosed in an array.

Parameters

$leftArray: One of the arrays that are to be joined.
$rightArray: The other array that will be joined with $leftArray.
&leftEvaluateBy: The expression that will be used for the evaluation of $leftArray.
&rightEvaluateBy: The expression that will be used for the evaluation of $rightArray.

Example

In the data set below, there are two arrays that will be joined using the list_join function. As it can be seen in the transformation block, the expressions that are used to evaluate each array are “id” and “Dep_id” respectively. Notice that the keys used for the expression don’t have to have the same name, as only their values are used for the evaluation.

{
    "Names": [
        {
            "id": 1,  //This will be used to evaluate the "Names" array
            "name": "James"
        },
        {
            "id": 2,
            "name": "John"
        },
        {
            "id": 2,
            "name": "Rita"
        },
        {
            "id": 3,
            "name": "Matilda"
        },
        {
            "id": 4,
            "name": "Alison"
        },
        {
            "id": 4,
            "name": "Alex"
        }
    ],
    "Team": [
        {
            "Dep_id": 1,  //This will be used to evaluate the "Team" array
            "Department": "HR"
        },
        {
            "Dep_id": 4,
            "Department": "Project Management"
        },
        {
            "Dep_id": 2,
            "Department": "Development"
        }
    ]
}

{
    LJ: list_join(Names, Team, &id, &Dep_id)
}

As seen in the output data below, the function returns a joined list of objects, where each object contains an index key, the entries from the $leftArray as well as the entries from the $rightArray that match the evaluation criteria.

In this case, all objects from the “Names” array ($leftArray) where the value of “id” is equal to the value of “Dep_id” (from the “Team” array) are collected in the “left” array of each object. Similarly, all objects from the “Team” array ($rightArray) where the “Dep_id” value matches the value of “id” from the “Names” array are gathered in the “right” array of each object.

{
    "LJ": [
        {
            "left": [  //Contains the items from the $leftArray for which the value of "id" is equal to the value of "Dep_id"
                {
                    "id": 1,
                    "name": "James"
                }
            ],
            "right": [  //Contains the items from the $rigthArray for which the value of "Dep_id" is equal to the value of "id"
                {
                    "Dep_id": 1,
                    "Department": "HR"
                }
            ],
            "__index": 0 //Key generated by function
        },
        {
            "left": [
                {
                    "id": 2,
                    "name": "John"
                },
                {
                    "id": 2,
                    "name": "Rita"
                }
            ],
            "right": [
                {
                    "Dep_id": 2,
                    "Department": "Development"
                }
            ],
            "__index": 1
        },
        {
            "left": [
                {
                    "id": 4,
                    "name": "Alison"
                },
                {
                    "id": 4,
                    "name": "Alex"
                }
            ],
            "right": [
                {
                    "Dep_id": 4,
                    "Department": "Project Management"
                }
            ],
            "__index": 2
        },
        {
            "left": [
                {
                    "id": 3,
                    "name": "Matilda"
                }
            ],
            "right": [], //No objects with matching id in the "Team" array
            "__index": 3
        }
    ]
}

The “__index” key, is generated by the function and it can be useful to target a particular object of the generated array.

As can be noticed in the generated array, in cases where objects from one of the original arrays can’t be matched to objects in the other, they are still displayed, but they are placed last. Naturally, one of the two arrays of the object (“left” or “right”) will be empty.