Crate konst

Source
Expand description

Const equivalents of std functions, compile-time comparison, and parsing.

§Features

This crate provides:

§Examples

§Parsing an enum

This example demonstrates how you can parse a simple enum from an environment variable, at compile-time.

use konst::eq_str;
use konst::{unwrap_opt_or, unwrap_ctx};

#[derive(Debug, PartialEq)]
enum Direction {
    Forward,
    Backward,
    Left,
    Right,
}

impl Direction {
    const fn try_parse(input: &str) -> Result<Self, ParseDirectionError> {
        // As of Rust 1.51.0, string patterns don't work in const contexts
        match () {
            _ if eq_str(input, "forward") => Ok(Direction::Forward),
            _ if eq_str(input, "backward") => Ok(Direction::Backward),
            _ if eq_str(input, "left") => Ok(Direction::Left),
            _ if eq_str(input, "right") => Ok(Direction::Right),
            _ => Err(ParseDirectionError),
        }
    }
}

const CHOICE: &str = unwrap_opt_or!(option_env!("chosen-direction"), "forward");

const DIRECTION: Direction = unwrap_ctx!(Direction::try_parse(CHOICE));

fn main() {
    match DIRECTION {
        Direction::Forward => assert_eq!(CHOICE, "forward"),
        Direction::Backward => assert_eq!(CHOICE, "backward"),
        Direction::Left => assert_eq!(CHOICE, "left"),
        Direction::Right => assert_eq!(CHOICE, "right"),
    }
}

§Parsing CSV

This example demonstrates how an CSV environment variable can be parsed into integers.

This requires the "rust_1_64" and ""parsing_no_proc"" features (the latter is enabled by default).

ⓘ
use konst::{
    primitive::parse_u64,
    result::unwrap_ctx,
    iter, string,
};

const CSV: &str = env!("NUMBERS");

static PARSED: [u64; 5] = iter::collect_const!(u64 =>
    string::split(CSV, ","),
        map(string::trim),
        map(|s| unwrap_ctx!(parse_u64(s))),
);

assert_eq!(PARSED, [3, 8, 13, 21, 34]);

§Parsing a struct

This example demonstrates how you can use Parser to parse a struct at compile-time.

ⓘ
use konst::{
    parsing::{Parser, ParseValueResult},
    for_range, parse_any, try_rebind, unwrap_ctx,
};

const PARSED: Struct = {
    // You can also parse strings from environment variables, or from an `include_str!(....)`
    let input = "\
        1000,
        circle,
        red, blue, green, blue,
    ";
     
    unwrap_ctx!(parse_struct(Parser::from_str(input))).0
};

