# `Yex.Text`
[🔗](https://github.com/satoren/y_ex/blob/main/lib/shared_type/text.ex#L1)

A shareable type that is optimized for shared editing on text.
This module provides functionality for collaborative text editing with support for rich text formatting.

## Features
- Insert and delete text at any position
- Apply formatting attributes (bold, italic, etc.)
- Support for Quill Delta format for change tracking
- Collaborative editing with conflict resolution

# `delta`

```elixir
@type delta() ::
  [%{:insert => binary(), optional(:attributes) => map()}]
  | [%{delete: integer()}]
  | [%{:retain => integer(), optional(:attributes) => map()}]
```

# `t`

```elixir
@type t() :: %Yex.Text{doc: Yex.Doc.t(), reference: reference()}
```

# `apply_delta`

```elixir
@spec apply_delta(t(), delta()) :: :ok | :error
```

Transforms this type to a Quill Delta

## Examples Syncs two clients by exchanging the complete document structure
    iex> doc = Yex.Doc.new()
    iex> text = Yex.Doc.get_text(doc, "text")
    iex> delta = [%{ "retain" => 1}, %{ "delete" => 3}]
    iex> Yex.Text.insert(text,0, "12345")
    iex> Yex.Text.apply_delta(text,delta)
    iex> Yex.Text.to_delta(text)
    [%{insert: "15"}]

# `as_prelim`

```elixir
@spec as_prelim(t()) :: Yex.TextPrelim.t()
```

Converts the text object to its preliminary representation.
This is useful when you need to serialize or transfer the text content and formatting.

## Parameters
  * `text` - The text object to convert

# `delete`

```elixir
@spec delete(t(), integer(), integer()) :: :ok | :error
```

Deletes text content starting at the specified index.
Supports negative indices for deletion from the end.
Returns :ok on success, :error on failure.

## Parameters
  * `text` - The text object to modify
  * `index` - The starting position to delete from (0-based, negative indices count from end)
  * `length` - The number of characters to delete

# `format`

```elixir
@spec format(t(), integer(), integer(), map()) :: :ok | :error
```

Applies formatting attributes to a range of text.
Returns :ok on success, :error on failure.

## Parameters
  * `text` - The text object to modify
  * `index` - The starting position to format from (0-based)
  * `length` - The number of characters to format
  * `attr` - A map of formatting attributes to apply (e.g. %{"bold" => true})

# `insert`

```elixir
@spec insert(t(), integer(), binary()) :: :ok | :error
```

Inserts text content at the specified index.
Returns :ok on success, :error on failure.

## Parameters
  * `text` - The text object to modify
  * `index` - The position to insert at (0-based)
  * `content` - The text content to insert

# `insert`

```elixir
@spec insert(t(), integer(), binary(), map()) :: :ok | :error
```

Inserts text content with formatting attributes at the specified index.
Returns :ok on success, :error on failure.

## Parameters
  * `text` - The text object to modify
  * `index` - The position to insert at (0-based)
  * `content` - The text content to insert
  * `attr` - A map of formatting attributes to apply (e.g. %{"bold" => true})

# `insert_embed`

```elixir
@spec insert_embed(t(), integer(), Yex.input_type()) :: :ok | :error
```

Inserts an embed value at the specified index.
Returns :ok on success, :error on failure.

## Parameters
  * `text` - The text object to modify
  * `index` - The position to insert at (0-based)
  * `embed` - The embed value to insert (e.g. WeakPrelim, MapPrelim, ArrayPrelim)

# `insert_embed`

```elixir
@spec insert_embed(t(), integer(), Yex.input_type(), map()) :: :ok | :error
```

Inserts an embed value with formatting attributes at the specified index.
Returns :ok on success, :error on failure.

## Parameters
  * `text` - The text object to modify
  * `index` - The position to insert at (0-based)
  * `embed` - The embed value to insert
  * `attr` - A map of formatting attributes to apply (e.g. %{"bold" => true})

# `length`

```elixir
@spec length(t()) :: integer()
```

Returns the length of the text content in characters.

## Parameters
  * `text` - The text object to get the length of

# `quote`

```elixir
@spec quote(t(), integer(), integer()) :: Yex.WeakPrelim.t() | {:error, term()}
```

### ⚠️ Experimental
Returns [WeakPrelim] to a given range of elements, if it's in a boundaries of a current quotable collection.

# `to_delta`

```elixir
@spec to_delta(t()) :: delta()
```

Transforms this type to a Quill Delta

## Examples creates a few changes, then gets them back as a batch of change maps
    iex> doc = Yex.Doc.new()
    iex> text = Yex.Doc.get_text(doc, "text")
    iex> Yex.Text.insert(text, 0, "12345")
    iex> Yex.Text.insert(text, 0, "0", %{"bold" => true})
    iex> Yex.Text.to_delta(text)
    [%{insert: "0", attributes: %{"bold" => true}}, %{insert: "12345"}]

# `to_string`

```elixir
@spec to_string(t()) :: binary()
```

Returns the text content as a string.

## Parameters
  * `text` - The text object to convert to string

---

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