@spec canonical(t()) :: t()

Transforms the given literal into its canonical form.

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

Returns if the lexical form of the given literal has the canonical form.

@spec canonical_lexical(t()) :: String.t() | nil

Returns the canonical lexical of the given literal.

Coerces a new RDF.Literal from another value.

The following mapping of Elixir types to XSD datatypes is applied:

When an RDF.Literal can not be coerced, nil is returned (as opposed to new/1 which fails in this case).

Examples

iex> RDF.Literal.coerce(42)
%RDF.Literal{literal: %RDF.XSD.Integer{value: 42}}

Returns if the given value is a RDF.Literal or RDF.Literal.Datatype struct.

If you simply want to check for a RDF.Literal use pattern matching or RDF.literal?/1. This function is a bit slower than those and most of the time only needed when implementing RDF.Literal.Datatypes where you have to deal with the raw, i.e. unwrapped RDF.Literal.Datatype structs.

@spec datatype_id(t()) :: RDF.IRI.t()

Returns the IRI of datatype of the given literal.

@spec equal?(any(), any()) :: boolean()

Checks if two literals are equal.

Two literals are equal if they have the same datatype, value and lexical form.

@spec equal_value?(t(), t() | any()) :: boolean()

Checks if two literals have equal values.

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

Returns if the literal uses the RDF.Literal.Generic datatype or on of the dedicated builtin or custom RDF.Literal.Datatypes.

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

Checks if the first of two RDF.Literals is greater than the other.

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

Returns if a literal is a datatyped literal.

For historical reasons, this excludes xsd:string and rdf:langString.

see http://www.w3.org/TR/rdf-concepts/#dfn-typed-literal

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

Returns if a literal is a language-tagged literal.

see http://www.w3.org/TR/rdf-concepts/#dfn-plain-literal

Checks if 'literal' is literal with the given datatype.

datatype can be one of the following:

• a RDF.Literal.Datatype module which checks if the literal is of this datatype or derived from it
• RDF.XSD.Numeric which checks if the literal is one of the numeric XSD datatypes or derived of one of them
• RDF.XSD.Datatype which checks if the literal is a XSD datatype or derived of one of them

@spec language(t()) :: String.t() | nil

Returns the language of the given literal if present.

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

Checks if the first of two RDF.Literals is smaller than the other.

@spec lexical(t()) :: String.t()

Returns the lexical form of the given literal.

@spec matches?(
  t() | String.t(),
  pattern :: t() | String.t(),
  flags :: t() | String.t()
) :: boolean()

Matches the lexical form of the given RDF.Literal against a XPath and XQuery regular expression pattern with flags.

The regular expression language is defined in XQuery 1.0 and XPath 2.0 Functions and Operators.

see https://www.w3.org/TR/xpath-functions/#func-matches

@spec new(t() | any()) :: t() | nil

Creates a new RDF.Literal of the given value and tries to infer an appropriate XSD datatype.

See coerce/1 for applied mapping of Elixir types to XSD datatypes.

Note: The RDF.literal function is a shortcut to this function.

Examples

iex> RDF.Literal.new(42)
%RDF.Literal{literal: %RDF.XSD.Integer{value: 42}}

@spec new(
  t() | any(),
  keyword()
) :: t() | nil

Creates a new RDF.Literal with the given datatype or language tag.

@spec new!(
  t() | any(),
  keyword()
) :: t()

Creates a new RDF.Literal, but fails if it's not valid.

Note: Validation is only possible if an RDF.Datatype with an implementation of RDF.Datatype.valid?/1 exists.

Examples

iex> RDF.Literal.new("foo")
%RDF.Literal{literal: %RDF.XSD.String{value: "foo"}}

iex> RDF.Literal.new!("foo", datatype: RDF.NS.XSD.integer)
** (RDF.Literal.InvalidError) invalid RDF.Literal: %RDF.XSD.Integer{value: nil, lexical: "foo"}

iex> RDF.Literal.new!("foo", datatype: RDF.langString)
** (RDF.Literal.InvalidError) invalid RDF.Literal: %RDF.LangString{value: "foo", language: nil}

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

Returns if a literal is a plain literal.

A plain literal may have a language, but may not have a datatype. For all practical purposes, this includes xsd:string literals too.

see http://www.w3.org/TR/rdf-concepts/#dfn-plain-literal

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

Returns if a literal is a simple literal.

A simple literal has no datatype or language.

see http://www.w3.org/TR/sparql11-query/#simple_literal

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

The optional second argument allows to specify what will be passed to fun with the :as option, e.g. with as: :lexical the lexical is passed to the function.

Example

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

@spec valid?(t() | any()) :: boolean()

Returns if the given literal is valid with respect to its datatype.

@spec value(t()) :: any()

Returns the value of the given literal.