@spec contains?(t(), term()) :: boolean()

Returns true when the value is one of the alternatives of the union.

Lists, ranges and contexts use their component unions, including their explicit null alternatives. Functions use observable projected arrows and ignore call refinements for membership. This asks about the analysis representation; use Feel.Type.value_conforms?/2 with the original declaration for complete guarded recursive data membership and retained runtime signature checks. Any term may be asked about, since a binding is the host's: one that is not a FEEL value is in the union only through Any.

iex> Feel.Type.Union.contains?([:number, :null], nil)
true
iex> Feel.Type.Union.contains?([:number], nil)
false
iex> Feel.Type.Union.contains?([:number, :string], "a")
true
iex> Feel.Type.Union.contains?([:any], %{"a" => 1})
true

@spec difference(t(), [member()]) :: [member()]

The values that are in the first union and not in the second: a union that holds every value that is, and as few others as it can say (D-39).

:any is taken apart into its kinds (tops/0), and each alternative loses what the second union has of its kind: the numbers, the strings, the booleans, the dates and the durations by their sets, and a kind that has no sets (a list, a range, a context, a function) all of it or none, by subtype?/2. A time and a date and time lose the lines of a set (Feel.Type.Moment.complement/2, D-152): what a set of lines can say of what is left, and more where it cannot. So the result is never smaller than the difference, and is the difference where the sets are: it is a sound answer to "what is left", which is what an else branch needs. It is empty (not a union) when nothing is left. null is left unless the second union has it.

iex> Feel.Type.Union.difference([:any, :null], [:number]) |> Feel.Type.Union.format()
"Any except number | Null"
iex> Feel.Type.Union.difference([:number, :string], [:number])
[:string]
iex> Feel.Type.Union.difference([:number], [:number])
[]
iex> five = Feel.Type.NumberSet.point(Decimal.new(5))
iex> Feel.Type.Union.difference([:number], [{:number, five}]) |> Feel.Type.Union.format()
"number in [-max..5), (5..max]"
iex> Feel.Type.Union.difference([:boolean], [{:boolean, true}])
[{:boolean, false}]
iex> Feel.Type.Union.difference([:any, :null], [:any]) 
[:null]

@spec empty_list() :: {:list, []}

The type of the empty list alone, []: a list with no element that it could have. Every list<T> holds it, and list<Null> holds it and the lists of nulls (Table 43), which is what a reader that does not ask for the exact type sees.

iex> Feel.Type.Union.empty_list()
{:list, []}
iex> Feel.Type.Union.format([Feel.Type.Union.empty_list()])
"empty list"
iex> Feel.Type.Union.contains?([Feel.Type.Union.empty_list()], [])
true
iex> Feel.Type.Union.contains?([Feel.Type.Union.empty_list()], [nil])
false

@spec erase_sets(t()) :: t()

The union with every set of values left out, at every level: each alternative that is a set (number in [1..5], "a", true, a date in a range) is its bare kind, which holds every value of the kind. null, the shape of a list, a context and a range, and the names of types are kept.

A function arrow is kept only when erasing its parameters does not broaden their domains: broader parameters would strengthen the arrow rather than safely widen it. Otherwise the whole arrow becomes the :function kind. Overloads fall back likewise when an observable arrow cannot be retained safely, and discard call refinements that cannot be erased safely.

The result holds every value that the union holds, so it is a type of the same values, and a less exact one. It is the type that an analysis without value sets gives (Feel.Analysis.Refinement).

iex> Feel.Type.Union.erase_sets([{:number, Feel.Type.NumberSet.point(Decimal.new(3))}])
[:number]
iex> Feel.Type.Union.erase_sets([{:boolean, true}, :null])
[:boolean, :null]
iex> Feel.Type.Union.erase_sets([{:string, ["a", "b"]}, {:number, Feel.Type.NumberSet.all()}])
[:number, :string]
iex> Feel.Type.Union.of_value(%{"a" => [Decimal.new(1)]}) |> Feel.Type.Union.erase_sets()
[{:closed_context, %{"a" => [{:list, [:number]}]}}]
iex> Feel.Type.Union.erase_sets([{:function, [[{:number, Feel.Type.NumberSet.point(Decimal.new(1))}]], [{:boolean, false}]}])
[:function]
iex> Feel.Type.Union.erase_sets([:any, :null])
[:any, :null]

