Доступ поведение

Базовый доступ к структурам данных с использованием синтаксиса data[key].

Elixir предоставляет два синтаксиса для доступа к значениям. user[:name] используется для динамических структур, таких как карты и ключевые слова, в то время как user.name используется для структур. Основное различие состоит в том, что user[:name] не сгенерирует ошибку, если ключ :name отсутствует, но user.name сгенерирует ошибку, если ключа :name нет.

Помимо вышеперечисленных случаев, этот модуль предоставляет удобные функции для доступа к другим структурам, например, at/1 для списков и elem/1 для кортежей. Эти функции могут быть использованы функциями вложенного обновления в Kernel, такие как Kernel.get_in/2, Kernel.put_in/3, Kernel.update_in/3, Kernel.get_and_update_in/3 и аналогичные.

Динамический доступ

Из коробки Access работает с Keyword и Map:

iex> keywords = [a: 1, b: 2]
iex> keywords[:a]
1

iex> map = %{a: 1, b: 2}
iex> map[:a]
1

iex> star_ratings = %{1.0 => "★", 1.5 => "★☆", 2.0 => "★★"}
iex> star_ratings[1.5]
"★☆"

Обратите внимание, что синтаксис динамического доступа (term[key]) примерно соответствует Access.get(term, key, nil).

Access можно комбинировать с Kernel.put_in/3 для добавления значения в указанный ключ:

iex> map = %{a: 1, b: 2}
iex> put_in map[:a], 3
%{a: 3, b: 2}

Этот синтаксис очень удобен, так как его можно вложенно использовать:

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> put_in users["john"][:age], 28
%{"john" => %{age: 28}, "meg" => %{age: 23}}

Кроме того, Access прозрачно игнорирует nil значения:

iex> keywords = [a: 1, b: 2]
iex> keywords[:c][:unknown]
nil

Поскольку Access — это поведение, оно может быть реализовано для структур данных ключ-значение. Реализация должна быть добавлена в модуль, который определяет структуру, к которой осуществляется доступ. Access требует реализации сравнения ключей с использованием оператора ===.

Статический доступ

Синтаксис Access (data[key]) не может использоваться для доступа к полям в структурах, так как структуры по умолчанию не реализуют поведение Access. Это также является дизайнерским решением: динамический доступ предназначен для использования с динамическими структурами ключ-значение, такими как карты и ключевые слова, а не со статическими, такими как структуры (где поля известны и не являются динамическими).

Поэтому Elixir предоставляет статический доступ к полям структур и полям атомов в картах. Представьте структуру с именем User с полем :name. Следующее приведет к ошибке:

user = %User{name: "John"}
user[:name]
# ** (UndefinedFunctionError) undefined function User.fetch/2 (User does not implement the Access behaviour)

Вместо этого структуры используют синтаксис user.name для доступа к полям:

user.name
#=> "John"

Тот же синтаксис user.name также может использоваться с Kernel.put_in/2 для обновления полей структур:

put_in user.name, "Mary"
#=> %User{name: "Mary"}

В отличие от user[:name], user.name не является расширяемым через поведение и ограничен только структурами и атомными ключами в картах.

Как упоминалось выше, это также работает для атомных ключей в картах. Для получения дополнительной информации обратитесь к модулю Map.

Подводя итог:

• user[:name] используется для динамических структур, расширяем и не генерирует ошибку при отсутствии ключа
• user.name используется для статических структур, не расширяем и генерирует ошибку при отсутствии ключа

Доступные функции

Хотя Elixir предоставляет встроенный синтаксис только для обхода динамических и статических структур ключ-значение, этот модуль предоставляет удобные функции для обхода других структур, таких как кортежи и списки, которые можно использовать вместе с Kernel.put_in/2 в других.

Например, задана карта пользователя с ключами :name и :languages, вот как можно глубоко пройтись по карте и преобразовать все имена языков в верхний регистр:

