---
name: join
signature: 'join EXPR, LIST'
status: documented
categories: ["Lists"]
---

```{index} single: join; Perl built-in
```

*[Lists](../perlfunc-by-category)*

# join

Concatenate a list of strings with a separator between each adjacent
pair, and return the single resulting string.

`join` takes a separator as its first argument and any number of
values as the rest. It stringifies every value in `LIST`, glues them
together with `EXPR` placed between each pair, and returns one scalar.
The separator is inserted **between** items only — never at the start,
never at the end. With zero or one items the separator never appears
at all.

## Synopsis

```perl
join $sep, @list
join "", @chars
join "\n", @lines
```

## What you get back

A single string. The result is a fresh scalar; modifying it does not
reach back into `LIST`. In scalar context you get that string; `join`
is effectively always scalar because it only ever produces one value.

## Examples

Comma-separated values, the canonical use:

```perl
my @cols = ("alice", 42, "ops");
my $row  = join ",", @cols;         # "alice,42,ops"
```

Build a file path with `/` as the separator:

```perl
my @parts = ("var", "log", "app.log");
my $path  = "/" . join("/", @parts);  # "/var/log/app.log"
```

Join lines with a newline between each — note that the trailing line
does **not** get a newline, because `join` puts the separator *between*
items:

```perl
my @lines = ("first", "second", "third");
my $text  = join "\n", @lines;      # "first\nsecond\nthird"
```

No-separator concatenation. Use the empty string `""`, not [`undef`](undef) —
[`undef`](undef) triggers an uninitialized warning under `use warnings` and
stringifies to `""` anyway:

```perl
my @chars = ("h", "e", "l", "l", "o");
my $word  = join "", @chars;        # "hello"
```

An empty `LIST` yields an empty string — this is safe to rely on and
needs no guard:

```perl
my @empty;
my $s = join ",", @empty;           # ""
```

## Edge cases

- **Empty `LIST`**: returns `""`. The separator is never used.
- **Single-item `LIST`**: returns that item stringified, with no
  separator anywhere: `join ",", ("only")` is `"only"`.
- **Separator is stringified**: pass a number, a reference, an object
  with overloaded `""` — `join` calls the same stringification every
  other Perl operator would. `join 0, 1, 2, 3` is `"10203"`.
- **Multi-character separator**: `EXPR` can be any string, not just a
  single character. `join ", ", @cols` gives `"a, b, c"`.
- **[`undef`](undef) items in `LIST`**: each [`undef`](undef) stringifies to `""` and
  emits an `uninitialized` warning under `use warnings`. Two adjacent
  [`undef`](undef)s still get a separator between them:
  `join ",", (undef, undef)` is `","`.
- **`join` is not the inverse of [`split`](split) on a single character** when
  the separator you pass differs from the pattern used to split. [`split`](split)
  takes a *pattern*; `join` takes a literal string. Round-tripping
  `join "\t", split /\s+/, $s` loses the distinction between runs of
  whitespace and a single tab.
- **Not a pattern**: unlike [`split`](split), the first argument to
  `join` is not a regex. `join /,/, @x` is a syntax surprise — the
  separator is always a string.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`split`](split) — the inverse: take a string and a pattern, return
  a list of pieces
- [`sprintf`](sprintf) — when you need per-item formatting, padding,
  or field widths that `join` can't express
- [`pack`](pack) — when the output is a binary record, not a
  separator-delimited text string
- [`map`](map) — transform items before joining, e.g.
  `join ",", map { uc } @names`