# `Localize.Inflection.SpeakableString`
[🔗](https://github.com/elixir-localize/localize/blob/v1.4.0/lib/localize/inflection/speakable_string.ex#L1)

A string with an optional distinct spoken form.

Most values are plain binaries where the printed and spoken forms
agree. When they differ (for example "boss’" printed but "boss’s"
spoken) the value is `{print, speak}`.

# `t`

```elixir
@type t() :: binary() | {binary(), binary()}
```

# `concat`

Concatenates two speakable strings.

### Arguments

* `left` is a speakable string.

* `right` is a speakable string.

### Returns

* The concatenated speakable string, collapsed to a binary when
  the printed and spoken forms agree.

* `{:error, exception}` if either argument is not a speakable string.

### Examples

    iex> Localize.Inflection.SpeakableString.concat("the ", "cat")
    "the cat"

    iex> Localize.Inflection.SpeakableString.concat({"boss’", "boss’s"}, " office")
    {"boss’ office", "boss’s office"}

# `new`

Builds a speakable string, collapsing to a binary when both forms
agree.

### Arguments

* `print` is the printed form.

* `speak` is the spoken form, or nil when it equals the printed
  form.

### Returns

* A speakable string.

### Examples

    iex> Localize.Inflection.SpeakableString.new("cat", "cat")
    "cat"

    iex> Localize.Inflection.SpeakableString.new("den", "dén")
    {"den", "dén"}

# `print`

Returns the printed form.

### Arguments

* `speakable` is a speakable string.

### Returns

* The printed form as a binary.

* `{:error, exception}` if `speakable` is not a speakable string.

### Examples

    iex> Localize.Inflection.SpeakableString.print("den")
    "den"

    iex> Localize.Inflection.SpeakableString.print({"den", "dén"})
    "den"

# `speak`

Returns the spoken form.

### Arguments

* `speakable` is a speakable string.

### Returns

* The spoken form as a binary; the printed form when no distinct
  spoken form exists.

* `{:error, exception}` if `speakable` is not a speakable string.

### Examples

    iex> Localize.Inflection.SpeakableString.speak("den")
    "den"

    iex> Localize.Inflection.SpeakableString.speak({"den", "dén"})
    "dén"

---

*Consult [api-reference.md](api-reference.md) for complete listing*