Char variants

A char variant is a transformation that is applied to every character of a text at the moment it is written on a surface. It allows you to display a text in a different style (bold, italic, script, circled, superscript, etc.) without having to change the text itself. The styled forms are regular Unicode characters (most of them from the Mathematical Alphanumeric Symbols, Enclosed Alphanumerics and Phonetic Extensions blocks), so they work in any terminal whose font contains those glyphs.

Char variants are described by the CharVariant enum:

#![allow(unused)]
fn main() {
pub enum CharVariant {
    None,                    // default - no conversion
    Uppercase,
    Lowercase,
    MathBold,
    MathItalic,
    MathBoldItalic,
    Script,
    ScriptBold,
    Fraktur,
    FrakturBold,
    DoubleStruck,
    SansSerif,
    SansSerifBold,
    SansSerifItalic,
    SansSerifBoldItalic,
    Monospace,
    Circled,
    CircledNegative,
    Squared,
    SquaredNegative,
    Superscript,
    Subscript,
    SmallCaps,
    Custom(fn(char) -> char),
}
}

Usage

With write_text(...)

The most common way to use a char variant is through the TextFormatBuilder (see Text). The char_variant(...) method sets the variant that will be applied to every character written by write_text(...):

#![allow(unused)]
fn main() {
use appcui::prelude::*;

let mut surface = Surface::new(40, 5);
let format = TextFormatBuilder::new()
    .position(1, 1)
    .attribute(CharAttribute::with_color(Color::Yellow, Color::DarkBlue))
    .align(TextAlignment::Left)
    .char_variant(CharVariant::MathBold)
    .build();
surface.write_text("Hello World 2026", &format);
// the surface now contains: 𝐇𝐞𝐥𝐥𝐨 𝐖𝐨𝐫𝐥𝐝 𝟐𝟎𝟐𝟔
}

The conversion is done one character at a time and always produces exactly one character, so:

• the number of characters (and therefore alignment, wrapping and hotkey positions) is the same as for the original text;
• the hotkey character (if any) is converted as well, but it keeps the hotkey attribute;
• the original string is never modified - only what is drawn on the surface changes.

The default value is CharVariant::None, meaning that the text is written as it is.

With map(...)

A CharVariant can also be used directly, to convert a single character through the map(...) method:

#![allow(unused)]
fn main() {
pub fn map(&self, ch: char) -> char
}

This is useful if you want to build a converted string yourself (for example to use it with write_string(...) or to store it):

#![allow(unused)]
fn main() {
use appcui::prelude::*;

let v = CharVariant::Circled;
assert_eq!(v.map('A'), 'Ⓐ');
assert_eq!(v.map('7'), '⑦');
assert_eq!(v.map('!'), '!'); // characters without a variant are left unchanged

let text: String = "Hello".chars().map(|c| CharVariant::DoubleStruck.map(c)).collect();
assert_eq!(text, "ℍ𝕖𝕝𝕝𝕠");
}

Custom variants

If none of the predefined variants fits your needs, CharVariant::Custom accepts any function with the signature fn(char) -> char:

#![allow(unused)]
fn main() {
use appcui::prelude::*;

fn leet(c: char) -> char {
    match c {
        'o' | 'O' => '0',
        'l' | 'L' => '1',
        'e' | 'E' => '3',
        _ => c,
    }
}

let format = TextFormatBuilder::new()
    .position(0, 0)
    .char_variant(CharVariant::Custom(leet))
    .build();
surface.write_text("Hello World", &format); // writes: H3110 W0r1d
}

Translation rules

The following table describes how each variant translates characters. Any character that is not listed in the Translation column (punctuation, spaces, accented letters, other Unicode characters, etc.) is left unchanged.

Examples

The following table shows how the text Hello World 2026 is displayed with each variant:

Writing the same text with multiple variants

The following example writes Hello World 2026 on several lines of a surface, each one using a different variant:

#![allow(unused)]
fn main() {
use appcui::prelude::*;

let variants = [
    ("None", CharVariant::None),
    ("MathBold", CharVariant::MathBold),
    ("Script", CharVariant::Script),
    ("Fraktur", CharVariant::Fraktur),
    ("DoubleStruck", CharVariant::DoubleStruck),
    ("Circled", CharVariant::Circled),
    ("Superscript", CharVariant::Superscript),
    ("SmallCaps", CharVariant::SmallCaps),
];
let mut surface = Surface::new(40, variants.len() as u32);
for (index, (name, variant)) in variants.iter().enumerate() {
    // the name of the variant (written as it is)
    surface.write_string(0, index as i32, name, CharAttribute::with_fore_color(Color::Gray), false);
    // the text, converted with the current variant
    let format = TextFormatBuilder::new()
        .position(16, index as i32)
        .attribute(CharAttribute::with_color(Color::Yellow, Color::DarkBlue))
        .char_variant(*variant)
        .build();
    surface.write_text("Hello World 2026", &format);
}
}

The result will look like this:

None            Hello World 2026
MathBold        𝐇𝐞𝐥𝐥𝐨 𝐖𝐨𝐫𝐥𝐝 𝟐𝟎𝟐𝟔
Script          ℋℯ𝓁𝓁ℴ 𝒲ℴ𝓇𝓁𝒹 2026
Fraktur         ℌ𝔢𝔩𝔩𝔬 𝔚𝔬𝔯𝔩𝔡 2026
DoubleStruck    ℍ𝕖𝕝𝕝𝕠 𝕎𝕠𝕣𝕝𝕕 𝟚𝟘𝟚𝟞
Circled         Ⓗⓔⓛⓛⓞ Ⓦⓞⓡⓛⓓ ②⓪②⑥
Superscript     ᴴᵉˡˡᵒ ᵂᵒʳˡᵈ ²⁰²⁶
SmallCaps       ʜᴇʟʟᴏ ᴡᴏʀʟᴅ 2026

Remarks

• Char variants are purely visual: the converted characters are different Unicode code points, so text written this way should not be used for copy/paste, search or accessibility purposes.
• Font support differs between terminals. The Mathematical Alphanumeric Symbols (MathBold, Script, Fraktur, DoubleStruck, SansSerif*, Monospace) are widely supported, while some of the Enclosed Alphanumeric Supplement characters (CircledNegative, Squared, SquaredNegative) may be missing or rendered as wide emoji.
• Because the translation is done per character, variants that do not have a form for a specific character (for example Subscript for b, or Squared for digits) simply leave that character as it is.