Crate urid

Library for idiomatic URID support.

In the world of RDF, resources are described using URIs. In Rust, this concept can be adapted to describe types with URIs using the UriBound trait. Then, other crates might use these URIs to describe relationships between types or values using URIs.

However, comparing URIs isn't necessarily fast. Therefore, another concept was introduced: The URID. A URID is basically a u32 which represents a URI. These URIDs are assigned by a Map and can be "dereferenced" by an Unmap.

This library also supports connecting URIDs to their UriBound via a generics argument. This can be used, for example, to request the URID of a certain bound as a parameter of a function. If someone would try to call this function with the wrong URID, the compiler will raise an error before the code is even compiled.

This may seem a bit minor to you now, but the audio plugin framework rust-lv2 heavily relies on this crate for fast, portable and dynamic data identification and exchange.

Example

use urid::*;

// Some types with URIs. The attribute implements `UriBound` with the given URI.
#[uri("urn:urid-example:my-struct-a")]
struct MyStructA;

#[uri("urn:urid-example:my-struct-b")]
struct MyStructB;

// A collection of URIDs that can be created by a mapper with one method call.
#[derive(URIDCollection)]
struct MyURIDCollection {
    my_struct_a: URID<MyStructA>,
    my_struct_b: URID<MyStructB>,
}

// A function that checks whether the unmapper behaves correctly.
// Due to the type argument, it can not be misused.
fn test_unmapper<M: Unmap, T: UriBound>(unmap: &M, urid: URID<T>) {
    assert_eq!(T::uri(), unmap.unmap(urid).unwrap());
}

// Create a simple mapper. The `HashURIDMapper` is thread-safe and can map and unmap all URIs.
let map = HashURIDMapper::new();

// Get the URIDs of the structs. You can use the collection or retrieve individual URIDs.
let urids: MyURIDCollection = map.populate_collection().unwrap();
let urid_a: URID<MyStructA> = map.map_type().unwrap();

// You can also retrieve the URID of a single URI without a binding to a type.
let urid_b: URID = map.map_str("https://rustup.rs").unwrap();

test_unmapper(&map, urids.my_struct_a);
test_unmapper(&map, urids.my_struct_b);
test_unmapper(&map, urid_a);

Structs

HashURIDMapper	A simple URI → URID mapper, backed by a standard HashMap and a Mutex for multi-thread access.
URID	Representation of a URI for fast comparisons.

Traits

Map	A handle to map URIs to URIDs.
URIDCollection	A store of pre-mapped URIDs
Unmap	A handle to map URIDs to URIs.
UriBound	A trait for types that can be identified by a URI.

Type Definitions

Uri	Representation of a borrowed Uri.
UriBuf	Representation of an owned Uri.

Attribute Macros

uri

Derive Macros

URIDCollection