Crate try_specialize

Expand description

The try-specialize crate provides limited, zero-cost specialization in generic context on stable Rust.

use try_specialize::TrySpecialize;

fn example_specialize_by_value<T>(value: T) -> Result<u32, T> {
    value.try_specialize()
    // Same as: `<T as TrySpecialize>::try_specialize::<u32>(value)`.
    // `try_specialize::<T>` specializes from `Self` to `T, where T: LifetimeFree`.
}

fn example_specialize_by_ref<T: ?Sized>(value: &T) -> Option<&str> {
    value.try_specialize_ref()
    // Same as: `<T as TrySpecialize>::try_specialize_ref::<str>(value)`.
    // `try_specialize_ref::<T>` specializes from `&Self` to `&T, where T: LifetimeFree`.
}

assert_eq!(example_specialize_by_value(123_u32), Ok(123));
assert_eq!(example_specialize_by_value(123_i32), Err(123));
assert_eq!(example_specialize_by_ref("foo"), Some("foo"));
assert_eq!(example_specialize_by_ref(&123_u32), None);
assert_eq!(example_specialize_by_ref(&[1, 2, 3]), None);

§Introduction

While specialization in Rust can be a tempting solution in many use cases, it is usually more idiomatic to use traits instead. Traits are the idiomatic way to achieve polymorphism in Rust, promoting better code clarity, reusability, and maintainability.

However, specialization can be suitable when you need to optimize performance by providing specialized implementations for some types without altering the code logic. It’s also useful in specific, type-level programming use cases like comparisons between types from different libraries.

For a simple use cases, consider the castaway crate, which offers a much simpler API. On nightly Rust, consider using min_specialization feature instead. The Rust standard library already uses min_specialization for many optimizations. For a more detailed comparison, see the Alternative crates section below.

§About

This crate offers a comprehensive API for addressing various specialization challenges, reducing the need for unsafe code. It provides specialization from unconstrained types, to unconstrained types, between ’static types, and between type references and mutable references, and more.

Library tests ensure that specializations are performed at compile time and are fully optimized with no runtime cost at opt-level >= 1. Note that the release profile uses opt-level = 3 by default.

§Usage

Add this to your Cargo.toml:

[dependencies]
try-specialize = "0.1.2"

Then, you can use TrySpecialize trait methods like TrySpecialize::try_specialize, TrySpecialize::try_specialize_ref and TrySpecialize::try_specialize_static. To check the possibility of specialization in advance and use it infallibly multiple times, including reversed or mapped specialization, use Specialization struct methods.

Note that unlike casting, subtyping, and coercion, specialization does not alter the underlying type or data. It merely qualifies the underlying types of generics, succeeding only when the underlying types of T1 and T2 are equal.

§Examples

Specialize type to any LifetimeFree type:

use try_specialize::TrySpecialize;

fn func<T>(value: T) {
    match value.try_specialize::<(u32, String)>() {
        Ok(value) => specialized_impl(value),
        Err(value) => default_impl(value),
    }
}

fn specialized_impl(_value: (u32, String)) {}
fn default_impl<T>(_value: T) {}

Specialize 'static type to any 'static type:

use try_specialize::TrySpecialize;

fn func<T>(value: T)
where
    T: 'static,
{
    match value.try_specialize_static::<(u32, &'static str)>() {
        Ok(value) => specialized_impl(value),
        Err(value) => default_impl(value),
    }
}