@spec erase_top_sets(t()) :: t()

The union with the sets left out of its own alternatives, and not of the types inside them: list<number in [1..3]> stays as it is. It is erase_sets/1 for a union whose parts have no sets already, which is the case of a type that is made from the types of the nodes below it in the core tier (Feel.Analysis.Refinement), and costs the size of the union and not the size of the type, so that a list nested to a thousand levels is not walked at each level.

iex> Feel.Type.Union.erase_top_sets([{:number, Feel.Type.NumberSet.point(Decimal.new(3))}, :null])
[:number, :null]
iex> inner = [{:number, Feel.Type.NumberSet.point(Decimal.new(3))}]
iex> Feel.Type.Union.erase_top_sets([{:list, inner}]) == [{:list, inner}]
true

@spec format(t() | never(), [{:values, boolean()}]) :: String.t()

Writes a union for a message: the members joined with |.

The sets of values are written too (number in [0..150]), unless values: false is given, which writes a number as number, a string as string, a boolean as boolean, and a date or a duration as its kind. The values of a date or a duration are written as 2024-01-31 and P1DT2H (Feel.Type.Image.format_value/2).

iex> Feel.Type.Union.format([:number, :null])
"number | Null"
iex> Feel.Type.Union.format([{:list, [:string]}])
"list<string>"
iex> union = Feel.Type.Union.of_value(Decimal.new(3))
iex> {Feel.Type.Union.format(union), Feel.Type.Union.format(union, values: false)}
{"number = 3", "number"}
iex> Feel.Type.Union.format(Feel.Type.Union.never())
"Never"

@spec from_spec(Feel.Type.t()) :: t()

Reads a type of the specification, where every type includes null.

A type marked {:non_null, type} (D-48) is the exception, for its outermost level: it has no null. What is inside it, as the elements of a list, is read as the specification has it. Raises ArgumentError for Null!, which has no values. A negation and a union that a host declares ({:not, type}, {:union, types}, D-178) are the union they make (Feel.Type.Composite.to_union/1).

iex> Feel.Type.Union.from_spec(:number)
[:number, :null]
iex> Feel.Type.Union.from_spec(:null)
[:null]
iex> Feel.Type.Union.from_spec({:list, :number})
[{:list, [:number, :null]}, :null]
iex> Feel.Type.Union.from_spec({:non_null, :number})
[:number]
iex> Feel.Type.Union.from_spec({:non_null, {:list, {:non_null, :number}}})
[{:list, [:number]}]

Recursive declarations are projected to a finite structural upper bound, not an exact translation. Recursive domains use a lower parameter bound in an upper arrow, and recursive negations project to top. Recursive function results use Any | Null in observable arrows, retaining their structural upper bound only as a call refinement. A graph projection may conservatively widen that call bound too. A consumer proving a recursive target must retain its check; inclusion in this projection is insufficient.

@spec intersect(t(), t()) :: [member()]

The values that two unions have in common: a union that holds every value that is in both, and as few others as it can say (D-194).

It is empty, never/0, when there is no value in both: a caller that gets [] knows that the two cannot be the same value. A value is in a union by what it is, so the numbers 1 and 1.0 are one value, and 1 is not in string.

The alternatives are taken in pairs. The sets of a kind meet in their intersection; Null meets only Null, and Any (every value that is not null) meets anything else as it is. The parts of a list and of a range meet part by part, and a list of nothing in common is the list of nothing, [] (Table 43). Two contexts meet entry by entry. An open context needs the entries it lists to be there (D-23), so it meets a closed one only if the closed one has them all; two closed ones only if they have the same entries. A named type is not looked into, and a function type meets another as the first.

iex> Feel.Type.Union.intersect([:number, :null], [:string, :null])
[:null]
iex> Feel.Type.Union.intersect([:number], [:string])
[]
iex> Feel.Type.Union.intersect([:any, :null], [:number]) |> Feel.Type.Union.format()
"number"
iex> a = [{:list, [:any, :null]}]
iex> b = [{:list, [:number]}]
iex> Feel.Type.Union.intersect(a, b) |> Feel.Type.Union.format()
"list<number>"

