Struct Reference 

pub struct Reference {
    pub id: String,
    pub kind: WorkKind,
    pub authors: Vec<Author>,
    pub published: Attested<PublicationDate>,
    pub title: String,
    pub version: Attested<String>,
    pub descriptor: Attested<String>,
    pub publisher: Attested<String>,
    pub locator: Attested<Locator>,
    pub stability: Stability,
}

A citable external work.

Every field a renderer consults is either a plain value that must be present (the identifier, the kind, the title, the stability) or an Attested, which is how a field says “nobody has checked” without that being indistinguishable from “there is nothing to check”.

The record carries no opinion about whether it is complete. Completeness is a property of a record and a citation style together — APA insists on a bracketed descriptor for software that another style would not ask for — so it is decided by the renderer, which is where the style’s rules are.

The derived Ord is structural — field order, so Reference::id first — and exists to give Reference::list_order a last resort that is total over the whole record. It is not the order a reference list is printed in; sorting a slice with it directly gives id order, which is nobody’s bibliography.

Fields

id: String

A stable identifier for this work within a reference register. It never appears in rendered output; it is what a citation points at, what a refusal names, and the final tiebreak that makes list ordering total.

kind: WorkKind

What kind of thing the work is.

authors: Vec<Author>

The authors, in the order the work presents them. That order is the work’s own and is never sorted: authorship order carries meaning.

published: Attested<PublicationDate>

When the work was published. Attested::AbsentFromWork is a dateless work — APA’s n.d. — and Attested::Unknown is a date nobody has looked for, which no renderer may print.

title: String

The title, in the case it should be printed in.

Stored ready to print. Recasing a title needs to know which words are proper nouns, and a renderer guessing at that is a renderer changing what somebody wrote down — so the register records sentence case and nothing downstream touches it.

version: Attested<String>

The version, edition or release designation, if the work has one, recorded bare — 3.3.070, not Version 3.3.070 and not v3.3.070. A renderer supplies whatever word its style puts in front, and one that found the word already there would print it twice.

descriptor: Attested<String>

A bracketed description of a non-standard work — Computer software, Data set, Fact sheet — stored without its brackets.

This is a judgement, not a fact read off the work, and it is deliberately not derivable from Reference::kind: inferring Computer software from WorkKind::Software would be the renderer inventing the one element APA added to stop readers mistaking one kind of source for another.

publisher: Attested<String>

The publisher, repository or site responsible for making the work available.

locator: Attested<Locator>

Where the work can be found.

stability: Stability

Whether the work holds still, carrying the retrieval date when it does not.

Implementations

impl Reference

pub fn new( id: impl Into<String>, kind: WorkKind, title: impl Into<String>, stability: Stability, ) -> Self

A record with the fields that have no honest default left Attested::Unknown, and no authors.

Such a record refuses: that is the point of it. Construction cannot produce something citable by accident, and every field that reaches output has to be filled in deliberately.

pub fn list_order(a: &Self, b: &Self) -> Ordering

The total order a reference list is printed in.

APA §9.47 is more than “alphabetical by surname”, and the parts people leave out are the parts that make two correct-looking lists disagree:

• a one-author entry precedes a multi-author entry beginning with the same surname;
• entries sharing a first author are ordered by the second author’s surname, and so on down the list;
• two different people with the same surname are ordered by their initials, before date is consulted at all — Smith, A. precedes Smith, T., whatever year either published;
• only then does date break the tie, earliest first, with an undated work before any dated one.

Comparing the whole author list, element by element, gets the first two for free: ["salas"] is a prefix of ["salas", "d'agostino"] and so sorts before it, and ["salas", "a"] sorts before ["salas", "b"].

The keys, in order:

1. every author, in the order the work lists them — surname then initials as rendered, folded letter by letter: capitals ignored, and spaces and punctuation dropped, which is what APA’s “letter by letter” means literally. Olsen therefore precedes O'Malley precedes O'Neil. Rendered initials rather than recorded given names, so that nothing invisible on the page can decide the order of the page;
2. the same list case-sensitively, so the fold in step 1 never decides a tie by accident of iteration order;
3. the full publication date — year, then month, then day, so two works from one year are not left to be separated by their titles. An undated work sorts first (APA puts n.d. before any year for the same author) and a record whose date nobody has looked up sorts last; such a record never reaches a rendered list, but the order still has to be defined for it. A year-only date precedes a more precise one in the same year, because that is the only placement that does not invent a month for it;
4. title, folded the same way then compared as written — trimmed, like the author keys, because the renderer trims both and whitespace nobody can see must not decide an order somebody reads. Folded the same way because APA alphabetises a title letter by letter too, and one function applied to both is what keeps them from disagreeing;
5. Reference::id;
6. the record itself, structurally.

Key 6 is what makes the order genuinely total rather than total only where ids happen to be unique. id is a public String and nothing enforces uniqueness, so two records could agree on keys 1–5 and still differ — in a publisher, say. Without a last resort they would compare Equal, and a stable sort would then order them by the order they arrived in, which is exactly the input-order dependence the byte-reproducibility rule forbids.

Deliberately a named function rather than the Ord implementation: Ord must agree with Eq, and keys 1–5 are a strict subset of the fields PartialEq compares. The derived Ord on Reference — which key 6 uses — is structural and agrees with Eq; it is a tiebreak, not a reference-list order, and sorting with it directly gives id order.

Trait Implementations

impl Clone for Reference

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Reference

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Reference

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for Reference

impl Ord for Reference

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for Reference

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for Reference

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Reference

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Reference