Crate core_extensions

Help

Expand description

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>,
   };
}

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.
Enables the "marker_type" feature.
"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. Enables the "on_drop" feature because RunOnDrop is used by the impls for arrays of all 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.

Re-exports§

pub use self::iterators::IterCloner;
pub use self::iterators::IterConstructor;
pub use self::iterators::IteratorExt;
pub use self::iterators::LazyOnce;
pub use self::strings::StringExt;
pub use self::slices::ValSliceExt;
pub use self::slices::SliceExt;

Modules§

iterators: Iterator adaptors and constructors.
measure_time: Time measurement.
slices: Slice extension traits, and related items.
strings: Extension trait for string types.
type_asserts: Type-level assertions, most useful for tests.
type_level_bool: Type level booleans
utils: Miscelaneous utility functions

Macros§

__priv_usize_const
compile_error_stringify: Stringifies the input tokens, and errors with compile_error.
count_tts: Counts the amount of token trees passed to this macro, passing the amount to an (optional) callback macro.
gen_ident_range: Generates identifiers. passing them to a callback macro.
iter_cloner: Use this macro to create an IterCloner from an IntoIterator (this includes all Iterators).
matches: Evaluates to true if the expression matches any of the patterns (this macro can have multiple patterns).
parenthesize_args: Adaptor macro which passes arguments to a callback macro, wrapping them in parentheses.
rewrap_macro_parameters: Rewraps the tokens inside macro parameters into parentheses.
tokens_method: Does slice and iterator operations on tokens, passing the result to a callback macro.

Enums§

Void: Type for impossible situations.

Traits§

SelfOps: Extension trait for every type.
TypeIdentity: Allows converting Self to Self::Type by proving that both types are equal.

Type Aliases§

TIdentity: A type-level identity function

Attribute Macros§

macro_attr: For using function-like macros as attributes.

Crate core_extensionsCopy item path