fn main(){
    assert_eq!(
        PARSED,
        Struct{
            amount: 1000,
            repeating: Shape::Circle,
            colors: [Color::Red, Color::Blue, Color::Green, Color::Blue],
        }
    );
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Struct {
    pub amount: usize,
    pub repeating: Shape,
    pub colors: [Color; 4],
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Shape {
    Circle,
    Square,
    Line,
}

#[derive(Debug, Copy, Clone, PartialEq, Eq)]
pub enum Color {
    Red,
    Blue,
    Green,
}

pub const fn parse_struct(mut parser: Parser<'_>) -> ParseValueResult<'_, Struct> {
    try_rebind!{(let amount, parser) = parser.trim_start().parse_usize()}
    try_rebind!{parser = parser.strip_prefix(",")}

    try_rebind!{(let repeating, parser) = parse_shape(parser.trim_start())}
    try_rebind!{parser = parser.strip_prefix(",")}

    try_rebind!{(let colors, parser) = parse_colors(parser.trim_start())}

    Ok((Struct{amount, repeating, colors}, parser))
}

pub const fn parse_shape(mut parser: Parser<'_>) -> ParseValueResult<'_, Shape> {
    let shape = parse_any!{parser, strip_prefix;
        "circle" => Shape::Circle,
        "square" => Shape::Square,
        "line" => Shape::Line,
        _ => return Err(parser.into_other_error())
    };
    Ok((shape, parser))
}

pub const fn parse_colors(mut parser: Parser<'_>) -> ParseValueResult<'_, [Color; 4]> {
    let mut colors = [Color::Red; 4];

    for_range!{i in 0..4 =>
        try_rebind!{(colors[i], parser) = parse_color(parser.trim_start())}
        try_rebind!{parser = parser.strip_prefix(",")}
    }

    Ok((colors, parser))
}

pub const fn parse_color(mut parser: Parser<'_>) -> ParseValueResult<'_, Color> {
    let color = parse_any!{parser, strip_prefix;
        "red" => Color::Red,
        "blue" => Color::Blue,
        "green" => Color::Green,
        _ => return Err(parser.into_other_error())
    };
    Ok((color, parser))
}

§Cargo features

These are the features of these crates:

  • "cmp"(enabled by default): Enables all comparison functions and macros, the string equality and ordering comparison functions don’t require this feature.

  • "parsing"(enabled by default): Enables the "parsing_no_proc" feature, compiles the konst_proc_macros dependency, and enables the parse_any macro. You can use this feature instead of "parsing_no_proc" if the slightly longer compile times aren’t a problem.

  • "parsing_no_proc"(enabled by default): Enables the parsing module (for parsing from &str and &[u8]), the primitive::parse_* functions, try_rebind, and rebind_if_ok macros.

  • alloc": Enables items that use types from the alloc crate, including Vec and String.

None of thse features are enabled by default.

  • "rust_1_51": Enables items that require const generics, and impls for arrays to use const generics instead of only supporting small arrays.

  • "rust_1_55": Enables the string::from_utf8 function (the macro works in all versions), str indexing functions, and the "rust_1_51" feature.

  • "rust_1_56": Enables items that internally use raw pointer dereferences or transmutes, and the "rust_1_55" feature.

  • "rust_1_57": Allows konst to use the panic macro, and enables the "rust_1_56" feature.

  • "rust_1_61": Enables const fns that use trait bounds, and the "rust_1_57" feature.

  • "rust_1_64":
    Adds slice and string iterators, string splitting functions([r]split_once), const equivalents of iterator methods(in konst::iter), and makes slicing functions more efficient.
    Note that only functions which mention this feature in their documentation are affected.
    Enables the "rust_1_61" feature.

  • "rust_latest_stable": enables the latest "rust_1_*" feature. Only recommendable if you can update the Rust compiler every stable release.

  • "mut_refs"(disabled by default): Enables const functions that take mutable references. Use this whenever mutable references in const contexts are stabilized. Also enables the "rust_latest_stable" feature.

  • "nightly_mut_refs"(disabled by default): Enables the "mut_refs" feature. Requires Rust nightly.

§No-std support

konst is #![no_std], it can be used anywhere Rust can be used.

§Minimum Supported Rust Version

konst requires Rust 1.46.0, because it uses looping an branching in const contexts.

Features that require newer versions of Rust, or the nightly compiler, need to be explicitly enabled with cargo features.

Re-exports§

pub use crate::string::cmp_str;
pub use crate::string::eq_str;
pub use crate::result::unwrap_ctx;

Modules§

array
Const equivalents of array functions.
iter
Const equivalent of iterators with a specific next function signature.
manually_drop
Const fn equivalents of ManuallyDrop<T> methods.
maybe_uninit
Const fn equivalents of MaybeUninit<T> methods.
nonzero
const fn equivalents of NonZero* methods.
option
const equivalents of Option methods.
other
const fn equivalents of methods from miscelaneous standard library types.
primitive
const fn equivalents of primitive type methods.
ptr
Const equivalents of raw pointer and NonNull methods.
range
const fn equivalents of range methods.
result
const equivalents of Result methods.
slice
const fn equivalents of slice methods.
string
const fn equivalents of str methods.

Macros§

for_range
For loop over a range
konst
Emulates the inline const feature, eg: const{ foo() },
try_
?-like macro, which allows optionally mapping errors.
try_opt
?-like macro for Options.
unwrap_opt_orDeprecated
For unwrapping Options in const contexts, with a default value when it’s a None.
unwrap_res_orDeprecated
For unwrapping Results in const contexts, with a default value when it’s an error.