Struct TeXString 

pub struct TeXString(/* private fields */);

A string of TeX markup — text that is safe to hand back to the tokenizer.

It is not a path and not an input .tex file (source_directory, --source-map and docs/performance/SOURCE_PROVENANCE.md own that sense of “source”); it is the character content a crate::mouth::Mouth will read.

Why the type exists

Flattening Tokens with Display welds control words. TeX consumes the space that terminates a control word, so \v S tokenizes to [\v][S]; re-emitting that with Display gives \vS, a control sequence that exists in no LaTeX. Tokens::untex re-emits the space, Display deliberately does not — this is faithful to Perl (Core/Tokens.pm:61 toString joins the token strings, and Core/Token.pm:306 returns a CS name with no trailing space), whose own comment says the result is “NOT for creating valid TeX (use revert or UnTeX for that!)”.

Perl relies on author discipline there. It has failed three times in this port — \bib@@names (PR #399), dcolumn/overpic (PR #400), and the MathSciNet review path (issue 410: MRREVIEWER = {Fran\c cois\ Digne} became undefined:\ccois) — each found by a user-visible failure years after the code was written. TeXString makes the mistake unrepresentable instead: the tokenizing sinks take impl Into<TeXString>, and a bare String has no way in.

The three ways in

• From<&'static str> — a string literal in a binding is TeX its author typed by hand, so it converts implicitly and the ~125 literal call sites stay untouched. There is deliberately no From<String> and no From<&str>: those are exactly the shapes a welded Tokens::to_string() arrives in, and s!(…)/format!(…) returns the former.
• Tokens::untex_string — the blessed path from Tokens.
• TeXString::assembled — the explicit escape hatch, for a format! of literal TeX around already-safe pieces. It names the obligation it imposes.

let s: TeXString = r"\relax".into(); // literal: implicit
assert_eq!(s.as_str(), r"\relax");

A String cannot get in on its own — this is the guard, and it bites:

let welded: String = String::from(r"\vS");
let _: TeXString = welded.into(); // no `From<String>`: does not compile

Implementations

impl TeXString

pub fn assembled(tex: String) -> Self

Assert that an owned String is valid TeX markup.

The caller’s obligation: every interpolated fragment must be either literal TeX written at the call site, or a fragment that came from Tokens::untex_string / another TeXString. It must not be a bare Tokens::to_string() — that is the welding bug this type exists to prevent (\v S → \vS); use Tokens::untex_string for those.

The typical honest use is a format! whose shape is literal TeX:

let counter = "section";
let tex = TeXString::assembled(format!(r"\the{counter}"));
assert_eq!(tex.as_str(), r"\thesection");

pub fn as_str(&self) -> &str

The TeX markup, borrowed.

pub fn into_string(self) -> String

The TeX markup, owned (allocates only when this was built from a literal).

pub fn is_empty(&self) -> bool

Is there any markup at all?

Trait Implementations

impl AsRef<str> for TeXString

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for TeXString

fn clone(&self) -> TeXString

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TeXString

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

Formats the value using the given formatter.

impl Default for TeXString

fn default() -> TeXString

Returns the “default value” for a type.

impl Display for TeXString

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

Formats the value using the given formatter.

impl Eq for TeXString

impl From<&'static str> for TeXString

fn from(tex: &'static str) -> Self

A &'static str in a binding is a TeX literal its author typed by hand.

Deliberately the only blanket string conversion — see the type docs.

impl Hash for TeXString

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 TeXString

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for TeXString