Struct KnownValue 

pub struct KnownValue { /* private fields */ }

A value in a namespace of unsigned integers that represents a stand-alone ontological concept.

Known Values provide a compact, deterministic way to represent commonly used ontological concepts such as relationships between entities, classes of entities, properties, or enumerated values. They are particularly useful as predicates in Gordian Envelope assertions, offering a more compact and deterministic alternative to URIs. However, known values are not exclusive to Gordian Envelopes and can be used in any context where a compact, unique identifier for a concept is needed.

A Known Value is represented as a 64-bit unsigned integer with an optional human-readable name. This approach ensures:

• Compact binary representation - Each Known Value requires only 1-9 bytes depending on value range
• Deterministic encoding - Every concept has exactly one valid binary representation
• Enhanced security - Eliminates URI manipulation vulnerabilities
• Standardized semantics - Values are registered in a central registry

While Known Values are most commonly used as predicates in assertions, they can appear in any position in an Envelope (subject, predicate, or object).

Examples

use known_values::KnownValue;

// Create a Known Value with a numeric value
let known_value = KnownValue::new(42);
assert_eq!(known_value.value(), 42);

// Create a Known Value with a name
let named_value = KnownValue::new_with_name(1u64, "isA".to_string());
assert_eq!(named_value.value(), 1);
assert_eq!(named_value.name(), "isA");

// Use a pre-defined Known Value from the registry
let is_a_value = known_values::IS_A;
assert_eq!(is_a_value.value(), 1);
assert_eq!(is_a_value.name(), "isA");

Specification

Known Values are defined in BCR-2023-002 and implemented as an Envelope extension in BCR-2023-003.

Implementations

impl KnownValue

pub fn new(value: u64) -> Self

Creates a new KnownValue with the given numeric value and no name.

Examples

use known_values::KnownValue;

let known_value = KnownValue::new(42);
assert_eq!(known_value.value(), 42);

pub fn new_with_name<T: Into<u64>>(value: T, assigned_name: String) -> Self

Creates a KnownValue with the given value and associated name.

This function accepts any type that can be converted into a u64 and a String for the name. The name is stored as a dynamic value.

Examples

use known_values::KnownValue;

let known_value = KnownValue::new_with_name(1u64, "isA".to_string());
assert_eq!(known_value.value(), 1);
assert_eq!(known_value.name(), "isA");

pub const fn new_with_static_name(value: u64, name: &'static str) -> Self

Creates a KnownValue at compile time with the given value and static name.

This function is used primarily with the const_known_value! macro to define known values as constants in the registry.

Examples

use known_values::KnownValue;

// This is similar to how registry constants are defined
const IS_A: KnownValue = KnownValue::new_with_static_name(1, "isA");

assert_eq!(IS_A.value(), 1);
assert_eq!(IS_A.name(), "isA");

pub fn value(&self) -> u64

Returns the numeric value of the KnownValue.

This is the raw 64-bit unsigned integer that identifies the concept.

Examples

assert_eq!(known_values::IS_A.value(), 1);
assert_eq!(known_values::NOTE.value(), 4);

pub fn assigned_name(&self) -> Option<&str>

Returns the assigned name of the KnownValue, if one exists.

Examples

use known_values::KnownValue;

let named_value = KnownValue::new_with_name(1u64, "isA".to_string());
assert_eq!(named_value.assigned_name(), Some("isA"));

let unnamed_value = KnownValue::new(42);
assert_eq!(unnamed_value.assigned_name(), None);

pub fn name(&self) -> String

Returns a human-readable name for the KnownValue.

If the KnownValue has an assigned name, that name is returned. Otherwise, the string representation of the numeric value is returned.

Examples

use known_values::KnownValue;

let named_value = KnownValue::new_with_name(1u64, "isA".to_string());
assert_eq!(named_value.name(), "isA");

let unnamed_value = KnownValue::new(42);
assert_eq!(unnamed_value.name(), "42");

Trait Implementations

impl CBORTagged for KnownValue

Specifies the CBOR tag used for KnownValue.

fn cbor_tags() -> Vec<Tag>

Returns the CBOR tags associated with this type.

impl CBORTaggedDecodable for KnownValue

Creates a KnownValue from untagged CBOR.

fn from_untagged_cbor(cbor: CBOR) -> Result<Self>

Creates an instance of this type by decoding it from untagged CBOR.

fn from_tagged_cbor(cbor: CBOR) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from tagged CBOR.

fn from_tagged_cbor_data(data: impl AsRef<[u8]>) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded tagged CBOR.

fn from_untagged_cbor_data(data: impl AsRef<[u8]>) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded untagged CBOR.

impl CBORTaggedEncodable for KnownValue

Provides the untagged CBOR representation of a KnownValue.

fn untagged_cbor(&self) -> CBOR

Returns the untagged CBOR encoding of this instance.

fn tagged_cbor(&self) -> CBOR

Returns the tagged CBOR encoding of this instance.

fn tagged_cbor_data(&self) -> Vec<u8>

Returns the tagged value in CBOR binary representation.

impl Clone for KnownValue

fn clone(&self) -> KnownValue

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KnownValue

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl DigestProvider for KnownValue

Provides a cryptographic digest for a KnownValue.

fn digest(&self) -> Digest

Returns a digest that uniquely characterizes the content of the implementing type.

impl Display for KnownValue

Formats the KnownValue for display.

If a name is assigned, the name is displayed. Otherwise, the numeric value is displayed.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<KnownValue> for CBOR

Converts a KnownValue to CBOR.

fn from(value: KnownValue) -> Self

Converts to this type from the input type.

impl From<i32> for KnownValue

Creates a KnownValue from an i32.

fn from(value: i32) -> Self

Converts to this type from the input type.

impl From<u64> for KnownValue

Creates a KnownValue from a u64.

fn from(value: u64) -> Self

Converts to this type from the input type.

impl From<usize> for KnownValue

Creates a KnownValue from a usize.

fn from(value: usize) -> Self

Converts to this type from the input type.

impl Hash for KnownValue

Hash implementation for KnownValue that considers only the numeric value.

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for KnownValue

Equality for KnownValue is based solely on the numeric value, ignoring the name.

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<CBOR> for KnownValue

Attempts to convert CBOR to a KnownValue.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(cbor: CBOR) -> Result<Self>

Performs the conversion.

impl Eq for KnownValue

KnownValue implements Eq since equality is based on the numeric value, which can be compared for equality.