A (Aja v0.4.3) View Source

Convenience macros to work with Aja's data structures.

Use import A to import everything, or import only the macros you need.

Link to this section Summary

Functions

Convenience macro to work with A.ExRanges (exclusive ranges).

Convenience macro to create or pattern match on A.OrdMaps.

A sigil to build IO data and avoid string concatenation.

Convenience macro to create or pattern match on A.Vectors.

Link to this section Functions

Convenience macro to work with A.ExRanges (exclusive ranges).

Use import A to use it, or import A, only: [~>: 2].

Examples

iex> 1 ~> 5
1 ~> 5
iex> start ~> stop = 0 ~> 10
iex> {start, stop}
{0, 10}
iex> for i <- 0 ~> 5, do: "id_#{i}"
["id_0", "id_1", "id_2", "id_3", "id_4"]

Convenience macro to create or pattern match on A.OrdMaps.

Use import A to use it, or import A, only: [ord: 1].

Creation examples

iex> ord(%{"一" => 1, "二" => 2, "三" => 3})
#A<ord(%{"一" => 1, "二" => 2, "三" => 3})>
iex> ord(%{a: "Ant", b: "Bat", c: "Cat"})
#A<ord(%{a: "Ant", b: "Bat", c: "Cat"})>

Pattern matching examples

iex> ord(%{b: bat}) = ord(%{a: "Ant", b: "Bat", c: "Cat"})
#A<ord(%{a: "Ant", b: "Bat", c: "Cat"})>
iex> bat
"Bat"

Replace existing keys examples

iex> ordered = ord(%{a: "Ant", b: "Bat", c: "Cat"})
iex> ord(%{ordered | b: "Buffalo"})
#A<ord(%{a: "Ant", b: "Buffalo", c: "Cat"})>
iex> ord(%{ordered | z: "Zebra"})
** (KeyError) key :z not found in: #A<ord(%{a: "Ant", b: "Bat", c: "Cat"})>
Link to this macro

sigil_i(term, modifiers)

View Source (macro)

A sigil to build IO data and avoid string concatenation.

Use import A to use it, or import A, only: [sigil_i: 2].

This sigil provides a faster version of string interpolation which:

  • will build a list with all chunks instead of concatenating them as a string
  • uses A.IO.to_iodata/1 on interpolated values instead of to_string/1, which:
    • will keep lists untouched, without any validation or transformation
    • will cast anything else using to_string/1

Works with both IO data and Chardata. See their respective documentation for more information.

Examples

iex> ~i"atom: #{:foo}, charlist: #{'abc'}, number: #{12 + 2.35}\n"
["atom: ", "foo", ", charlist: ", 'abc', ", number: ", "14.35", 10]
iex> ~i"abc#{['def' | "ghi"]}"
["abc", ['def' | "ghi"]]
iex> ~i"Giorno Giovanna"
"Giorno Giovanna"

IO data can often be used as is without ever generating the corresponding string. If needed however, IO data can be cast as a string using IO.iodata_to_binary/1, and chardata using List.to_string/1. In most cases, both should be the same:

iex> IO.iodata_to_binary(~i"atom: #{:foo}, charlist: #{'abc'}, number: #{12 + 2.35}\n")
"atom: foo, charlist: abc, number: 14.35\n"
iex> List.to_string(~i"abc#{['def' | "ghi"]}")
"abcdefghi"

Those are the exact same values returned by a regular string interpolation, without the ~i sigil:

iex> "atom: #{:foo}, charlist: #{'abc'}, number: #{12 + 2.35}\n"
"atom: foo, charlist: abc, number: 14.35\n"
iex> "abc#{['def' | "ghi"]}"
"abcdefghi"

Convenience macro to create or pattern match on A.Vectors.

It can only work with known-size vectors.

Examples

iex> import A
iex> vec([1, 2, 3])
#A<vec([1, 2, 3])>
iex> vec([1, 2, var, _, _, _]) = A.Vector.new(1..6)
#A<vec([1, 2, 3, 4, 5, 6])>
iex> var
3
iex> vec([_, _, _]) = A.Vector.new(1..6)
** (MatchError) no match of right hand side value: #A<vec([1, 2, 3, 4, 5, 6])>

It also supports ranges with constant values:

iex> vec(0..4) = A.Vector.new(0..4)
#A<vec([0, 1, 2, 3, 4])>
iex> vec(0~>8)
#A<vec([0, 1, 2, 3, 4, 5, 6, 7])>

Variable lists or dynamic ranges cannot be passed:

vec(my_list)  # invalid
vec(1..n)  # invalid

Explanation

The vec/1 macro generates the AST at compile time instead of building the vector at runtime. This can speedup the instanciation of vectors of known size.

iex> import A
iex> quote do vec([1, foo, _]) end |> Macro.expand(__ENV__) |> Macro.to_string()
"%A.Vector{internal: {3, {1, foo, _, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil}}}"