iex> languages = [
...>   %{name: "elixir", type: :functional},
...>   %{name: "c", type: :procedural},
...> ]
iex> user = %{name: "john", languages: languages}
iex> update_in user, [:languages, Access.all(), :name], &String.upcase/1
%{name: "john",
  languages: [%{name: "ELIXIR", type: :functional},
              %{name: "C", type: :procedural}]}

См. функции key/1, key!/1, elem/1 и all/0 для некоторых доступных функций.

Реализация поведения Access для пользовательских структур данных

Для использования поведения Access с пользовательскими структурами данных (которые должны быть структурами), такие структуры должны реализовывать поведение Access. Например, для структуры User это необходимо сделать:

defmodule User do
  defstruct [:name, :email]

  @behaviour Access
  # Implementation of the Access callbacks...
end

Резюме

Типы

access_fun(data, get_value)

any_container()

container()

get_and_update_fun(data, get_value)

get_fun(data, get_value)

key()

nil_container()

t()

value()

Функции

all()

Возвращает функцию, которая обращается ко всем элементам списка.

at(индекс)

Возвращает функцию, которая обращается к элементу по индексу index (нумерация с нуля) списка.

elem(индекс)

Возвращает функцию, которая обращается к элементу по заданному индексу в кортеже.

fetch(контейнер, ключ)

Извлекает значение для данного ключа в контейнере (карта, список ключевых слов или структура, реализующая поведение Access).

get(контейнер, ключ, по-умолчанию \\ nil)

Получает значение для данного ключа в контейнере (карта, список ключевых слов или структура, реализующая поведение Access).

get_and_update(контейнер, ключ, функция)

Получает и обновляет данный ключ в container (карта, список ключевых слов, структура, реализующая поведение Access).

key(ключ, по-умолчанию \\ nil)

Возвращает функцию, которая обращается к заданному ключу в карте/структуре.

key!(ключ)

Возвращает функцию, которая обращается к заданному ключу в карте/структуре.

pop(контейнер, ключ)

Удаляет запись с заданным ключом из контейнера (карта, список ключевых слов или структура, реализующая поведение Access).

Обработчики

fetch(элемент, ключ)

Вызывается для доступа к значению, хранящемуся по ключу key в данном элементе term.

get(элемент, ключ, по-умолчанию)

Вызывается для доступа к значению, хранящемуся по ключу key в данном элементе term, возвращая значение по умолчанию default, если оно отсутствует.

get_and_update(данные, ключ, функция)

Вызывается для доступа к значению по ключу key и одновременного обновления.

pop(данные, ключ)

Вызывается для удаления значения по ключу key из структуры данных.

Типы

access_fun(data, get_value)

access_fun(data, get_value) ::
  get_fun(data, get_value) |
  get_and_update_fun(data, get_value)

any_container()

any_container() :: any()

container()

container() :: keyword() | struct() | map()

get_and_update_fun(data, get_value)

get_and_update_fun(data, get_value) :: (:get_and_update, data, (term() -> term()) -> {get_value, new_data :: container()} | :pop)

get_fun(data, get_value)

get_fun(data, get_value) :: (:get, data, (term() -> term()) -> {get_value, new_data :: container()})

key()

key() :: any()

nil_container()

nil_container() :: nil

t()

t() :: container() | nil_container() | any_container()

value()

value() :: any()

Функции

all()

all() :: access_fun(data :: list(), get_value :: list())

Возвращает функцию, которая обращается ко всем элементам списка.

Возвращаемая функция обычно передаётся в качестве функции доступа к Kernel.get_in/2, Kernel.get_and_update_in/3 и аналогичным функциям.

Примеры

iex> list = [%{name: "john"}, %{name: "mary"}]
iex> get_in(list, [Access.all(), :name])
["john", "mary"]
iex> get_and_update_in(list, [Access.all(), :name], fn
...>   prev -> {prev, String.upcase(prev)}
...> end)
{["john", "mary"], [%{name: "JOHN"}, %{name: "MARY"}]}
iex> pop_in(list, [Access.all(), :name])
{["john", "mary"], [%{}, %{}]}

