Add RDF.Description.first/3

CHANGELOG.md

@@ -13,6 +13,8 @@ This project adheres to [Semantic Versioning](http://semver.org/) and
 - `RDF.Graph.new/2` and `RDF.Graph.add/2` support the addition of `RDF.Dataset`s
 - `RDF.Description.empty?/1`, `RDF.Graph.empty?/1` and `RDF.Dataset.empty?/1` which
    are significantly faster than `Enum.empty?/1` 
+- `RDF.Description.first/2` now has a `RDF.Description.first/3` variant which
+  supports a default value
 - new guards in `RDF.Guards`: `is_statement/1` and `is_quad/1`
 - `RDF.PropertyMap.terms/1` and `RDF.PropertyMap.iris/1`
 

lib/rdf/description.ex

@@ -370,12 +370,14 @@ defmodule RDF.Description do
       RDF.iri(EX.O)
       iex> RDF.Description.new(EX.S) |> RDF.Description.first(EX.foo)
       nil
+      iex> RDF.Description.new(EX.S) |> RDF.Description.first(EX.foo, :bar)
+      :bar
   """
-  @spec first(t, Statement.coercible_predicate()) :: Statement.object() | nil
-  def first(%__MODULE__{} = description, predicate) do
+  @spec first(t, Statement.coercible_predicate(), any) :: Statement.object() | nil
+  def first(%__MODULE__{} = description, predicate, default \\ nil) do
     description
     |> get(predicate, [])
-    |> List.first()
+    |> List.first() || default
   end
 
   @doc """

test/unit/description_test.exs

@@ -787,6 +787,14 @@ defmodule RDF.DescriptionTest do
     assert Enum.count(desc.predications) == 1
   end
 
+  test "first/3" do
+    assert EX.S |> EX.p(EX.O) |> Description.first(EX.p()) == RDF.iri(EX.O)
+    assert EX.S |> EX.p(EX.O1, EX.O2) |> Description.first(EX.p()) == RDF.iri(EX.O1)
+    assert EX.S |> EX.p(EX.O1, EX.O2) |> Description.first(EX.missing()) == nil
+    assert EX.S |> EX.p(EX.O1, EX.O2) |> Description.first(EX.missing(), :default) == :default
+    assert EX.S |> EX.p(false) |> Description.first(EX.p(), :default) == XSD.false()
+  end
+
   test "statement_count/1" do
     assert Description.statement_count(Description.new(EX.S)) == 0
     assert Description.statement_count(description({EX.p(), EX.O})) == 1