Extension traits for many standard/core library types/traits. and other miscelaneuous types / traits / functions / macros.

Adding as dependency

This crate requires cargo features for enabling items, to get all of them you can use:

[dependencies.core_extensions]
version = "1.5"
features = [
    # enables items that use anything from the standard `std` or `alloc` crates.
    "std",
    # Requires the latest stable release, enables all the rust-version-dependent features
    "rust_latest_stable",
    # enables all the item features 
    "all_items",
]

The "std" feature is required to enable impls and items that use std types, otherwise only the core library is supported.

"rust_latest_stable" enables all the "rust_1_*" crate features to use the newest stable language features, here's a list of all the "rust_1_*" features,

"all_items" enables all of the features for enabling items from this crate (documented here):

Here is the expanded version of the above configuration:

[dependencies.core_extensions]
version = "1.5"
features = [
    "std",
    "rust_latest_stable"
    # all of the features below are what "all_items" enables
    "derive"
    "bools",
    "callable",
    "collections",
    "const_default",
    "const_val",
    "generics_parsing",
    "integers",
    "item_parsing",
    "iterators",
    "macro_utils",
    "marker_type",
    "on_drop",
    "option_result",
    "phantom",
    "self_ops",
    "slices",
    "strings",
    "transparent_newtype",
    "type_asserts",
    "type_identity",
    "type_level_bool",
    "void",
]

Examples

Showcasing some features from this crate.

quasiconst, generic constants.

The quasiconst macro allows emulating generic constants by generating a zero-sized generic type that implements the ConstVal trait, the preferred way to get its value is the getconst macro.

This example demonstrates how you can use them to declare a generic VTABLE constant.

use core_extensions::{getconst, quasiconst};

use std::fmt::{self, Debug};


quasiconst!{
    pub const VTABLE<T: Debug>: &'static Vtable = &Vtable {
        size: std::mem::size_of::<T>(),
        align: std::mem::align_of::<T>(),
        drop: drop_erased::<T>,
        fmt: debug_fmt_erased::<T>,
    };
}

fn main() {
    const VTABLE_U8: &'static Vtable = getconst!(VTABLE<u8>);
    assert_eq!(VTABLE_U8.size, 1);
    assert_eq!(VTABLE_U8.align, 1);

    const VTABLE_USIZE: &'static Vtable = getconst!(VTABLE<usize>);
    assert_eq!(VTABLE_USIZE.size, std::mem::size_of::<usize>());
    assert_eq!(VTABLE_USIZE.align, std::mem::align_of::<usize>());

    const VTABLE_STRING: &'static Vtable = getconst!(VTABLE<&str>);
    assert_eq!(VTABLE_STRING.size, std::mem::size_of::<usize>() * 2);
    assert_eq!(VTABLE_STRING.align, std::mem::align_of::<usize>());
}



pub struct Vtable {
    pub size: usize,
    pub align: usize,
    pub drop: unsafe fn(*mut ()),
    pub fmt: unsafe fn(*const (), &mut fmt::Formatter<'_>) -> fmt::Result,
}

unsafe fn drop_erased<T>(ptr: *mut ()) {
    std::ptr::drop_in_place(ptr as *mut T)
}

unsafe fn debug_fmt_erased<T>(ptr: *const (), f: &mut fmt::Formatter<'_>) -> fmt::Result 
where
    T: Debug,
{
    let this = unsafe{ &*(ptr as *const T) };
    
    Debug::fmt(this, f)
}

Cargo Features

Item features

Item features enables items from this crate.

The "all_items" feature enables all of these features, you can use it instead of the ones below if you don't mind longer compile-times.

The "all_items_no_derive" feature eanbles all the features below except for the "derive" feature, to reduce compile-times due to enabling the syn indirect dependency.

• "derive": Enables derive macros for traits declared in core_extensions. If a trait has a derive macro it'll mention and link to it.

• "bools": Enables the BoolExt trait, extension trait for bool.

• "callable": Enables the callable module, with stably implementable equivalents of the Fn* traits.

• "collections": Enables the collections module, with traits for collection types.

• "const_default": Enables the ConstDefault trait, and const_default macro, for a const equivalent of the Default trait.

• "const_val": Enables the ConstVal trait (for types that represent constants), getconst macro (for getting the ConstVal::VAL associated constant), and quasiconst macro (for declaring types that emulate generic constants). Enables the "generics_parsing" feature.

• "macro_utils: Enables the rewrap_macro_parameters, count_tts, gen_ident_range, tokens_method, compile_error_stringify, and parenthesize_args macro. Also enables the macro_attr attribute.

• "generics_parsing": Enables the parse_generics, parse_generics_and_where, split_generics_and_where, parse_split_generics, and parse_split_generics_and_where macros. These allow macros to parse items with generic parameters.

• "item_parsing": Enables the "macro_utils and "generics_parsing" features. Enables the impl_parse_generics and impl_split macros.

• "integers": Enables the integers module, with extension traits for integer types.

• "iterators": Enables the iterators module, with the IteratorExt extension trait for iterators, and a few iterator types.

• "marker_type": Enables the MarkerType trait, for trivially constructible, zero-sized, and aligned-to-1 types.

• "on_drop": Enables the RunOnDrop type, a wrapper type that runs a closure at the end of the scope.

• "option_result": Enables the option_result_ext module, with traits for Option and Result-like types.

• "phantom": Enables the phantom module(with PhantomData-related items), expr_as_phantom macro,map_phantomdata macro, and return_type_phantom macro.

• "self_ops": Enables the SelfOps trait, an extension trait for all types. It primarily has methods for calling free functions as methods.

• "slices": Enables the slices module, with extension traits for [T] and str slices.

• "strings": Enables the strings module, with the StringExt extension trait for strings.

• "transparent_newtype": Enables the transparent_newtype module, with extension traits and functions for #[repr(transparent)] newtypes with public fields.

• "type_asserts": Enables the type_asserts module, with type-level assertiosn, most useful in tests.

• "type_identity": Enables the TypeIdentity trait, for proving that two types are equal, and converting between them in a generic context.

• "type_level_bool": Enables the type_level_bool module, which encodes bools on the type-level.

• "void": Enables the Void type, a type that can't be constructed, for encodign impossible situations.

Rust Version numbers

These features enable code that require some Rust version past the minimum supported one:

• "rust_1_46": Makes TransparentNewtype and TypeIdentity associated functions that take Rc<Self> or Arc<Self> callable as methods.

• "rust_1_51": Enables the "rust_1_46" feature, and impls of traits for all array lengths.

• "rust_latest_stable": Enables all the "rust_1_*" features. This requires the last stable release of Rust, since more "rust_1_*" features can be added at any time.

Support for other crates

All of these are disabled by default:

• "std": Enables std library support. Implies the "alloc" feature.

• "alloc": Enables alloc library support.

• "serde_": Enables serde support.

Miscelaneous features

"track_caller": Enables the "rust_1_46" feature. Changes ResultLike to allow getting the caller location in ResultLike::into_result_, and makes IsNoneError store where it was constructed.

"docsrs": Used to document the required features in docs.rs, requires Rust nightly. Doesn't enable any items itself.

no-std support

This crate works in #![no_std] contexts by default.

Supported Rust versions

This crate support Rust back to 1.41.0, requiring cargo features to use language features from newer versions.

License

core_extensions is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in core_extensions by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.