Вот пример, который проходит по списку, удаляет чётные числа и умножает нечётные на 2:

iex> require Integer
iex> get_and_update_in([1, 2, 3, 4, 5], [Access.all], fn
...>   num -> if Integer.is_even(num), do: :pop, else: {num, num * 2}
...> end)
{[1, 2, 3, 4, 5], [2, 6, 10]}

Если доступная структура не является списком, возникает ошибка:

iex> get_in(%{}, [Access.all()])
** (RuntimeError) Access.all/0 expected a list, got: %{}

at(индекс)

at(non_neg_integer()) :: access_fun(data :: list(), get_value :: term())

Возвращает функцию, которая обращается к элементу по индексу index (нумерация с нуля) списка.

Возвращаемая функция обычно передаётся в качестве функции доступа к Kernel.get_in/2, Kernel.get_and_update_in/3 и аналогичным функциям.

Примеры

iex> list = [%{name: "john"}, %{name: "mary"}]
iex> get_in(list, [Access.at(1), :name])
"mary"
iex> get_and_update_in(list, [Access.at(0), :name], fn
...>   prev -> {prev, String.upcase(prev)}
...> end)
{"john", [%{name: "JOHN"}, %{name: "mary"}]}

at/1 также может использоваться для удаления элементов из списка или ключей внутри списка:

iex> list = [%{name: "john"}, %{name: "mary"}]
iex> pop_in(list, [Access.at(0)])
{%{name: "john"}, [%{name: "mary"}]}
iex> pop_in(list, [Access.at(0), :name])
{"john", [%{}, %{name: "mary"}]}

Если индекс выходит за пределы границ, возвращается значение nil, и функция обновления не вызывается:

iex> list = [%{name: "john"}, %{name: "mary"}]
iex> get_in(list, [Access.at(10), :name])
nil
iex> get_and_update_in(list, [Access.at(10), :name], fn
...>   prev -> {prev, String.upcase(prev)}
...> end)
{nil, [%{name: "john"}, %{name: "mary"}]}

Для отрицательных индексов возникает ошибка:

iex> get_in([], [Access.at(-1)])
** (FunctionClauseError) no function clause matching in Access.at/1

Если доступная структура не является списком, возникает ошибка:

iex> get_in(%{}, [Access.at(1)])
** (RuntimeError) Access.at/1 expected a list, got: %{}

elem(индекс)

elem(non_neg_integer()) :: access_fun(data :: tuple(), get_value :: term())

Возвращает функцию, которая обращается к элементу по заданному индексу в кортеже.

Возвращаемая функция обычно передается в качестве аксессора к Kernel.get_in/2, Kernel.get_and_update_in/3 и подобным функциям.

Возвращаемая функция вызывает исключение, если index находится за пределами границ.

Примеры

iex> map = %{user: {"john", 27}}
iex> get_in(map, [:user, Access.elem(0)])
"john"
iex> get_and_update_in(map, [:user, Access.elem(0)], fn
...>   prev -> {prev, String.upcase(prev)}
...> end)
{"john", %{user: {"JOHN", 27}}}
iex> pop_in(map, [:user, Access.elem(0)])
** (RuntimeError) cannot pop data from a tuple

Возникает ошибка, если доступная структура не является кортежем:

iex> get_in(%{}, [Access.elem(0)])
** (RuntimeError) Access.elem/1 expected a tuple, got: %{}

fetch(контейнер, ключ)

fetch(container(), term()) :: {:ok, term()} | :error

fetch(nil_container(), any()) :: :error

Извлекает значение по заданному ключу в контейнере (карта, список ключевых слов или структура, реализующая поведение Access).

Возвращает {:ok, value}, где value — значение по ключу key, если такой ключ существует, или :error, если key не найден.

