Make the parts that use an allocator optional.

Author: hsivonen

Cargo.toml

@@ -16,6 +16,8 @@ categories = ["text-processing", "encoding", "web-programming", "internationaliz
 travis-ci = { repository = "hsivonen/encoding_rs" }
 
 [features]
+default = ["alloc"]
+alloc = []
 simd-accel = ["packed_simd", "packed_simd/into_bits"]
 less-slow-kanji-encode = []
 less-slow-big5-hanzi-encode = []

README.md

@@ -77,11 +77,10 @@ crate provides that capability.
 
 ## `no_std` Environment
 
-The crate works in a `no_std` environment assuming that `alloc` is present.
-The `alloc`-using part are on the outer edge of the crate, so if there is
-interest in using the crate in environments without `alloc` it would be
-feasible to add a way to turn off those parts of the API of this crate that
-use `Vec`/`String`/`Cow`.
+The crate works in a `no_std` environment. By default, the `alloc` feature,
+which assumes that an allocator is present is enabled. For a no-allocator
+environment, the default features (i.e. `alloc`) can be turned off. This
+makes the part of the API that returns `Vec`/`String`/`Cow` unavailable.
 
 ## Decoding Email
 
@@ -432,6 +431,10 @@ To regenerate the generated code:
 
 ## Release Notes
 
+### 0.8.29
+
+* Make the parts that use an allocator optional.
+
 ### 0.8.28
 
 * Fix error in Serde support introduced as part of `no_std` support.

src/ascii.rs

@@ -1508,7 +1508,7 @@ pub fn iso_2022_jp_ascii_valid_up_to(bytes: &[u8]) -> usize {
 // Any copyright to the test code below this comment is dedicated to the
 // Public Domain. http://creativecommons.org/publicdomain/zero/1.0/
 
-#[cfg(test)]
+#[cfg(all(test, feature = "alloc"))]
 mod tests {
     use super::*;
     use alloc::vec::Vec;

src/big5.rs

@@ -263,7 +263,7 @@ impl Big5Encoder {
 // Any copyright to the test code below this comment is dedicated to the
 // Public Domain. http://creativecommons.org/publicdomain/zero/1.0/
 
-#[cfg(test)]
+#[cfg(all(test, feature = "alloc"))]
 mod tests {
     use super::super::testing::*;
     use super::super::*;

src/euc_jp.rs

@@ -346,7 +346,7 @@ impl EucJpEncoder {
 // Any copyright to the test code below this comment is dedicated to the
 // Public Domain. http://creativecommons.org/publicdomain/zero/1.0/
 
-#[cfg(test)]
+#[cfg(all(test, feature = "alloc"))]
 mod tests {
     use super::super::testing::*;
     use super::super::*;

src/euc_kr.rs

@@ -362,7 +362,7 @@ impl EucKrEncoder {
 // Any copyright to the test code below this comment is dedicated to the
 // Public Domain. http://creativecommons.org/publicdomain/zero/1.0/
 
-#[cfg(test)]
+#[cfg(all(test, feature = "alloc"))]
 mod tests {
     use super::super::testing::*;
     use super::super::*;

src/gb18030.rs

@@ -571,7 +571,7 @@ impl Gb18030Encoder {
 // Any copyright to the test code below this comment is dedicated to the
 // Public Domain. http://creativecommons.org/publicdomain/zero/1.0/
 
-#[cfg(test)]
+#[cfg(all(test, feature = "alloc"))]
 mod tests {
     use super::super::testing::*;
     use super::super::*;

src/iso_2022_jp.rs

@@ -754,7 +754,7 @@ impl Iso2022JpEncoder {
 // Any copyright to the test code below this comment is dedicated to the
 // Public Domain. http://creativecommons.org/publicdomain/zero/1.0/
 
-#[cfg(test)]
+#[cfg(all(test, feature = "alloc"))]
 mod tests {
     use super::super::testing::*;
     use super::super::*;

src/lib.rs

@@ -59,6 +59,7 @@
 //! Decode using the non-streaming API:
 //!
 //! ```
+//! #[cfg(feature = "alloc")] {
 //! use encoding_rs::*;
 //!
 //! let expectation = "\u{30CF}\u{30ED}\u{30FC}\u{30FB}\u{30EF}\u{30FC}\u{30EB}\u{30C9}";
@@ -68,6 +69,7 @@
 //! assert_eq!(&cow[..], expectation);
 //! assert_eq!(encoding_used, SHIFT_JIS);
 //! assert!(!had_errors);
+//! }
 //! ```
 //!
 //! Decode using the streaming API with minimal `unsafe`:
@@ -682,8 +684,10 @@
 #![no_std]
 #![cfg_attr(feature = "simd-accel", feature(stdsimd, core_intrinsics))]
 
+#[cfg(feature = "alloc")]
 #[cfg_attr(test, macro_use)]
 extern crate alloc;
+
 extern crate core;
 #[macro_use]
 extern crate cfg_if;
@@ -723,7 +727,7 @@ mod macros;
 ))]
 mod simd_funcs;
 
-#[cfg(test)]
+#[cfg(all(test, feature = "alloc"))]
 mod testing;
 
 mod big5;
@@ -750,8 +754,11 @@ use crate::ascii::iso_2022_jp_ascii_valid_up_to;
 use crate::utf_8::utf8_valid_up_to;
 use crate::variant::*;
 
+#[cfg(feature = "alloc")]
 use alloc::borrow::Cow;
+#[cfg(feature = "alloc")]
 use alloc::string::String;
+#[cfg(feature = "alloc")]
 use alloc::vec::Vec;
 use core::cmp::Ordering;
 use core::hash::Hash;
@@ -2894,6 +2901,7 @@ impl Encoding {
 
     /// Checks whether the bytes 0x00...0x7F map mostly to the characters
     /// U+0000...U+007F and vice versa.
+    #[cfg(feature = "alloc")]
     #[inline]
     fn is_potentially_borrowable(&'static self) -> bool {
         !(self == REPLACEMENT || self == UTF_16BE || self == UTF_16LE)
@@ -2945,7 +2953,9 @@ impl Encoding {
     /// If the size calculation for a heap-allocated backing buffer overflows
     /// `usize`.
     ///
-    /// Available to Rust only.
+    /// Available to Rust only and only with the `alloc` feature enabled (enabled
+    /// by default).
+    #[cfg(feature = "alloc")]
     #[inline]
     pub fn decode<'a>(&'static self, bytes: &'a [u8]) -> (Cow<'a, str>, &'static Encoding, bool) {
         let (encoding, without_bom) = match Encoding::for_bom(bytes) {
@@ -2988,7 +2998,9 @@ impl Encoding {
     /// If the size calculation for a heap-allocated backing buffer overflows
     /// `usize`.
     ///
-    /// Available to Rust only.
+    /// Available to Rust only and only with the `alloc` feature enabled (enabled
+    /// by default).
+    #[cfg(feature = "alloc")]
     #[inline]
     pub fn decode_with_bom_removal<'a>(&'static self, bytes: &'a [u8]) -> (Cow<'a, str>, bool) {
         let without_bom = if self == UTF_8 && bytes.starts_with(b"\xEF\xBB\xBF") {
@@ -3035,7 +3047,9 @@ impl Encoding {
     /// If the size calculation for a heap-allocated backing buffer overflows
     /// `usize`.
     ///
-    /// Available to Rust only.
+    /// Available to Rust only and only with the `alloc` feature enabled (enabled
+    /// by default).
+    #[cfg(feature = "alloc")]
     pub fn decode_without_bom_handling<'a>(&'static self, bytes: &'a [u8]) -> (Cow<'a, str>, bool) {
         let (mut decoder, mut string, mut total_read) = if self.is_potentially_borrowable() {
             let valid_up_to = if self == UTF_8 {
@@ -3130,7 +3144,9 @@ impl Encoding {
     /// If the size calculation for a heap-allocated backing buffer overflows
     /// `usize`.
     ///
-    /// Available to Rust only.
+    /// Available to Rust only and only with the `alloc` feature enabled (enabled
+    /// by default).
+    #[cfg(feature = "alloc")]
     pub fn decode_without_bom_handling_and_without_replacement<'a>(
         &'static self,
         bytes: &'a [u8],
@@ -3225,7 +3241,9 @@ impl Encoding {
     /// If the size calculation for a heap-allocated backing buffer overflows
     /// `usize`.
     ///
-    /// Available to Rust only.
+    /// Available to Rust only and only with the `alloc` feature enabled (enabled
+    /// by default).
+    #[cfg(feature = "alloc")]
     pub fn encode<'a>(&'static self, string: &'a str) -> (Cow<'a, [u8]>, &'static Encoding, bool) {
         let output_encoding = self.output_encoding();
         if output_encoding == UTF_8 {
@@ -3988,7 +4006,9 @@ impl Decoder {
     /// See the documentation of the struct for documentation for `decode_*`
     /// methods collectively.
     ///
-    /// Available to Rust only.
+    /// Available to Rust only and only with the `alloc` feature enabled (enabled
+    /// by default).
+    #[cfg(feature = "alloc")]
     pub fn decode_to_string(
         &mut self,
         src: &[u8],
@@ -4076,7 +4096,9 @@ impl Decoder {
     /// See the documentation of the struct for documentation for `decode_*`
     /// methods collectively.
     ///
-    /// Available to Rust only.
+    /// Available to Rust only and only with the `alloc` feature enabled (enabled
+    /// by default).
+    #[cfg(feature = "alloc")]
     pub fn decode_to_string_without_replacement(
         &mut self,
         src: &[u8],
@@ -4575,7 +4597,9 @@ impl Encoder {
     /// See the documentation of the struct for documentation for `encode_*`
     /// methods collectively.
     ///
-    /// Available to Rust only.
+    /// Available to Rust only and only with the `alloc` feature enabled (enabled
+    /// by default).
+    #[cfg(feature = "alloc")]
     pub fn encode_from_utf8_to_vec(
         &mut self,
         src: &str,
@@ -4613,7 +4637,9 @@ impl Encoder {
     /// See the documentation of the struct for documentation for `encode_*`
     /// methods collectively.
     ///
-    /// Available to Rust only.
+    /// Available to Rust only and only with the `alloc` feature enabled (enabled
+    /// by default).
+    #[cfg(feature = "alloc")]
     pub fn encode_from_utf8_to_vec_without_replacement(
         &mut self,
         src: &str,
@@ -4879,11 +4905,13 @@ fn checked_div(opt: Option<usize>, num: usize) -> Option<usize> {
     }
 }
 
+#[cfg(feature = "alloc")]
 #[inline(always)]
 fn checked_next_power_of_two(opt: Option<usize>) -> Option<usize> {
     opt.map(|n| n.next_power_of_two())
 }
 
+#[cfg(feature = "alloc")]
 #[inline(always)]
 fn checked_min(one: Option<usize>, other: Option<usize>) -> Option<usize> {
     if let Some(a) = one {
@@ -4910,7 +4938,7 @@ struct Demo {
 #[cfg(test)]
 mod test_labels_names;
 
-#[cfg(test)]
+#[cfg(all(test, feature = "alloc"))]
 mod tests {
     use super::*;
     use alloc::borrow::Cow;

src/mem.rs

@@ -24,8 +24,11 @@
 //! The FFI binding for this module are in the
 //! [encoding_c_mem crate](https://github.com/hsivonen/encoding_c_mem).
 
+#[cfg(feature = "alloc")]
 use alloc::borrow::Cow;
+#[cfg(feature = "alloc")]
 use alloc::string::String;
+#[cfg(feature = "alloc")]
 use alloc::vec::Vec;
 
 use super::in_inclusive_range16;
@@ -1988,6 +1991,9 @@ pub fn convert_utf16_to_latin1_lossy(src: &[u16], dst: &mut [u8]) {
 ///
 /// Borrows if input is ASCII-only. Performs a single heap allocation
 /// otherwise.
+///
+/// Only available if the `alloc` feature is enabled (enabled by default).
+#[cfg(feature = "alloc")]
 pub fn decode_latin1<'a>(bytes: &'a [u8]) -> Cow<'a, str> {
     let up_to = ascii_valid_up_to(bytes);
     // >= makes later things optimize better than ==
@@ -2022,6 +2028,9 @@ pub fn decode_latin1<'a>(bytes: &'a [u8]) -> Cow<'a, str> {
 ///
 /// Borrows if input is ASCII-only. Performs a single heap allocation
 /// otherwise.
+///
+/// Only available if the `alloc` feature is enabled (enabled by default).
+#[cfg(feature = "alloc")]
 pub fn encode_latin1_lossy<'a>(string: &'a str) -> Cow<'a, [u8]> {
     let bytes = string.as_bytes();
     let up_to = ascii_valid_up_to(bytes);
@@ -2155,7 +2164,7 @@ pub fn copy_basic_latin_to_ascii(src: &[u16], dst: &mut [u8]) -> usize {
 // Any copyright to the test code below this comment is dedicated to the
 // Public Domain. http://creativecommons.org/publicdomain/zero/1.0/
 
-#[cfg(test)]
+#[cfg(all(test, feature = "alloc"))]
 mod tests {
     use super::*;