Crate core_extensions

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::callable::CallExt;

pub use self::callable::CallInto;

pub use self::callable::CallMut;

pub use self::callable::CallRef;

pub use self::integers::IntegerExt;

pub use self::integers::ToTime;

pub use self::iterators::IterCloner;

pub use self::iterators::IterConstructor;

pub use self::iterators::IteratorExt;

pub use self::iterators::LazyOnce;

pub use self::option_result_ext::OptionExt;

pub use self::option_result_ext::ResultExt;

pub use self::option_result_ext::ResultLike;

pub use self::option_result_ext::ResultLikeExt;

pub use self::option_result_ext::TransposeOption;

pub use self::phantom::AsPhantomData;

pub use self::phantom::AndPhantom;

pub use self::phantom::AndPhantomCov;

pub use self::phantom::as_phantom;

pub use self::phantom::as_covariant_phantom;

pub use self::phantom::ContraVariantPhantom;

pub use self::phantom::InvariantPhantom;

pub use self::phantom::InvariantRefPhantom;

pub use self::phantom::VariantDropPhantom;

pub use self::phantom::CovariantPhantom;

pub use self::strings::StringExt;

pub use self::slices::ValSliceExt;

pub use self::slices::SliceExt;

pub use self::transparent_newtype::TransparentNewtype;

pub use self::transparent_newtype::TransparentNewtypeExt;

Modules

callablecallable

Alternatives of the standard Fn/FnMut/FnOnce traits, implementable in stable Rust.

collectionscollections

Extension traits for collection types.

integersintegers

Extension traits for integers and types used in the traits.

iteratorsiterators

Iterator adaptors and constructors.

measure_time

Time measurement.

option_result_extoption_result

Contains extension traits for Option and Result

phantomphantom

PhantomData-related items.

slicesslices

Slice extension traits, and related items.

stringsslices

Extension trait for string types.

transparent_newtypetransparent_newtype

Traits for newtype wrappers.

type_assertstype_asserts

Type-level assertions, most useful for tests.

type_level_booltype_level_bool

Type level booleans

utils

Miscelaneous utility functions

Macros

compile_error_stringifymacro_utils

Stringifies the input tokens, and errors with compile_error.

const_defaultconst_default

Gets the ConstDefault::DEFAULT associated constant for a type.

count_ttsmacro_utils

Counts the amount of token trees passed to this macro, passing the amount to an (optional) callback macro.

delegate_transparent_newtype_impltransparent_newtype

For delegating the implementation of the TransparentNewtype trait to a field.

expr_as_phantomphantom

Gets the type of an expression as a PhantomData, without evaluating the expression.

gen_ident_rangemacro_utils

Generates identifiers. passing them to a callback macro.

getconstconst_val

Gets the ConstVal::VAL associated constant for a type.

impl_callcallable

This macro allows more ergonomically implementing the CallRef / CallMut / CallInto traits .

impl_parse_genericsitem_parsing

For parsing impl blocks, transforming the generic parameters to a form easily parsable by the callback macro.

impl_splititem_parsing

For parsing impl blocks, passing the generic parameters unchanged to a callback macro.

impl_transparent_newtypetransparent_newtype

For implementing the TransparentNewtype trait, to cast between a field and Self.

iter_cloneriterators

Use this macro to create an IterCloner from an IntoIterator (this includes all Iterators).

map_phantomdataphantom

Maps a PhantomData<T> to a PhantomData<U> by using a FnOnce(T) -> U closure.

matches

Evaluates to true if the expression matches any of the patterns (this macro can have multiple patterns).

parenthesize_argsmacro_utils

Adaptor macro which passes arguments to a callback macro, wrapping them in parentheses.

parse_genericsgenerics_parsing

Transforms generic parameters for use in type definitions, impl blocks and generic arguments, passing them to a callback macro.

parse_generics_and_wheregenerics_parsing

For writing macros that parse item definitions, with the generic parameters transformed for use in type definitions, impl blocks and generic arguments.

parse_split_genericsgenerics_parsing

Transforms generic parameters to a form easily parsable by a callback macro.

parse_split_generics_and_wheregenerics_parsing

For parsing item definitions, transforming generics to a form easily parsable by a callback macro.

quasiconstconst_val

Declare types that emulate generic constants.

return_type_phantomphantom

Gets the return type of a parameterless closure as a PhantomData

rewrap_macro_parametersmacro_utils

Rewraps the tokens inside macro parameters into parentheses.

split_generics_and_wheregenerics_parsing

For parsing item definitions, passing the generic parameters unchanged to a callback macro.