# Merge Verbs

Sometimes you'd like to merge two collections into one. There are a few ways of doing that in this library.

## Concat¶

If you just want to stack collections on top
of each other, you can use `concat`

for that. It's
short for "concatenate".

```
from clumper import Clumper
c1 = Clumper([{"a": 1}])
c2 = Clumper([{"a": 2}])
c3 = Clumper([{"a": 3}])
assert len(c1.concat(c2)) == 2
assert len(c1.concat(c2, c3)) == 3
assert len(c1.concat(c2).concat(c3)) == 3
```

## Joins¶

If you want to merge two collections together based on
the values then you'd be interested in a `join`

. When doing a join there are two sets: a leftset and a right set.
Depending on the type of join that you are performing you will
get different behavior.

### Left Join¶

A left join keeps all the values from the left table even when there's nothing from the right table that it can join on.

```
from clumper import Clumper
left = Clumper([
{"a": 1, "b": 4},
{"a": 2, "b": 6},
{"a": 3, "b": 8},
])
right = Clumper([
{"c": 9, "b": 4},
{"c": 8, "b": 5},
{"c": 7, "b": 6},
])
result = left.inner_join(right, mapping={"b": "b"})
expected = [
{"a": 1, "b": 4, "c": 9},
{"a": 2, "b": 6, "c": 7},
{"a": 3, "b": 8},
]
assert result.equals(expected)
```

Note that items on the left hand side may appear multiple times.

```
from clumper import Clumper
left = Clumper([
{"a": 1, "b": 4},
{"a": 2, "b": 6},
{"a": 3, "b": 8},
])
right = Clumper([
{"c": 9, "b": 4},
{"c": 8, "b": 5},
{"c": 7, "b": 6},
{"c": 9, "b": 6},
])
result = left.left_join(right, mapping={"b": "b"})
expected = [
{'a': 1, 'b': 4, 'c': 9},
{'a': 2, 'b': 6, 'c': 7},
{'a': 2, 'b': 6, 'c': 9},
{'a': 3, 'b': 8}
]
assert result.equals(expected)
```

### Right Join¶

This is not implemented. You can swap the left/right tables and still use the left-join for this.

### Inner Join¶

An inner join only keeps items that can be paired in both tables.

```
from clumper import Clumper
left = Clumper([
{"a": 1, "b":4},
{"a": 2, "b":6},
{"a": 3, "b":8},
])
right = Clumper([
{"c": 9, "b":4},
{"c": 8, "b":5},
{"c": 7, "b":6},
])
result = left.inner_join(right, mapping={"b": "b"})
expected = [
{"a": 1, "b": 4, "c": 9},
{"a": 2, "b": 6, "c": 7},
]
assert result.equals(expected)
```