Yex.Map (y_ex v0.7.3)

View Source

A shareable Map type that supports concurrent modifications with automatic conflict resolution. This module provides functionality for collaborative key-value pair management with support for nested shared types and JSON compatibility.

Features

  • Concurrent modifications with automatic conflict resolution
  • Support for nested shared types (Array, Text, Map)
  • JSON-compatible serialization
  • Key-value pair management with atomic operations
  • Observable changes for real-time collaboration

Summary

Functions

Converts the map to its preliminary representation. This is useful when you need to serialize or transfer the map's contents.

Deletes a key from the map. Returns :ok on success, :error on failure.

Retrieves a value by key from the map. Returns {:ok, value} if found, :error if not found.

Similar to fetch/2 but raises ArgumentError if the key is not found.

get(map, key) deprecated

get a key from the map. ## Examples

Checks if a key exists in the map. Returns true if the key exists, false otherwise.

Sets a key-value pair in the map. Returns :ok on success, :error on failure.

Returns the number of key-value pairs in the map.

Converts the map to a JSON-compatible format. This is useful for serialization or when you need to transfer the map's contents.

Converts the map to a list of key-value tuples.

Converts the map to a standard Elixir map. This is useful when you need to work with the map's contents in a non-collaborative context.

Types

t()

@type t() :: %Yex.Map{doc: Yex.Doc.t(), reference: reference()}

Functions

as_prelim(map)

@spec as_prelim(t()) :: Yex.MapPrelim.t()

Converts the map to its preliminary representation. This is useful when you need to serialize or transfer the map's contents.

Parameters

  • map - The map to convert

delete(map, key)

@spec delete(t(), term()) :: :ok

Deletes a key from the map. Returns :ok on success, :error on failure.

Parameters

  • map - The map to modify
  • key - The key to delete

Examples

iex> doc = Yex.Doc.new()
iex> map = Yex.Doc.get_map(doc, "map")
iex> Yex.Map.set(map, "plane", ["Hello", "World"])
iex> Yex.Map.delete(map, "plane")
:ok

fetch(map, key)

@spec fetch(t(), binary()) :: {:ok, term()} | :error

Retrieves a value by key from the map. Returns {:ok, value} if found, :error if not found.

Parameters

  • map - The map to query
  • key - The key to look up

Examples

iex> doc = Yex.Doc.new()
iex> map = Yex.Doc.get_map(doc, "map")
iex> Yex.Map.set(map, "plane", ["Hello", "World"])
iex> Yex.Map.fetch(map, "plane")
{:ok, ["Hello", "World"]}
iex> Yex.Map.fetch(map, "not_found")
:error

fetch!(map, key)

@spec fetch!(t(), binary()) :: term()

Similar to fetch/2 but raises ArgumentError if the key is not found.

Parameters

  • map - The map to query
  • key - The key to look up

Raises

  • ArgumentError - If the key is not found

get(map, key)

This function is deprecated. Rename to `fetch/2`.
@spec get(t(), binary()) :: {:ok, term()} | :error

get a key from the map. ## Examples

iex> doc = Yex.Doc.new()
iex> map = Yex.Doc.get_map(doc, "map")
iex> Yex.Map.set(map, "plane", ["Hello", "World"])
iex> Yex.Map.get(map, "plane")
{:ok, ["Hello", "World"]}
iex> Yex.Map.get(map, "not_found")
:error

has_key?(map, key)

@spec has_key?(t(), binary()) :: boolean()

Checks if a key exists in the map. Returns true if the key exists, false otherwise.

Parameters

  • map - The map to check
  • key - The key to look for

set(map, key, content)

@spec set(t(), term(), term()) :: term()

Sets a key-value pair in the map. Returns :ok on success, :error on failure.

Parameters

  • map - The map to modify
  • key - The key to set
  • content - The value to associate with the key

Examples

iex> doc = Yex.Doc.new()
iex> map = Yex.Doc.get_map(doc, "map")
iex> Yex.Map.set(map, "plane", ["Hello", "World"])
:ok

size(map)

@spec size(t()) :: integer()

Returns the number of key-value pairs in the map.

to_json(map)

@spec to_json(t()) :: map()

Converts the map to a JSON-compatible format. This is useful for serialization or when you need to transfer the map's contents.

Examples

iex> doc = Yex.Doc.new()
iex> map = Yex.Doc.get_map(doc, "map")
iex> Yex.Map.set(map, "array", Yex.ArrayPrelim.from(["Hello", "World"]))
iex> Yex.Map.set(map, "plane", ["Hello", "World"])
iex> assert %{"plane" => ["Hello", "World"], "array" => ["Hello", "World"]} = Yex.Map.to_json(map)

to_list(map)

@spec to_list(t()) :: list()

Converts the map to a list of key-value tuples.

to_map(map)

@spec to_map(t()) :: map()

Converts the map to a standard Elixir map. This is useful when you need to work with the map's contents in a non-collaborative context.

Examples

iex> doc = Yex.Doc.new()
iex> map = Yex.Doc.get_map(doc, "map")
iex> Yex.Map.set(map, "array", Yex.ArrayPrelim.from(["Hello", "World"]))
iex> Yex.Map.set(map, "plane", ["Hello", "World"])
iex> assert %{"plane" => ["Hello", "World"], "array" => %Yex.Array{}} = Yex.Map.to_map(map)