Crate core_extensions

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.