fn specialized_impl(_value: (u32, &'static str)) {}
fn default_impl<T>(_value: T) {}

Specialize Sized or Unsized type reference to any LifetimeFree type reference:

use try_specialize::TrySpecialize;

fn func<T>(value: &T)
where
    T: ?Sized, // Relax the implicit `Sized` bound.
{
    match value.try_specialize_ref::<str>() {
        Some(value) => specialized_impl(value),
        None => default_impl(value),
    }
}

fn specialized_impl(_value: &str) {}
fn default_impl<T: ?Sized>(_value: &T) {}

Specialize Sized or Unsized type mutable reference to any LifetimeFree type mutable reference:

use try_specialize::TrySpecialize;

fn func<T>(value: &mut T)
where
    T: ?Sized, // Relax the implicit `Sized` bound.
{
    match value.try_specialize_mut::<[u8]>() {
        Some(value) => specialized_impl(value),
        None => default_impl(value),
    }
}

fn specialized_impl(_value: &mut [u8]) {}
fn default_impl<T: ?Sized>(_value: &mut T) {}

Specialize a third-party library container with generic types:

use try_specialize::{Specialization, TypeFn};

fn func<K, V>(value: hashbrown::HashMap<K, V>) {
    struct MapIntoHashMap;
    impl<K, V> TypeFn<(K, V)> for MapIntoHashMap {
        type Output = hashbrown::HashMap<K, V>;
    }

    if let Some(spec) = Specialization::<(K, V), (u32, char)>::try_new() {
        let spec = spec.map::<MapIntoHashMap>();
        let value: hashbrown::HashMap<u32, char> = spec.specialize(value);
        specialized_impl(value);
    } else {
        default_impl(value);
    }
}

fn default_impl<K, V>(_value: hashbrown::HashMap<K, V>) {}
fn specialized_impl(_value: hashbrown::HashMap<u32, char>) {}

For a more comprehensive example, see the examples/encode.rs, which implements custom data encoders and decoders with per-type encoding and decoding errors and optimized byte array encoding and decoding. The part of this example related to the Encode implementation for a slice:

// ...

impl<T> Encode for [T]
where
    T: Encode,
{
    type EncodeError = T::EncodeError;

    #[inline]
    fn encode_to<W>(&self, writer: &mut W) -> Result<(), Self::EncodeError>
    where
        W: ?Sized + Write,
    {
        if let Some(spec) = Specialization::<[T], [u8]>::try_new() {
            // Specialize self from `[T; N]` to `[u32; N]`
            let bytes: &[u8] = spec.specialize_ref(self);
            // Map type specialization to its associated error specialization.
            let spec_err = spec.rev().map::<MapToEncodeError>();
            writer
                .write_all(bytes)
                // Specialize error from `io::Error` to `Self::EncodeError`.
                .map_err(|err| spec_err.specialize(err))?;
        } else {
            for item in self {
                item.encode_to(writer)?;
            }
        }
        Ok(())
    }
}

// ...

Find values by type in generic composite types:

use try_specialize::{LifetimeFree, TrySpecialize};

pub trait ConsListLookup {
    fn find<T>(&self) -> Option<&T>
    where
        T: ?Sized + LifetimeFree;
}

impl ConsListLookup for () {
    #[inline]
    fn find<T>(&self) -> Option<&T>
    where
        T: ?Sized + LifetimeFree,
    {
        None
    }
}

impl<T1, T2> ConsListLookup for (T1, T2)
where
    T2: ConsListLookup,
{
    #[inline]
    fn find<T>(&self) -> Option<&T>
    where
        T: ?Sized + LifetimeFree,
    {
        self.0.try_specialize_ref().or_else(|| self.1.find::<T>())
    }
}

#[derive(Eq, PartialEq, Debug)]
struct StaticStr(&'static str);
// SAFETY: It is safe to implement `LifetimeFree` for structs with no
// parameters.
unsafe impl LifetimeFree for StaticStr {}

let input = (
    123_i32,
    (
        [1_u32, 2, 3, 4],
        (1_i32, (StaticStr("foo"), (('a', false), ()))),
    ),
);

assert_eq!(input.find::<u32>(), None);
assert_eq!(input.find::<i32>(), Some(&123_i32));
assert_eq!(input.find::<[u32; 4]>(), Some(&[1, 2, 3, 4]));
assert_eq!(input.find::<[u32]>(), None);
assert_eq!(input.find::<StaticStr>(), Some(&StaticStr("foo")));
assert_eq!(input.find::<char>(), None);
assert_eq!(input.find::<(char, bool)>(), Some(&('a', false)));

§Documentation

API Documentation

§Feature flags

alloc (implied by std, enabled by default): enables LifetimeFree implementations for alloc types, like Box, Arc, String, Vec, BTreeMap etc.
std (enabled by default): enables alloc feature and LifetimeFree implementations for std types, like OsStr, Path, PathBuf, Instant, HashMap etc.
unreliable: enables functions, methods and macros that rely on Rust standard library undocumented behavior. Refer to the unreliable module documentation for details.

§How it works

Type comparison between 'static types compares their TypeId::ofs.
Type comparison between unconstrained and LifetimeFree type treats them as 'static and compares their TypeId::ofs.
Specialization relies on type comparison and transmute_copy when the equality of types is established.
Unreliable trait implementation checks are performed using an expected, but undocumented behavior of the Rust stdlib PartialEq implementation for Arc<T>. Arc::eq uses fast path comparing references before comparing data if T implements Eq.

§Alternative crates

castaway: A similar crate with a much simpler macro-based API. The macro uses Autoref-Based Specialization and automatically determines the appropriate type of specialization, making it much easier to use. However, if no specialization is applicable because of the same Autoref-Based Specialization, the compiler generates completely unclear errors, which makes it difficult to use it in complex cases. Internally uses unsafe code for type comparison and specialization.
coe-rs: Smaller and simpler, but supports only static types and don’t safely combine type equality check and specialization. Internally uses unsafe code for type specialization.
downcast-rs: Specialized on trait objects (dyn) downcasting. Can’t be used to specialize unconstrained types.
syllogism and syllogism_macro: Requires to provide all possible types to macro that generate a lot of boilerplate code and can’t be used to specialize stdlib types because of orphan rules.
specialize: Requires nightly. Adds a simple macro to inline nightly min_specialization usage into simple if let expressions.
specialized-dispatch: Requires nightly. Adds a macro to inline nightly min_specialization usage into a match-like macro.
spez: Specializes expression types, using Autoref-Based Specialization. It won’t works in generic context but can be used in the code generated by macros.
impls: Determine if a type implements a trait. Can’t detect erased type bounds, so not applicable in generic context, but can be used in the code generated by macros.

§Comparison of libraries supporting specialization in generic context:

	crate `try-specialize`	crate `castaway`	crate `coe-rs`	crate `downcast-rs`	crate `syllogism`	`min_spec...` nightly feature	crate `specialize`	crate `spec...ch`
Checked version	`0.1.2`	`0.2.3`	`0.1.2`	`1.2.1`	`0.1.3`	N/A	`0.0.3`	`0.2.1`
Rust toolchain	Stable	Stable	Stable	Stable	Stable	Nightly	Nightly	Nightly
API complexity	Complex	Simple	Simple	Moderate	Simple	Simple	Simple	Simple
API difficulty	Difficult	Easy	Easy	Moderate	Moderate	Easy	Easy	Moderate
Zero-cost (compile-time optimized)	YES	YES	YES	no	YES	YES	YES	YES
Safely combines type eq check and specialization	YES	YES	no	YES	YES	YES	YES	YES
Specialize value references	YES	YES	YES	N/A	YES	YES	YES	no
Specialize values	YES	YES	no	N/A	YES	YES	YES	YES
Specialize values without consume on failure	YES	YES	no	N/A	YES	YES	no	YES
Limited non-static value specialization	YES	YES	no	N/A	YES	YES	YES	YES
Full non-static value specialization	no	no	no	N/A	YES	no	no	no
Specialize trait objects (`dyn`)	N/A	N/A	N/A	YES	N/A	N/A	N/A	N/A
Compare types without instantiation	YES	no	YES	no	YES	YES	YES	no
Support std types	YES	YES	YES	YES	no	YES	YES	YES
Specialize from unconstrained type	YES	YES	no	no	no	YES	YES	YES
Specialize to unconstrained type	YES	no	no	no	no	YES	YES	YES
Check generic implements “erased” trait	YES, but `unreliable`	no	no	no	no	YES	YES	YES
Specialize to generic with added bounds	no	no	no	no	no	YES	YES	YES
API based on	Traits	Macros	Traits	Macros + Traits	Traits	Language	Macros	Macros
Type comparison implementation based on	`TypeId` + `transmute`	`TypeId` + `transmute`	`TypeId`	N/A	Traits	Language	Nightly feature	Nightly feature
Type casting implementation based on	`transmute_copy`	`ptr::read`	`transmute`	`std::any::Any`	Traits	Language	Nightly feature	Nightly feature
Implementation free of `unsafe`	no	no	no	YES	YES	YES	YES	YES

§Primitive example of the value specialization using different libraries

crate `try_specialize`: `use try_specialize::TrySpecialize; fn spec<T>(value: T) -> Result<u32, T> { value.try_specialize() } assert_eq!(spec(42_u32), Ok(42)); assert_eq!(spec(42_i32), Err(42)); assert_eq!(spec("abc"), Err("abc"));`	crate `castaway`: `use castaway::cast; fn spec<T>(value: T) -> Result<u32, T> { cast!(value, _) } assert_eq!(spec(42_u32), Ok(42)); assert_eq!(spec(42_i32), Err(42)); assert_eq!(spec("abc"), Err("abc"));`
crate `coe-rs`: `use coe::{is_same, Coerce}; // Library don't support non-reference. // specialization. Using reference. fn spec<T>(value: &T) -> Option<&u32> where // Library don't support specialization of // unconstrained non-static types. T: 'static, { is_same::<u32, T>().then(\|\| value.coerce()) } fn main() { assert_eq!(spec(&42_u32), Some(&42)); assert_eq!(spec(&42_i32), None); assert_eq!(spec(&"abc"), None); }`	crates `downcast-rs`: use downcast_rs::{impl_downcast, DowncastSync}; trait Base: DowncastSync {} impl_downcast!(sync Base); // Library requires all specializable // types to be defined in advance. impl Base for u32 {} impl Base for i32 {} impl Base for &'static str {} // Library support only trait objects (`dyn`). fn spec(value: &dyn Base) -> Option<&u32> { value.downcast_ref::<u32>() } fn main() { assert_eq!(spec(&42_u32), Some(&42)); assert_eq!(spec(&42_i32), None); assert_eq!(spec(&"abc"), None); }
crate `specialize`: `// Requires nightly. #![feature(min_specialization)] use specialize::constrain; // Library don't support non-consuming // value specialization. Using reference. fn spec<T: ?Sized>(value: &T) -> Option<&u32> { constrain!(ref value as u32) } assert_eq!(spec(&42_u32), Some(&42)); assert_eq!(spec(&42_i32), None); assert_eq!(spec("abc"), None);`	crate `specialized-dispatch`: // Requires nightly. #![feature(min_specialization)] use specialized_dispatch::specialized_dispatch; // The library don't support using generics. // from outer item. Using `Option`. fn spec<T>(value: T) -> Option<u32> { specialized_dispatch! { T -> Option<u32>, fn (value: u32) => Some(value), default fn <T>(_: T) => None, value, } } assert_eq!(spec(42_u32), Some(42)); assert_eq!(spec(42_i32), None); assert_eq!(spec("abc"), None);
crates `syllogism` and `syllogism_macro`: use syllogism::{Distinction, Specialize}; use syllogism_macro::impl_specialization; // Library specialization can not be // implemented for std types because of // orphan rules. Using custom local types. #[derive(Eq, PartialEq, Debug)] struct U32(u32); #[derive(Eq, PartialEq, Debug)] struct I32(i32); #[derive(Eq, PartialEq, Debug)] struct Str<'a>(&'a str); // Library requires all specializable // types to be defined in one place. impl_specialization!( type U32; type I32; type Str<'a>; ); fn spec<T>(value: T) -> Result<U32, T> where T: Specialize<U32>, { match value.specialize() { Distinction::Special(value) => Ok(value), Distinction::Generic(value) => Err(value), } } assert_eq!(spec(U32(42)), Ok(U32(42))); assert_eq!(spec(I32(42_i32)), Err(I32(42))); assert_eq!(spec(Str("abc")), Err(Str("abc")));	`min_specialization` nightly feature: // Requires nightly. #![feature(min_specialization)] // The artificial example looks a bit long. // More real-world use cases are usually // on the contrary more clear and understandable. pub trait Spec: Sized { fn spec(self) -> Result<u32, Self>; } impl<T> Spec for T { default fn spec(self) -> Result<u32, Self> { Err(self) } } impl Spec for u32 { fn spec(self) -> Result<u32, Self> { Ok(self) } } assert_eq!(Spec::spec(42_u32), Ok(42)); assert_eq!(Spec::spec(42_i32), Err(42)); assert_eq!(Spec::spec("abc"), Err("abc"));

§License

Licensed under either of

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

at your option.

§Contribution

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

Modules§

unreliablealloc and unreliable: This module contains a set of functions, traits and macros that depend on undocumented standard library behavior and should therefore be used with caution.

Macros§

define_impls_trait_ignore_lt_fnalloc and unreliable: Generates a function which returns true if the given type implements specified trait. Note that all the lifetimes are erased and not accounted for.

Structs§

Specialization: A zero-sized marker struct that guarantees type equality between T1 and T2.

Traits§

LifetimeFree: A marker trait for types that do not contain any lifetime parameters.
TrySpecialize: A trait for specializing one type to another at runtime.
TypeFn: A trait that defines a mapping between an input type and an output type.

Functions§

static_type_eq: Returns true if the T1 and T2 static types are equal.
type_eq: Returns true if the T1 and T2 types are equal.
type_eq_ignore_lifetimes: Returns true if the Self and T types are equal ignoring their lifetimes.