get(контейнер, ключ, значение_по_умолчанию \\ nil)

get(container(), term(), term()) :: term()

get(nil_container(), any(), default) :: default when default: var

Получает значение по заданному ключу в контейнере (карта, список ключевых слов или структура, реализующая поведение Access).

Возвращает значение по ключу key, если такой ключ существует, или default, если key не найден.

get_and_update(контейнер, ключ, функция)

get_and_update(data, key(), (value() -> {get_value, value()} | :pop)) :: {get_value, data} when data: container(), get_value: var

Получает и обновляет заданный ключ в container (карта, список ключевых слов, структура, реализующая поведение Access).

Аргумент fun получает значение по ключу key (или nil, если key отсутствует в container). Он должен вернуть кортеж из двух элементов {get_value, update_value}: значение «get» get_value (извлеченное значение, с которым можно выполнить операции перед возвращением) и новое значение, которое будет сохранено по ключу key (update_value). fun также может вернуть :pop, что означает, что текущее значение должно быть удалено из контейнера и возвращено.

Возвращаемое значение — кортеж из двух элементов: значение «get», возвращенное функцией fun, и новый контейнер с обновлённым значением по ключу key.

key(ключ, значение_по_умолчанию \\ nil)

key(key(), term()) :: access_fun(data :: struct() | map(), get_value :: term())

Возвращает функцию, которая обращается к заданному ключу в карте/структуре.

Возвращаемая функция обычно передается в качестве аксессора к Kernel.get_in/2, Kernel.get_and_update_in/3 и аналогичным функциям.

Возвращаемая функция использует значение по умолчанию, если ключ не существует. Это позволяет задавать значения по умолчанию и безопасно обрабатывать отсутствующие ключи:

iex> get_in(%{}, [Access.key(:user, %{}), Access.key(:name)])
nil

Это также полезно при использовании функций обновления, позволяя нам вводить значения по мере обхода структуры данных для обновлений:

iex> put_in(%{}, [Access.key(:user, %{}), Access.key(:name)], "Mary")
%{user: %{name: "Mary"}}

Примеры

iex> map = %{user: %{name: "john"}}
iex> get_in(map, [Access.key(:unknown, %{}), Access.key(:name, "john")])
"john"
iex> get_and_update_in(map, [Access.key(:user), Access.key(:name)], fn
...>   prev -> {prev, String.upcase(prev)}
...> end)
{"john", %{user: %{name: "JOHN"}}}
iex> pop_in(map, [Access.key(:user), Access.key(:name)])
{"john", %{user: %{}}}

Если доступная структура не является картой или структурой, возникает ошибка:

iex> get_in(nil, [Access.key(:foo)])
** (BadMapError) expected a map, got: nil

iex> get_in([], [Access.key(:foo)])
** (BadMapError) expected a map, got: []

key!(ключ)

key!(key()) :: access_fun(data :: struct() | map(), get_value :: term())

Возвращает функцию, которая обращается к заданному ключу в карте/структуре.

Возвращаемая функция обычно передается в качестве аксессора к Kernel.get_in/2, Kernel.get_and_update_in/3 и аналогичным функциям.

Возвращаемая функция вызывает исключение, если ключ не существует.

Примеры

iex> map = %{user: %{name: "john"}}
iex> get_in(map, [Access.key!(:user), Access.key!(:name)])
"john"
iex> get_and_update_in(map, [Access.key!(:user), Access.key!(:name)], fn
...>   prev -> {prev, String.upcase(prev)}
...> end)
{"john", %{user: %{name: "JOHN"}}}
iex> pop_in(map, [Access.key!(:user), Access.key!(:name)])
{"john", %{user: %{}}}
iex> get_in(map, [Access.key!(:user), Access.key!(:unknown)])
** (KeyError) key :unknown not found in: %{name: "john"}

Если доступная структура не является картой/структурой, возникает ошибка:

iex> get_in([], [Access.key!(:foo)])
** (RuntimeError) Access.key!/1 expected a map/struct, got: []

