@callback canonical(RDF.Literal.t() | literal()) :: RDF.Literal.t()

Produces the canonical representation of a RDF.Literal.

@callback canonical?(RDF.Literal.t() | literal() | any()) :: boolean()

Determines if the lexical form of a RDF.Literal is the canonical form.

Note: For RDF.Literal.Generic literals with the canonical form not defined, this always returns true.

@callback canonical_lexical(RDF.Literal.t() | literal()) :: String.t() | nil

Returns the canonical lexical form of a RDF.Literal.

If the given literal is invalid, nil is returned.

@callback datatype?(RDF.Literal.t() | t() | literal()) :: boolean()

Checks if the given RDF.Literal has the datatype for which the RDF.Literal.Datatype is implemented or is derived from it.

Example

iex> RDF.XSD.byte(42) |> RDF.XSD.Integer.datatype?()
true

@callback datatype_id(RDF.Literal.t() | literal()) :: RDF.IRI.t()

The datatype IRI of the given RDF.Literal.

@callback do_cast(literal() | RDF.IRI.t() | RDF.BlankNode.t()) :: RDF.Literal.t() | nil

Callback for datatype specific castings.

This callback is called by the auto-generated cast/1 function on the implementations, which already deals with the basic cases. So, implementations can assume the passed argument is a valid RDF.Literal.Datatype struct, a RDF.IRI or a RDF.BlankNode.

If the given literal can not be converted into this datatype an implementation should return nil.

A final catch-all clause should delegate to super. For example RDF.XSD.Datatypes will handle casting from derived datatypes in the default implementation.

@callback do_compare(literal() | any(), literal() | any()) ::
  comparison_result() | :indeterminate | nil

Callback for datatype specific compare/2 comparisons between two RDF.Literals.

This callback is called by auto-generated compare/2 function on the implementations, which already deals with the basic cases. So, implementations can assume the passed arguments are valid RDF.Literal.Datatype structs and have the same datatypes or are derived from each other.

Should return :gt if value of the first literal is greater than the value of the second in terms of their datatype and :lt for vice versa. If the two literals can be considered equal :eq should be returned. For datatypes with only partial ordering :indeterminate should be returned when the order of the given literals is not defined.

nil should be returned when the given arguments are not comparable datatypes or if one them is invalid.

The default implementation of the _using__ macro of RDF.Literal.Datatypes just compares the values of the given literals.

@callback do_equal_value_different_datatypes?(literal(), literal()) :: boolean() | nil

Callback for datatype specific equal_value?/2 comparisons when the given literals have different datatypes.

This callback is called by auto-generated equal_value?/2 function when the given literals have different datatypes and are not derived from each other.

Should return nil when the given arguments are not comparable as literals of this datatype. This behaviour is particularly important for SPARQL.ex where this function is used for the = operator, where comparisons between incomparable terms are treated as errors and immediately leads to a rejection of a possible match.

See also do_equal_value_same_or_derived_datatypes?/2.

@callback do_equal_value_same_or_derived_datatypes?(literal(), literal()) ::
  boolean() | nil

Callback for datatype specific equal_value?/2 comparisons when the given literals have the same or derived datatypes.

This callback is called by auto-generated equal_value?/2 function when the given literals have the same datatype or one is derived from the other.

Should return nil when the given arguments are not comparable as literals of this datatype. This behaviour is particularly important for SPARQL.ex where this function is used for the = operator, where comparisons between incomparable terms are treated as errors and immediately leads to a rejection of a possible match.

See also do_equal_value_different_datatypes?/2.

@callback id() :: RDF.IRI.t() | nil

The IRI of the datatype.

@callback language(RDF.Literal.t() | literal()) :: String.t() | nil

The language of the given RDF.Literal if present.

@callback lexical(RDF.Literal.t() | literal()) :: String.t()

Returns the lexical form of a RDF.Literal.

@callback name() :: String.t()

The name of the datatype.

@callback update(RDF.Literal.t() | literal(), (... -> any())) :: RDF.Literal.t()

Updates the value of a RDF.Literal without changing everything else.

Example

iex> RDF.XSD.integer(42) |> RDF.XSD.Integer.update(fn value -> value + 1 end)
RDF.XSD.integer(43)
iex> ~L"foo"de |> RDF.LangString.update(fn _ -> "bar" end)
~L"bar"de
iex> RDF.literal("foo", datatype: "http://example.com/dt") |> RDF.Literal.Generic.update(fn _ -> "bar" end)
RDF.literal("bar", datatype: "http://example.com/dt")

@callback update(RDF.Literal.t() | literal(), (... -> any()), keyword()) ::
  RDF.Literal.t()

Updates the value of a RDF.Literal without changing anything else.

This variant of update/2 allows with the :as option to specify what will be passed to fun, e.g. with as: :lexical the lexical is passed to the function.

Example

iex> RDF.XSD.integer(42) |> RDF.XSD.Integer.update(
...>   fn value -> value <> "1" end, as: :lexical)
RDF.XSD.integer(421)

@callback valid?(RDF.Literal.t() | literal() | any()) :: boolean()

Determines if a RDF.Literal has a proper value of the value space of its datatype.

This function also accepts literals of derived datatypes.

@callback value(RDF.Literal.t() | literal()) :: any()

Returns the value of a RDF.Literal.

This function also accepts literals of derived datatypes.