RUST-960 Deprecate decimal128 feature flag (#288)

Author: patrickfreed

Cargo.toml

@@ -34,7 +34,10 @@ exclude = [
 default = []
 # attempt to encode unsigned types in signed types
 u2i = []
-# Decimal128 in BSON 1.1
+# Experimental / unstable Decimal128 support
+# Note: this feature is deprecated and will be removed in 2.0.0.
+# The feature is not recommended for use as it causes decimal128
+# values to be serialized incorrectly to BSON.
 decimal128 = ["decimal"]
 
 [lib]

src/de/mod.rs

@@ -162,6 +162,7 @@ fn read_f128<R: Read + ?Sized>(reader: &mut R) -> Result<Decimal128> {
 }
 
 #[cfg(feature = "decimal128")]
+#[allow(deprecated)]
 #[inline]
 fn read_f128<R: Read + ?Sized>(reader: &mut R) -> Result<Decimal128> {
     let mut local_buf = [0u8; 16];

src/decimal128.rs

@@ -10,8 +10,12 @@ use std::fmt;
 /// deserialized from existing documents that contain BSON decimal128s.
 ///
 /// Experimental functionality can be enabled through the usage of the `"decimal128"`
-/// feature flag. Note that the API and behavior of such functionality are unstable and
-/// subject to change.
+/// feature flag. The flag is not recommended for use however, as it causes `Decimal128` values to
+/// serialize to BSON incorrectly. See [this issue](https://github.com/mongodb/bson-rust/issues/282#issuecomment-889958970) for
+/// more information.
+///
+/// Note that the API and behavior of the feature-gated functionality are unstable and subject to
+/// change, and the feature flag will be removed completely in 2.0.0.
 #[derive(Clone, PartialEq, PartialOrd)]
 pub struct Decimal128 {
     #[cfg(not(feature = "decimal128"))]
@@ -23,6 +27,8 @@ pub struct Decimal128 {
 }
 
 #[cfg(feature = "decimal128")]
+#[deprecated = "The feature-gated decimal128 implementation serializes to BSON incorrectly and \
+                should not be used. It will be removed completely in 2.0.0"]
 impl Decimal128 {
     /// Construct a `Decimal128` from string.
     ///
@@ -231,6 +237,7 @@ impl fmt::LowerExp for Decimal128 {
 }
 
 #[cfg(feature = "decimal128")]
+#[allow(deprecated)]
 impl std::str::FromStr for Decimal128 {
     type Err = ();
     fn from_str(s: &str) -> Result<Decimal128, ()> {
@@ -253,6 +260,7 @@ impl From<d128> for Decimal128 {
 }
 
 #[cfg(feature = "decimal128")]
+#[allow(deprecated)]
 impl Default for Decimal128 {
     fn default() -> Decimal128 {
         Decimal128::zero()
@@ -261,6 +269,7 @@ impl Default for Decimal128 {
 
 #[cfg(test)]
 #[cfg(feature = "decimal128")]
+#[allow(deprecated)]
 mod test {
     use super::*;
 

src/ser/mod.rs

@@ -79,6 +79,7 @@ fn write_f64<W: Write + ?Sized>(writer: &mut W, val: f64) -> Result<()> {
 }
 
 #[cfg(feature = "decimal128")]
+#[allow(deprecated)]
 #[inline]
 fn write_f128<W: Write + ?Sized>(writer: &mut W, val: Decimal128) -> Result<()> {
     let raw = val.to_raw_bytes_le();

src/tests/modules/ordered.rs

@@ -50,6 +50,7 @@ fn ordered_insert_shorthand() {
 }
 
 #[cfg(feature = "decimal128")]
+#[allow(deprecated)]
 fn test_decimal128(doc: &mut Document) {
     let _guard = LOCK.run_concurrently();
     let dec = Decimal128::from_str("968E+1");

src/tests/modules/ser.rs

@@ -69,6 +69,7 @@ fn int32() {
 }
 
 #[cfg(feature = "decimal128")]
+#[allow(deprecated)]
 #[test]
 fn dec128() {
     let _guard = LOCK.run_concurrently();

src/tests/modules/serializer_deserializer.rs

@@ -386,6 +386,7 @@ fn test_deserialize_multiply_overflows_issue64() {
 }
 
 #[cfg(feature = "decimal128")]
+#[allow(deprecated)]
 #[test]
 fn test_serialize_deserialize_decimal128() {
     let _guard = LOCK.run_concurrently();