borsh/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2
3/*!
4
5# Crate features
6
7### Ecosystem features
8
9* **std** -
10  When enabled, `borsh` uses the standard library. Disabling this feature will
11  result in building the crate in `no_std` environment.
12
13  To carter such builds, Borsh offers [`io`] module which includes a items which
14  are used in [`BorshSerialize`] and [`BorshDeserialize`] traits.  Most notably
15  `io::Read`, `io::Write` and `io::Result`.
16
17  When **std** feature is enabled, those items are re-exports of corresponding
18  `std::io` items.  Otherwise they are borsh-specific types which mimic
19  behaviour of corresponding standard types.
20
21### Default features
22
23* **std** - enabled by default.
24
25### Other features
26
27* **derive** -
28  Gates derive macros of [BorshSerialize] and
29  [BorshDeserialize] traits.
30* **unstable__schema** -
31  Gates [BorshSchema] trait and its derive macro.
32  Gates [schema] module.
33  This feature requires **derive** to be enabled too.
34* **rc** -
35  Gates implementation of [BorshSerialize] and [BorshDeserialize]
36  for [`Rc<T>`](std::rc::Rc)/[`Arc<T>`](std::sync::Arc) respectively.
37  In `no_std` setting `Rc`/`Arc` are pulled from `alloc` crate.
38  Serializing and deserializing these types
39  does not preserve identity and may result in multiple copies of the same data.
40  Be sure that this is what you want before enabling this feature.
41* **hashbrown** -
42  Pulls in [HashMap](std::collections::HashMap)/[HashSet](std::collections::HashSet) when no `std` is available.
43  This feature is set to be mutually exclusive with **std** feature.
44* **bytes** -
45  Gates implementation of [BorshSerialize] and [BorshDeserialize]
46  for [Bytes](https://docs.rs/bytes/1.5.0/bytes/struct.Bytes.html) and [BytesMut](https://docs.rs/bytes/1.5.0/bytes/struct.BytesMut.html).
47* **bson** -
48  Gates implementation of [BorshSerialize] and [BorshDeserialize]
49  for [ObjectId](https://docs.rs/bson/2.9.0/bson/oid/struct.ObjectId.html).
50* **ascii** -
51  Gates implementation of [BorshSerialize], [BorshDeserialize], [BorshSchema] for
52  types from [ascii](https://docs.rs/ascii/1.1.0/ascii/) crate.
53* **de_strict_order** -
54  Enables check that keys, parsed during deserialization of
55  [HashMap](std::collections::HashMap)/[HashSet](std::collections::HashSet) and
56  [BTreeSet](std::collections::BTreeSet)/[BTreeMap](std::collections::BTreeMap)
57  are encountered in ascending order with respect to [PartialOrd] for hash collections,
58  and [Ord] for btree ones. Deserialization emits error otherwise.
59
60  If this feature is not enabled, it is possible that two different byte slices could deserialize into the same `HashMap`/`HashSet` object.
61
62### Config aliases
63
64* **hash_collections** -
65  This is a feature alias, set up in `build.rs` to be equivalent to (**std** OR **hashbrown**).
66  Gates implementation of [BorshSerialize], [BorshDeserialize]
67  and [BorshSchema]
68  for [HashMap](std::collections::HashMap)/[HashSet](std::collections::HashSet).
69
70
71*/
72
73#[cfg(not(feature = "std"))]
74extern crate alloc;
75
76/// Derive macro available if borsh is built with `features = ["unstable__schema"]`.
77#[cfg(feature = "unstable__schema")]
78pub use borsh_derive::BorshSchema;
79
80/// Derive macro available if borsh is built with `features = ["derive"]`.
81#[cfg(feature = "derive")]
82pub use borsh_derive::{BorshDeserialize, BorshSerialize};
83
84pub mod de;
85
86// See `hash_collections` alias definition in build.rs
87/// Module is available if borsh is built with `features = ["unstable__schema"]`.
88#[cfg(feature = "unstable__schema")]
89pub mod schema;
90#[cfg(feature = "unstable__schema")]
91pub(crate) mod schema_helpers;
92pub mod ser;
93
94pub use de::BorshDeserialize;
95pub use de::{from_reader, from_slice};
96#[cfg(feature = "unstable__schema")]
97pub use schema::BorshSchema;
98#[cfg(feature = "unstable__schema")]
99pub use schema_helpers::{
100    max_serialized_size, schema_container_of, try_from_slice_with_schema, try_to_vec_with_schema,
101};
102pub use ser::helpers::{object_length, to_vec, to_writer};
103pub use ser::BorshSerialize;
104pub mod error;
105
106#[cfg(all(feature = "std", feature = "hashbrown"))]
107compile_error!("feature \"std\" and feature \"hashbrown\" don't make sense at the same time");
108
109#[cfg(feature = "std")]
110use std::io as io_impl;
111#[cfg(not(feature = "std"))]
112mod nostd_io;
113#[cfg(not(feature = "std"))]
114use nostd_io as io_impl;
115
116/// Subset of `std::io` which is used as part of borsh public API.
117///
118/// When crate is built with `std` feature disabled (it’s enabled by default),
119/// the exported types are custom borsh types which try to mimic behaviour of
120/// corresponding standard types usually offering subset of features.
121pub mod io {
122    pub use super::io_impl::{Error, ErrorKind, Read, Result, Write};
123}
124
125#[doc(hidden)]
126pub mod __private {
127
128    /// A facade around all the types we need from the `std`, and `alloc`
129    /// crates. This avoids elaborate import wrangling having to happen in every
130    /// module.
131    #[cfg(feature = "std")]
132    pub mod maybestd {
133        pub use std::{borrow, boxed, collections, format, string, vec};
134
135        #[cfg(feature = "rc")]
136        pub use std::{rc, sync};
137    }
138    #[cfg(not(feature = "std"))]
139    pub mod maybestd {
140        pub use alloc::{borrow, boxed, format, string, vec};
141
142        #[cfg(feature = "rc")]
143        pub use alloc::{rc, sync};
144
145        pub mod collections {
146            pub use alloc::collections::{btree_map, BTreeMap, BTreeSet, LinkedList, VecDeque};
147            #[cfg(feature = "hashbrown")]
148            pub use hashbrown::*;
149        }
150    }
151}
borsh/lib.rs

borsh/
lib.rs
