Trait ion_rs::value::SymbolToken

source · [−]
pub trait SymbolToken: Debug + PartialEq {
    type ImportSource: ImportSource + ?Sized;

    fn text(&self) -> Option<&str>;
    fn local_sid(&self) -> Option<SymbolId>;
    fn source(&self) -> Option<&Self::ImportSource>;
    fn with_text(self, text: &'static str) -> Self;
    fn with_local_sid(self, local_sid: SymbolId) -> Self;
    fn with_source(self, table: &'static str, sid: SymbolId) -> Self;
    fn text_token(text: &'static str) -> Self;
    fn local_sid_token(local_sid: SymbolId) -> Self;
}
Expand description

A view of a symbolic token.

This can be either a content associated with a symbol value itself, an annotation, or a field name.

A token may have text, a symbol id, both, or neither. Optionally, a token may have some shared import source from whence it came.

Symbol $0, for example, is represented with a symbol that has no source and no text, and whose local_sid is 0 (but could also have some other local_sid implying that a symbol with unknown text was defined in some local context).

Note that it is context dependent whether a symbol token implementation has had its applicable context available to it (e.g. the local symbol table). A low-level implementation of a symbol token from a raw Ion binary parser, for example, may have symbol tokens in which only the local_sid defined because it only deals with the raw encoding of Ion. A high-level implementation that end users would generally use could have an symbol tokens that have their context applied (or available) such that they return their text and/or source if the applicable context had/has that information.

PartialEq Implementation Notes

Implementations of SymbolToken that implement PartialEq should do so without violating the transitivity rule of PartialEq. Specifically, this means that one cannot use PartialEq to implement the Ion data model definition of equivalence for symbolic tokens.

Consider the following pseudo-code describing Ion data model semantics:

    //   (<text>, <local id>, <source>)
     
    a := (nil, 200, ("my_table", 1))
    b := ("foobar", 200, ("my_table", 1))
    c := ("foobar", nil, nil)

    a == b, b == a // true -- source matches
    b == c, c == b // true -- text matches

    a == c         // false - text + no source != no text with source

The problem above is that a != c violates the contract for PartialEq as equality must be transitive.

A reasonable definition for PartialEq is that any symbol with text is equal to any other symbol with text, but in the case that a symbol does not have text, it is equal to another symbol if and only if that symbol does not have text and the source is the same.

In practice the above difference from the Ion data model should only affect esoteric use cases of the API. For example, a use case where data is read from a context in which a shared symbol table is not available and is mixed with data was resolved with the shared symbol table being present. Such a context implies more than one symbol table catalog in use by an application which is not a typical (but certainly valid) usage pattern.

Required Associated Types

Required Methods

The text of the token, which may be None if no text is associated with the token (e.g. lack of a shared symbol table import for a given SID).

An implementation is allowed to return None if the text is explicitly known to be undefined (e.g. $0) or the context that would allow it to be defined has not been applied or is not available.

The ID of the token, which may be None if no ID is associated with the token (e.g. Ion text symbols).

The source of this token, which may be None if the symbol is locally defined.

An implementation is allowed to return None if the source is explicitly known to be undefined (e.g. a locally defined symbol) or the context that would allow the source to be defined has not been applied or is not available.

source

fn with_text(self, text: &'static str) -> Self

Decorates the SymbolToken with text.

Decorates the SymbolToken with a local ID.

Decorates the SymbolToken with an ImportSource.

Constructs an SymbolToken with just text. A common case for text and synthesizing tokens.

Constructs an SymbolToken with unknown text and a local ID. A common case for binary parsing (though technically relevant in text).

Implementors