Add RDF.Description.first/2

CHANGELOG.md

@@ -10,7 +10,8 @@ This project adheres to [Semantic Versioning](http://semver.org/) and
 ### Added
 
 - Turtle decoder
-- `RDF.Data.descriptions/1` returns all descriptions of a RDF data structure 
+- `RDF.Data.descriptions/1` returns all descriptions within a RDF data structure 
+- `RDF.Description.first/2` returns a single object a predicate of a `RDF.Description` 
 
 ### Changed
 

README.md

@@ -549,6 +549,14 @@ iex> RDF.Graph.new({EX.S1, EX.p, [EX.O1, EX.O2]})
 :not_found
 ```
 
+You can get a single object value for a given predicate in a `RDF.Description` with the `RDF.Description.first/2` function:
+
+```elixir
+iex> RDF.Description.new(EX.S1, {EX.p, EX.O1})
+...> |> RDF.Description.first(EX.p)
+~I<http://example.com/O1>
+```
+
 Since all three RDF data structures implement the `Access` behaviour, you can also use `data[key]` syntax, which basically just calls the resp. `get` function.
 
 ```elixir

lib/rdf/description.ex

@@ -329,7 +329,7 @@ defmodule RDF.Description do
   @doc """
   Gets the objects for the given predicate of a Description.
 
-  When the predicate can not be found the optionally given default value or `nil` is returned.
+  When the predicate can not be found, the optionally given default value or `nil` is returned.
 
   ## Examples
 
@@ -347,6 +347,24 @@ defmodule RDF.Description do
     end
   end
 
+  @doc """
+  Gets a single object for the given predicate of a Description.
+
+  When the predicate can not be found, the optionally given default value or `nil` is returned.
+
+  ## Examples
+
+      iex> RDF.Description.first(RDF.Description.new({EX.S, EX.P, EX.O}), EX.P)
+      RDF.uri(EX.O)
+      iex> RDF.Description.first(RDF.Description.new(EX.S), EX.foo)
+      nil
+  """
+  def first(description = %RDF.Description{}, predicate) do
+    description
+    |> get(predicate, [])
+    |> List.first
+  end
+
   @doc """
   Gets and updates the objects of the given predicate of a Description, in a single pass.