@spec kind(member()) :: member()

The kind of an alternative: the primitive type that a set of values is of, so :number for {:number, set}, and the alternative itself for every other.

iex> Feel.Type.Union.kind({:number, Feel.Type.NumberSet.all()})
:number
iex> Feel.Type.Union.kind({:boolean, true})
:boolean
iex> Feel.Type.Union.kind({:days_and_time_duration, Feel.Type.NumberSet.all()})
:days_and_time_duration
iex> Feel.Type.Union.kind({:list, [:number]})
{:list, [:number]}

@spec member_within?(member(), member()) :: boolean()

Whether one member is within another by itself: the structural test of subtype?/2 for two members, without looking at the other members of a union. For Feel.Type.Except.

@spec never() :: never()

Returns the union of no value, []: the type of code that cannot run (D-173), such as a branch of an if that its condition or the facts of the conditions around it rule out.

It is not [:null], the type of code that runs and gives null. It is the bottom of the order: it is within every type, nothing but itself is within it, and it is the identity of a join (new/1 leaves it out of what it builds). A value cannot be in it, so a node of this type that a run reaches is a type that was wrong (Feel.Paranoid says so).

iex> Feel.Type.Union.never()
[]
iex> Feel.Type.Union.subtype?(Feel.Type.Union.never(), [:number])
true
iex> Feel.Type.Union.new([Feel.Type.Union.never(), [:number]])
[:number]

@spec new([member() | t()]) :: t()

Builds a union from members and unions, in normal form.

Raises ArgumentError when there is nothing to build it from.

iex> Feel.Type.Union.new([:null, :number, :number])
[:number, :null]
iex> Feel.Type.Union.new([[:string, :null], [:number]])
[:number, :string, :null]
iex> Feel.Type.Union.new([:number, :any])
[:any]
iex> Feel.Type.Union.new([:any, :null, :boolean])
[:any, :null]

@spec non_empty(member()) :: [member()]

The lists of a list type that have an element: the type less the empty list (Feel.Type.Except).

iex> Feel.Type.Union.non_empty({:list, [:number, :null]}) |> Feel.Type.Union.format()
"non-empty list<number | Null>"
iex> Feel.Type.Union.non_empty({:list, []})
[]

@spec non_empty?(t()) :: boolean()

Whether every list of the union has an element: a list type less the empty list, or a value that is not a list.

@spec nullable?(t()) :: boolean()

Returns true when the union has null among its alternatives.

iex> Feel.Type.Union.nullable?([:number, :null])
true
iex> Feel.Type.Union.nullable?([:number])
false

@spec of_value(term()) :: t()

Returns the internal type of a value, retaining literal sets where the representation supports them.

Function values describe observable signature bounds and call refinements. Recursive result signatures are approximated conservatively, so this is not an exact runtime membership predicate.

Unlike Feel.Type.of/1, which follows Table 43, the elements of a list are not joined: ["a", true] is a list of boolean | string, not of Any, and null is an alternative of the element type where there is one. A term that is not a FEEL value is [:any, :null]: nothing is known about it.

iex> Feel.Type.Union.of_value(Decimal.new(1)) |> Feel.Type.Union.format()
"number = 1"
iex> Feel.Type.Union.of_value(nil)
[:null]
iex> Feel.Type.Union.of_value([true, nil]) |> Feel.Type.Union.format()
"non-empty list<boolean = true | Null>"
iex> Feel.Type.Union.of_value([]) |> Feel.Type.Union.format()
"empty list"
iex> Feel.Type.Union.of_value(~D[2024-01-31]) |> Feel.Type.Union.format()
"date = 2024-01-31"
iex> Feel.Type.Union.of_value(Feel.Value.DaysAndTimeDuration.new(93_600)) |> Feel.Type.Union.format()
"days and time duration = P1DT2H"
iex> Feel.Type.Union.of_value(1.5)
[:any, :null]

@spec plain?(t()) :: boolean()

Whether no member of the union is a kind less some of it or the empty list (D-152): the union as a reader that looks into a type sees it.

iex> Feel.Type.Union.plain?([:number, :null])
true
iex> Feel.Type.Union.plain?([Feel.Type.Union.empty_list()])
false

