Users' guide: the `Cite2Urn`

The CitableObject module defines functions for working with Cite2Urns. (The API documentation has a more complete list.) Construct a Cite2Urn from a string value.

using CitableObject
pageurn = Cite2Urn("urn:cite2:hmt:msA.v1:12r")

urn:cite2:hmt:msA.v1:12r

Components and parts

Include the CitableBase module for to use the generic components and parts functions. These return Vectors of string values.

using CitableBase
components(pageurn)

5-element Vector{SubString{String}}:
 "urn"
 "cite2"
 "hmt"
 "msA.v1"
 "12r"

A Cite2Urn always has five top-level components. It is legal for the object component to be empty.

pagecollection =  Cite2Urn("urn:cite2:hmt:msA.v1:")
components(pagecollection)

5-element Vector{SubString{String}}:
 "urn"
 "cite2"
 "hmt"
 "msA.v1"
 ""

You can use the following functions to extract top-level components by name. They return a string value.

namespace(pageurn)

"hmt"

collectioncomponent(pageurn)

"msA.v1"

objectcomponent(pageurn)

"12r"

You can also retrieve individual parts of the collection component:

collectionid(pageurn)

"msA"

versionid(pageurn)

"v1"

propurn =  Cite2Urn("urn:cite2:hmt:msA.v1.side:12r")
propertyid(propurn)

"side"

URN manipulation

Several functions use a Cite2Urn to create a new, modified Cite2Urn.

dropversion(pageurn)

urn:cite2:hmt:msA:12r

Verify that the result is a new Cite2Urn.

dropversion(pageurn) |> typeof

Cite2Urn

addversion(pageurn, "v2")

urn:cite2:hmt:msA.v2:12r

dropobject(pageurn)

urn:cite2:hmt:msA.v1:

addobject(pageurn, "1r")

urn:cite2:hmt:msA.v1:1r

dropproperty(propurn)

urn:cite2:hmt:msA.v1:12r

addproperty(pageurn, "side")

urn:cite2:hmt:msA.v1.side:12r

URN comparison

In addition to comparing for equality with ==, you can compare a pair of CITE2 URNs for URN containment or URN similarity.

urncontains(pagecollection, pageurn)

true

Two URNs are similar if they are equal, or if either contains the other.

urnsimilar(pagecollection, pageurn)

true

Note that this definition means the function is symmetric.

urnsimilar(pagecollection, pageurn) == urnsimilar(pageurn, pagecollection)

true

For Cite2Urns, urnequals and == return identical results.

urnequals(pagecollection, pageurn)

false

pagecollection == pageurn

false

urnsimilar(pagecollection,dropobject(pageurn))

true

Ranges

Cite2Urns can identify ranges (sequences) of objects in ordered collections.

pages = Cite2Urn("urn:cite2:hmt:msA.v1:1r-11v")
isrange(pages)

true

range_begin(pages)

"1r"

range_end(pages)

"11v"

Extended identifiers ("subreferences")

In some collections, extended identifiers ("subreferences") may be appropriate. You can determine if a Cite2Urn includes an extended identifier, extract the subreference, or drop it.

imgurn = Cite2Urn("urn:cite2:hmt:vaimg.2017a:VA012RN_0013@0.2005,0.2073,0.1774,0.02351")
hassubref(imgurn)

true

The subref functions returns a string value.

subref(imgurn)

"0.2005,0.2073,0.1774,0.02351"

The dropsubref function returns a new Cite2Urn.

dropsubref(imgurn)

urn:cite2:hmt:vaimg.2017a:VA012RN_0013