Add `Uri::toRelative(base: Uri): Uri` method

Issue by bblfish Friday Jul 04, 2014 at 09:08 GMT Originally opened as https://github.com/akka/akka/issues/15495

---

I reported this as Spray issue 818 as the move to akka was underway. So I'll add a reference here.

Currently one can make a Uri relative to the root.

**
   * Converts this URI into a relative URI by keeping the path, query and fragment, but dropping the scheme and authority.
   */
  def toRelative =
    Uri(path = if (path.isEmpty) Uri.Path./ else path, query = query, fragment = fragment)

It would be useful to have the same functionality as java.net.URI#relativize(URI) to allow easy relative URI creation.

scala> import java.net.URI
import java.net.URI

scala> val card = new URI("http://bblfish.net/people/henry/card#me")
card: java.net.URI = http://bblfish.net/people/henry/card#me

scala> val base1 = new URI("http://bblfish.net/people/")
base1: java.net.URI = http://bblfish.net/people/

scala> base1.relativize(card)
res0: java.net.URI = henry/card#me

scala> new URI("http://bblfish.net/people/henry/").relativize(card)
res1: java.net.URI = card#me

scala> new URI("http://bblfish.net/people/henry/card").relativize(card)
res2: java.net.URI = #me

It is often very useful to serialise to relative uris when a base is known. So when one does a GET on a URI such as http://bblfish.net/people/henry/card it is much easier to read the result when it says

<> a foaf:PersonalProfileDocument;
    foaf:primaryTopic <card> .

rather than writing out all the Uris in full. Because a relative URI such as "" ( or <> and in the above ) allows a human to immediatly understand that the document is speaking of itself. A full URI requires a human to do a full comparison.

So we need this a lot in serialisations. Having this feature would allow banana-rdf for example to move totally to akka-http, which would also make it easier then to write code that can compile with scala-js.

As a matter of interest I wonder if it would be possible to make type distinctions between full and relative Uris. (Full Uris being a subclass of relative Uris perhaps). This would help make a large class of errors visible to the compiler, as explained in issue #41 of banana-rdf. Perhaps that should be for a different bug report?