@spec positive(t() | never()) :: t() | never()

The union with the kinds that are less some of them (Feel.Type.Except) as the whole kind: every value that the union holds, and in a form that does not look into what is taken out. It is what a reader of a type that does not ask for the exact one reads (Feel.IR.plain_type/1).

iex> list = {:list, [:any, :null]}
iex> union = Feel.Type.Union.new([{:except, list, [{:list, [:number, :null]}]}, :null])
iex> Feel.Type.Union.positive(union)
[{:list, [:any, :null]}, :null]
iex> Feel.Type.Union.positive([:number, :null])
[:number, :null]

@spec positive_keeping_overloads(t() | never()) :: t() | never()

The union as positive/1 has it, with the overloads kept (D-171): what a reader that compares and applies function types reads. A kind less some of it is the kind, and an overload is still all of its arrows, since a function that is passed on or called is the one that the overload is the type of.

iex> {:ok, abs} = Feel.Builtin.value("abs")
iex> union = Feel.Type.Union.of_value(abs)
iex> Feel.Type.Union.positive_keeping_overloads(union) == union
true
iex> length(Feel.Type.Union.positive(union))
1

@spec restrict(
  t(),
  :number | :string | :boolean | Feel.Type.Image.kind(),
  Feel.Type.NumberSet.t() | Feel.Type.StringSet.t() | [String.t()] | [boolean()]
) :: t()

Narrows the numbers, the strings, the booleans, the dates or the durations of a union to a set.

set is a Feel.Type.NumberSet for :number and for a kind with an image (:date and the two durations, whose sets are those of the numbers that stand for the values), a list of strings for :string, and a list of true and false for :boolean. The alternative that is a number (a string, a boolean) becomes the numbers (strings, booleans) that are in both sets, and goes if none is. A union that has no alternative left is [:null]: the only value it can have is null.

iex> set = Feel.Type.NumberSet.interval(Decimal.new(0), Decimal.new(150))
iex> Feel.Type.Union.restrict([:number, :null], :number, set) |> Feel.Type.Union.format()
"number in [0..150] | Null"
iex> Feel.Type.Union.restrict([:string, :null], :string, ["a", "b"])
[{:string, ["a", "b"]}, :null]
iex> Feel.Type.Union.restrict([:number, :null], :number, [])
[:null]
iex> Feel.Type.Union.restrict([:boolean, :null], :boolean, [true])
[{:boolean, true}, :null]
iex> Feel.Type.Union.restrict([:boolean, :null], :boolean, [true, false])
[:boolean, :null]

@spec subtype?(t(), t()) :: boolean()

Returns true when every alternative of the first union is covered by one of the second.

This is sound but not complete: a union of lists is compared member by member, and list<number | string> is not seen to be within list<number> | list<string> (it is not), nor is a context with a union as a member seen to be within the union of two contexts (it is). The two type languages agree on what they share: for types of the non-recursive specification fragment, subtype?(from_spec(a), from_spec(b)) agrees with Feel.Type.conforms?(a, b). Recursive projections are upper approximations and do not establish that equivalence.

iex> Feel.Type.Union.subtype?([:number], [:number, :null])
true
iex> Feel.Type.Union.subtype?([:number, :null], [:number])
false
iex> Feel.Type.Union.subtype?([{:list, [:number]}], [{:list, [:number, :null]}, :null])
true

@spec to_spec(t()) :: Feel.Type.t()

Writes a union as a type of the specification: null is dropped, because every type includes it, and what is left is joined with Feel.Type.join/2.

iex> Feel.Type.Union.to_spec([:number, :null])
:number
iex> Feel.Type.Union.to_spec([:null])
:null
iex> Feel.Type.Union.to_spec([:boolean, :string])
:any
iex> Feel.Type.Union.to_spec([{:list, [:number]}])
{:list, :number}

@spec tops() :: [member(), ...]

The kinds of value that :any is the union of, each as the member that holds all of its values (D-39).

iex> Feel.Type.Union.tops() |> Enum.take(3)
[:boolean, :number, :string]
iex> Feel.Type.Union.new(Feel.Type.Union.tops() ++ [:null])
[:any, :null]