9 releases (4 breaking)
0.4.3 | Aug 1, 2020 |
---|---|
0.4.2 | Jul 30, 2020 |
0.4.0 | May 16, 2020 |
0.3.1 | Apr 5, 2020 |
0.0.0 | Oct 14, 2019 |
#22 in #structural
119 downloads per month
Used in structural
165KB
4.5K
SLoC
This library provides field accessor traits,and emulation of structural types.
Features
These are some of the features this library provides:
-
Structural
derive macro to implement accessor traits for every public field:GetField
/GetFieldMut
/IntoField
for structs, andGetVariantField
/GetVariantFieldMut
/IntoVariantField
for enums. -
The
StructuralExt
extension trait,which defines the main methods to access fields, so long as the type implements the accessor traits for those fields. -
The
StrucWrapper
wrapper type,defined as an alternative toStructuralExt
. -
The
structural_alias
macro, to declare trait aliases for accessor traits, using field-in-trait syntax. -
The
impl_struct
macro to declare structural parameter/return types, as well asmake_struct
to construct anonymous structs -
The
FromStructural
andTryFromStructural
conversion traits, similar (but not identical) to the standard libraryFrom
andTryFrom
traits for structural types.
Examples
For examples you can look at the examples section of the documentation for the root module of the structural crate
Clarifications
The way that this library emulates structural types is by using traits as bounds or trait objects.
All the structural
traits are dyn-compatible(also known as object-safe),
and no change will be made to make them not dyn-compatible.
By default all structural types are open,
structs and enums can have more variants and or fields than are required.
The only exception to this is exhaustive enums,
in which the variant count and names must match exactly,
this is useful for exhaustive matching of variants (in the switch
macro).
Every trait with the _SI
/_ESI
/_VSI
suffixes in the examples are traits
generated by the Structural
derive macro.
These traits alias the accessor traits implemented by the type they're named after.
Required macros
The only macros that are required to use this crate are the ones for TStr
,
every other macro expands to code that can be written manually
(except for the __TS
type, that is an implementation detail that only macros from
this crate should use by name).
Changelog
The changelog is in the "Changelog.md" file.
Future plans
Making the FromStructural
and TryFromStructural
traits derivable.
no-std support
To use structural
in no_std contexts disable the default-feature.
structural={version="0.4",default_features=false}
This crate has few items that require the std
crate (instead of core).
The "std" and "alloc" features are enabled by default so that users that are not
aware of the core
/alloc
crates don't have to pass a feature to enable std
support.
Cargo Features
These are the cargo features in structural:
-
std
: Enables std support,this is enabled by default. -
alloc
: Enables alloc crate support,this is enabled by default. -
specialization
: Enables specialization inside structural,without enabling the nightly feature flag. This is for the case that specialization is stabilized after the last update to this library. -
nightly_specialization
: Enables specialization inside structural, requires nightly because it enables the nightly feature. -
impl_fields
: This allows usingfield_name: impl Foo
fields in thestructural_alias
macro, which as of 2020-03-21 requires theassociated_type_bounds
Rust nightly feature.
If this doesn't work,try using the "nightly_impl_fields" feature in Rust nightly instead. -
nightly_impl_fields
Equivalent to theimpl_fields
feature, as well as enabling theassociated_type_bounds
nightly features required for using the feature as of 2020-03-21. -
use_const_str
: Changes the internal implementation ofTStr
(the type level string type) to use a&'static str
const parameter instead of types.
Use this if const generics (eg:struct Foo<const S: &'static str>;
) are usable on stable. -
nightly_use_const_str
: Equivalent to theuse_const_str
feature, which also enables the nightly Rust features required for const generics as of 2020-03-21. -
disable_const_str
: Disables const generics, useful if other crates enabling const generics causes internal errors in this Rust version.
Specialization is used inside structural
for performance reasons.
There are no benchmarks comparing when specialization is enabled and disabled yet.
Minimum Rust version
This crate support Rust back to 1.40, and uses a build script to automatically enable features from newer versions.
It requires Rust 1.40 to use proc macros in type position,eg: TS
and FP
.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Structural by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
lib.rs
:
An implementation detail of structural.
Dependencies
~1.7–2.6MB
~57K SLoC