A (Aja v0.5.1) 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 operator to concatenate an enumerable right to a vector left.

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

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

Returns the size of an ord_map.

A sigil to build IO data and avoid string concatenation.

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

Returns the size of a vector.

Link to this section Functions

Convenience operator to concatenate an enumerable right to a vector left.

left has to be an A.Vector, right can be any Enumerable.

It is just an alias for A.Vector.concat/2.

Only available on Elixir versions >= 1.11.

Examples

iex> import A
iex> vec(5..1) +++ vec([:boom, nil])
vec([5, 4, 3, 2, 1, :boom, nil])
iex> vec(5..1) +++ 0..3
vec([5, 4, 3, 2, 1, 0, 1, 2, 3])

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})
ord(%{"一" => 1, "二" => 2, "三" => 3})
iex> ord(%{a: "Ant", b: "Bat", c: "Cat"})
ord(%{a: "Ant", b: "Bat", c: "Cat"})

Pattern matching examples

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

Replace existing keys examples

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

ord_size(ord_map)

View Source (macro)

Returns the size of an ord_map.

It is implemented as a macro so that it can be used in guards.

When used outside of a guard, it will just be replaced by a call to A.OrdMap.size/1.

When used in guards, it will fail if called on something else than an A.OrdMap. It is recommended to verify the type first.

Runs in constant time.

Examples

iex> import A
iex> ord_map = A.OrdMap.new(a: 1, b: 2, c: 3)
iex> match?(v when ord_size(v) > 5, ord_map)
false
iex> match?(v when ord_size(v) < 5, ord_map)
true
iex> ord_size(ord_map)
3
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.

Examples

iex> import A
iex> vec([1, 2, 3])
vec([1, 2, 3])
iex> vec(first ||| last) = A.Vector.new(0..99_999); {first, last}
{0, 99999}
iex> vec([1, 2, var, _, _, _]) = A.Vector.new(1..6); var
3
iex> vec([_, _, _]) = A.Vector.new(1..6)
** (MatchError) no match of right hand side value: vec([1, 2, 3, 4, 5, 6])

It also supports ranges with constant values:

iex> vec(0..4) = A.Vector.new(0..4)
vec([0, 1, 2, 3, 4])
iex> vec(0~>8)
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.

Link to this macro

vec_size(vector)

View Source (macro)

Returns the size of a vector.

It is implemented as a macro so that it can be used in guards.

When used outside of a guard, it will just be replaced by a call to A.Vector.size/1.

When used in guards, it will fail if called on something else than an A.Vector. It is recommended to verify the type first.

Runs in constant time.

Examples

iex> import A
iex> match?(v when vec_size(v) > 20, A.Vector.new(1..10))
false
iex> match?(v when vec_size(v) < 5, A.Vector.new([1, 2, 3]))
true
iex> vec_size(A.Vector.new([1, 2, 3]))
3