pop(контейнер, ключ)

pop(data, key()) :: {value(), data} when data: container()

Удаляет запись с заданным ключом из контейнера (карта, список ключевых слов или структура, реализующая поведение Access).

Возвращает кортеж, содержащий значение, связанное с ключом, и обновленный контейнер. nil возвращается для значения, если ключ не находится в контейнере.

Примеры

С картой:

iex> Access.pop(%{name: "Elixir", creator: "Valim"}, :name)
{"Elixir", %{creator: "Valim"}}

Список ключевых слов:

iex> Access.pop([name: "Elixir", creator: "Valim"], :name)
{"Elixir", [creator: "Valim"]}

Неизвестный ключ:

iex> Access.pop(%{name: "Elixir", creator: "Valim"}, :year)
{nil, %{creator: "Valim", name: "Elixir"}}

Обработчики событий

fetch(элемент, ключ)

fetch(term :: t(), key()) :: {:ok, value()} | :error

Вызывается для доступа к значению, хранящемуся по ключу key в заданном элементе term.

Эта функция должна вернуть {:ok, value}, где value — значение по ключу key, если ключ существует в элементе, или :error, если ключ не существует в элементе.

Многие функции, определенные в модуле Access, внутренне вызывают эту функцию. Эта функция также используется при использовании синтаксиса доступа с квадратными скобками (structure[key]). Вызывается обработчик fetch/2, реализованный в модуле, который определяет структуру structure, и если он возвращает {:ok, value}, возвращается value, или если он возвращает :error, возвращается nil.

См. реализации Map.fetch/2 и Keyword.fetch/2 для примеров реализации этого обработчика.

get(элемент, ключ, значение_по_умолчанию)

get(term :: t(), key(), default :: value()) :: value()

Вызывается для доступа к значению по ключу key в заданном элементе term, используя значение по умолчанию default, если ключ отсутствует.

Функция должна вернуть значение по ключу key в term, если такой ключ существует, в противном случае default.

Для большинства структур данных это можно реализовать, используя fetch/2 внутри; например:

def get(structure, key, default) do
  case fetch(structure, key) do
    {:ok, value} -> value
    :error       -> default
  end
end

См. реализации Map.get/3 и Keyword.get/3 для примеров реализации этого обработчика.

get_and_update(данные, ключ, функция)

get_and_update(data, key(), (value() -> {get_value, value()} | :pop)) :: {get_value, data} when data: container() | any_container(), get_value: var

Вызывается для доступа к значению по ключу key и одновременного обновления.

Реализация этого обработчика должна вызвать fun со значением по ключу key в переданной структуре data, или со значением nil, если key отсутствует в ней. Эта функция должна вернуть либо {get_value, update_value}, либо :pop.

Если переданная функция возвращает {get_value, update_value}, возвращаемое значение этого обработчика должно быть {get_value, new_data}, где:

• get_value — полученное значение (с которым можно выполнить операции перед возвращением)
• update_value — новое значение, которое нужно сохранить по ключу key
• new_data — data после обновления значения по ключу key значением update_value.

Если переданная функция возвращает :pop, возвращаемое значение этого обработчика должно быть {value, new_data}, где value — значение по ключу key (или nil, если он отсутствует), а new_data — data без key.

См. реализации Map.get_and_update/3 или Keyword.get_and_update/3 для получения дополнительных примеров.

pop(данные, ключ)

pop(data, key()) :: {value(), data} when data: container() | any_container()

Вызывается для «удаления» значения по ключу key из заданной структуры данных.

Если key существует в заданной структуре data, реализация должна вернуть кортеж {value, new_data}, где value — значение, которое было по ключу key, а new_data — term без key.

Если key не существует в заданной структуре, должен быть возвращён кортеж {value, data}, где value — значение, определяемое реализацией.

См. реализации Map.pop/3 или Keyword.pop/3 для получения дополнительных примеров.