culit - Custom Literals in Rust

You probably know that numbers in Rust can be suffixed to specify their type, e.g. 100i32. But did you know that syntactically any literal can have a suffix? And did you know that the suffix can be whatever you want?

This crate provides an attribute macro #[culit] for "Custom Literals". When applied to any statement, it enables using custom literals in that statement.

[dependencies]
culit = "0.2"

Note: culit does not have any dependencies such as syn or quote, and it is a simple mapping SourceCode -> SourceCode, so compile-speeds will be very fast.

Example

A NonZeroUsize literal that fails to compile if it is 0: 100nzusize

use culit::culit;
use std::num::NonZeroUsize;

#[culit]
fn main() {
    assert_eq!(100nzusize, NonZeroUsize::new(100).unwrap());
    // COMPILE ERROR!
    // let illegal = 0nzusize;
}

mod custom_literal {
    pub mod integer {
        macro_rules! nzusize {
            // handle `0` specially
            (0) => {
                compile_error!("`0` is not a valid `NonZeroUsize`")
            };
            ($value:literal) => {
                const { NonZeroUsize::new($value).unwrap() }
            };
        }
        pub(crate) use nzusize;
    }
}

IDE Support

Hovering over the custom literals shows documentation for the macro that generates them. You can also do "goto definition". It's quite nice!

More Examples

Python-like f-strings: "hello {name}"f

use culit::culit;
use std::time::Duration;

#[culit]
fn main() {
    let name = "bob";
    let age = 23;

    assert_eq!(
        "hi, my name is {name} and I am {age} years old"f,
        format!("hi, my name is {name} and I am {age} years old")
    );
}

mod custom_literal {
    pub mod string {
        macro_rules! f {
            ($value:literal) => {
                format!($value)
            };
        }
        pub(crate) use f;
    }
}

Duration literals: 100m, 2h...

use culit::culit;
use std::time::Duration;

#[culit]
fn main() {
    assert_eq!(
        100d + 11h + 8m + 7s,
        Duration::from_secs(100 * 60 * 60 * 24)
        + Duration::from_secs(11 * 60 * 60)
        + Duration::from_secs(8 * 60)
        + Duration::from_secs(7)
    );
}

mod custom_literal {
    pub mod integer {
        // day
        macro_rules! d {
            ($value:literal) => {
                Duration::from_secs(60 * 60 * 24 * $value)
            };
        }
        pub(crate) use d;

        // hour
        macro_rules! h {
            ($value:literal) => {
                Duration::from_secs(60 * 60 * $value)
            };
        }
        pub(crate) use h;

        // minute
        macro_rules! m {
            ($value:literal) => {
                Duration::from_secs(60 * $value)
            };
        }
        pub(crate) use m;

        // second
        macro_rules! s {
            ($value:literal) => {
                Duration::from_secs($value)
            };
        }
        pub(crate) use s;
    }
}

The possibilities are endless!

Details

#[culit] replaces every literal that has a custom suffix with a call to the macro at crate::custom_literal::<type>::<suffix>!(...), for example:

• 100km expands to crate::custom_literal::int::km!(100)
• 70.8e7feet expands to crate::custom_literal::float::feet!(70 8 7)
  • 70 is the part before the decimal
  • 8 is the part after the decimal. If missing like in 70e8 then it defaults to 0
  • 7 is the exponent. If missing like in 70.0 then it defaults to 1
• 'a'ascii expands to crate::custom_literal::char::ascii!('a')
• b'a'ascii expands to crate::custom_literal::byte_char::ascii!(97)
• "foo"bar expands to crate::custom_literal::str::bar!("foo")
• b"foo"bar expands to crate::custom_literal::byte_str::bar!(b"foo")
• c"foo"bar expands to crate::custom_literal::c_str::bar!(c"foo")

Skeleton

Here's a skeleton for the custom_literal module which must exist at crate::custom_literal. This module adds a new literal for every type of literal:

mod custom_literal {
    pub mod integer {
        // 0x100custom
        macro_rules! custom {
            ($value:literal) => {
                // ...
            }
        }
        pub(crate) use custom;
    }

    pub mod decimal {
        // 70.3141e-100custom
        //
        // ^^ integral              70
        //    ^^^^ fractional       3141
        //         ^^^ exponent    -100
        macro_rules! custom {
            ($integral:literal $fractional:literal $exponent:literal) => {
                // ...
            }
        }
        pub(crate) use custom;
    }

    pub mod string {
        // "foo_bar"custom
        // ^^^^^^^^^ value - "foo_bar"
        macro_rules! custom {
            ($value:literal) => {
                // ...
            }
        }
        pub(crate) use custom;
    }

    pub mod character {
        // 'x'custom
        // ^^^ value - 'x'
        macro_rules! custom {
            ($value:literal) => {
                // ...
            }
        }
        pub(crate) use custom;
    }

    pub mod byte_character {
        // b'a'custom
        //   ^ value - 97
        macro_rules! custom {
            ($value:literal) => {
                // ...
            }
        }
        pub(crate) use custom;
    }

    pub mod byte_string {
        // b"foo_bar"custom
        // ^^^^^^^^^^ value - b"foo_bar"
        macro_rules! custom {
            ($value:literal) => {
                // ...
            }
        }
        pub(crate) use custom;
    }

    pub mod c_string {
        // c"string"custom
        // ^^^^^^^^^ value - c"string"
        macro_rules! custom {
            ($value:literal) => {
                // ...
            }
        }
        pub(crate) use custom;
    }
}

Nightly

You need to use #[culit] attribute everywhere you want to use these literals. On nightly, you can apply it on the module:

#![feature(custom_inner_attributes)]
#![feature(proc_macro_hygiene)]
#![culit::culit]

While this works, I wouldn't recommend it - currently rust-analyzer is unable to properly work with custom inner attributes that modify the whole crate. For example, if you write 0nzusize which produces a compiler error, the span of the error will point to the macro crate::custom_literal::int::nzusize but not the actual 0nzusize, which makes it very hard to debug these