Merge pull request #1116 from CosmWasm/pair-to-record

Rename Pair to Record

CHANGELOG.md

@@ -41,6 +41,8 @@ and this project adheres to
 - cosmwasm-std: Make methods `Uint256::to_be_bytes`/`::to_le_bytes` const.
 - cosmwasm-std: Make methods `Uint512::to_be_bytes`/`::to_le_bytes` const.
 - cosmwasm-std: Make method `Uint512::from_le_bytes` const.
+- cosmwasm-std: Rename `Pair` to `Record`. `Pair` is now an alias for `Record`
+  and deprecated.
 
 ### Removed
 

MIGRATING.md

@@ -4,6 +4,32 @@ This guide explains what is needed to upgrade contracts when migrating over
 major releases of `cosmwasm`. Note that you can also view the
 [complete CHANGELOG](./CHANGELOG.md) to understand the differences.
 
+## 0.16 -> 1.0 (unreleased)
+
+- Update CosmWasm dependencies in Cargo.toml (skip the ones you don't use):
+
+  ```
+  [dependencies]
+  cosmwasm-std = "1.0.0"
+  cosmwasm-storage = "1.0.0"
+  # ...
+
+  [dev-dependencies]
+  cosmwasm-schema = "1.0.0"
+  cosmwasm-vm = "1.0.0"
+  # ...
+  ```
+
+- Use type `Record` instead of `Pair`
+
+  ```rust
+  // before
+  use cosmwasm_std::Pair;
+
+  // after
+  use cosmwasm_std::Record;
+  ```
+
 ## 0.15 -> 0.16
 
 - Update CosmWasm dependencies in Cargo.toml (skip the ones you don't use):

README.md

@@ -290,7 +290,7 @@ pub trait Storage {
     start: Option<&[u8]>,
     end: Option<&[u8]>,
     order: Order,
-  ) -> Box<dyn Iterator<Item = Pair> + 'a>;
+  ) -> Box<dyn Iterator<Item = Record> + 'a>;
 }
 ```
 

packages/std/src/imports.rs

@@ -13,7 +13,7 @@ use crate::serde::from_slice;
 use crate::traits::{Api, Querier, QuerierResult, Storage};
 #[cfg(feature = "iterator")]
 use crate::{
-    iterator::{Order, Pair},
+    iterator::{Order, Record},
     memory::get_optional_region_address,
 };
 
@@ -108,7 +108,7 @@ impl Storage for ExternalStorage {
         start: Option<&[u8]>,
         end: Option<&[u8]>,
         order: Order,
-    ) -> Box<dyn Iterator<Item = Pair>> {
+    ) -> Box<dyn Iterator<Item = Record>> {
         // There is lots of gotchas on turning options into regions for FFI, thus this design
         // See: https://github.com/CosmWasm/cosmwasm/pull/509
         let start_region = start.map(build_region);
@@ -130,7 +130,7 @@ struct ExternalIterator {
 
 #[cfg(feature = "iterator")]
 impl Iterator for ExternalIterator {
-    type Item = Pair;
+    type Item = Record;
 
     fn next(&mut self) -> Option<Self::Item> {
         let next_result = unsafe { db_next(self.iterator_id) };

packages/std/src/iterator.rs

@@ -1,8 +1,14 @@
 use crate::errors::StdError;
 use std::convert::TryFrom;
 
-/// A Key-Value pair, returned from our iterators
-pub type Pair<V = Vec<u8>> = (Vec<u8>, V);
+/// A record of a key-value storage that is created through an iterator API.
+/// The first element (key) is always raw binary data. The second element
+/// (value) is binary by default but can be changed to a custom type. This
+/// allows contracts to reuse the type when deserializing database records.
+pub type Record<V = Vec<u8>> = (Vec<u8>, V);
+
+#[deprecated(note = "Renamed to Record, please use this instead")]
+pub type Pair<V = Vec<u8>> = Record<V>;
 
 #[derive(Copy, Clone)]
 // We assign these to integers to provide a stable API for passing over FFI (to wasm and Go)

packages/std/src/lib.rs

@@ -38,7 +38,10 @@ pub use crate::ibc::{
     IbcPacketReceiveMsg, IbcPacketTimeoutMsg, IbcReceiveResponse, IbcTimeout, IbcTimeoutBlock,
 };
 #[cfg(feature = "iterator")]
-pub use crate::iterator::{Order, Pair};
+#[allow(deprecated)]
+pub use crate::iterator::Pair;
+#[cfg(feature = "iterator")]
+pub use crate::iterator::{Order, Record};
 pub use crate::math::{
     Decimal, Decimal256, Decimal256RangeExceeded, DecimalRangeExceeded, Fraction, Uint128, Uint256,
     Uint512, Uint64,

packages/std/src/storage.rs

@@ -6,7 +6,7 @@ use std::iter;
 use std::ops::{Bound, RangeBounds};
 
 #[cfg(feature = "iterator")]
-use crate::iterator::{Order, Pair};
+use crate::iterator::{Order, Record};
 use crate::traits::Storage;
 
 #[derive(Default)]
@@ -45,7 +45,7 @@ impl Storage for MemoryStorage {
         start: Option<&[u8]>,
         end: Option<&[u8]>,
         order: Order,
-    ) -> Box<dyn Iterator<Item = Pair> + 'a> {
+    ) -> Box<dyn Iterator<Item = Record> + 'a> {
         let bounds = range_bounds(start, end);
 
         // BTreeMap.range panics if range is start > end.
@@ -96,12 +96,12 @@ fn range_bounds(start: Option<&[u8]>, end: Option<&[u8]>) -> impl RangeBounds<Ve
 }
 
 #[cfg(feature = "iterator")]
-/// The BTreeMap specific key-value pair reference type, as returned by BTreeMap<Vec<u8>, T>::range.
+/// The BTreeMap specific key-value pair reference type, as returned by BTreeMap<Vec<u8>, Vec<u8>>::range.
 /// This is internal as it can change any time if the map implementation is swapped out.
-type BTreeMapPairRef<'a, T = Vec<u8>> = (&'a Vec<u8>, &'a T);
+type BTreeMapRecordRef<'a> = (&'a Vec<u8>, &'a Vec<u8>);
 
 #[cfg(feature = "iterator")]
-fn clone_item<T: Clone>(item_ref: BTreeMapPairRef<T>) -> Pair<T> {
+fn clone_item(item_ref: BTreeMapRecordRef) -> Record {
     let (key, value) = item_ref;
     (key.clone(), value.clone())
 }
@@ -160,7 +160,7 @@ mod tests {
         // unbounded
         {
             let iter = store.range(None, None, Order::Ascending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(
                 elements,
                 vec![
@@ -174,7 +174,7 @@ mod tests {
         // unbounded (descending)
         {
             let iter = store.range(None, None, Order::Descending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(
                 elements,
                 vec![
@@ -188,14 +188,14 @@ mod tests {
         // bounded
         {
             let iter = store.range(Some(b"f"), Some(b"n"), Order::Ascending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(elements, vec![(b"foo".to_vec(), b"bar".to_vec())]);
         }
 
         // bounded (descending)
         {
             let iter = store.range(Some(b"air"), Some(b"loop"), Order::Descending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(
                 elements,
                 vec![
@@ -208,35 +208,35 @@ mod tests {
         // bounded empty [a, a)
         {
             let iter = store.range(Some(b"foo"), Some(b"foo"), Order::Ascending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(elements, vec![]);
         }
 
         // bounded empty [a, a) (descending)
         {
             let iter = store.range(Some(b"foo"), Some(b"foo"), Order::Descending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(elements, vec![]);
         }
 
         // bounded empty [a, b) with b < a
         {
             let iter = store.range(Some(b"z"), Some(b"a"), Order::Ascending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(elements, vec![]);
         }
 
         // bounded empty [a, b) with b < a (descending)
         {
             let iter = store.range(Some(b"z"), Some(b"a"), Order::Descending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(elements, vec![]);
         }
 
         // right unbounded
         {
             let iter = store.range(Some(b"f"), None, Order::Ascending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(
                 elements,
                 vec![
@@ -249,7 +249,7 @@ mod tests {
         // right unbounded (descending)
         {
             let iter = store.range(Some(b"f"), None, Order::Descending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(
                 elements,
                 vec![
@@ -262,14 +262,14 @@ mod tests {
         // left unbounded
         {
             let iter = store.range(None, Some(b"f"), Order::Ascending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(elements, vec![(b"ant".to_vec(), b"hill".to_vec()),]);
         }
 
         // left unbounded (descending)
         {
             let iter = store.range(None, Some(b"no"), Order::Descending);
-            let elements: Vec<Pair> = iter.collect();
+            let elements: Vec<Record> = iter.collect();
             assert_eq!(
                 elements,
                 vec![

packages/std/src/traits.rs

@@ -7,7 +7,7 @@ use crate::binary::Binary;
 use crate::coins::Coin;
 use crate::errors::{RecoverPubkeyError, StdError, StdResult, VerificationError};
 #[cfg(feature = "iterator")]
-use crate::iterator::{Order, Pair};
+use crate::iterator::{Order, Record};
 use crate::query::{
     AllBalanceResponse, BalanceResponse, BankQuery, CustomQuery, QueryRequest, WasmQuery,
 };
@@ -40,7 +40,7 @@ pub trait Storage {
         start: Option<&[u8]>,
         end: Option<&[u8]>,
         order: Order,
-    ) -> Box<dyn Iterator<Item = Pair> + 'a>;
+    ) -> Box<dyn Iterator<Item = Record> + 'a>;
 
     fn set(&mut self, key: &[u8], value: &[u8]);
     /// Removes a database entry at `key`.

packages/storage/src/bucket.rs

@@ -3,7 +3,7 @@ use std::marker::PhantomData;
 
 use cosmwasm_std::{to_vec, StdError, StdResult, Storage};
 #[cfg(feature = "iterator")]
-use cosmwasm_std::{Order, Pair};
+use cosmwasm_std::{Order, Record};
 
 use crate::length_prefixed::{to_length_prefixed, to_length_prefixed_nested};
 #[cfg(feature = "iterator")]
@@ -88,7 +88,7 @@ where
         start: Option<&[u8]>,
         end: Option<&[u8]>,
         order: Order,
-    ) -> Box<dyn Iterator<Item = StdResult<Pair<T>>> + 'b> {
+    ) -> Box<dyn Iterator<Item = StdResult<Record<T>>> + 'b> {
         let mapped = range_with_prefix(self.storage, &self.prefix, start, end, order)
             .map(deserialize_kv::<T>);
         Box::new(mapped)
@@ -159,7 +159,7 @@ where
         start: Option<&[u8]>,
         end: Option<&[u8]>,
         order: Order,
-    ) -> Box<dyn Iterator<Item = StdResult<Pair<T>>> + 'b> {
+    ) -> Box<dyn Iterator<Item = StdResult<Record<T>>> + 'b> {
         let mapped = range_with_prefix(self.storage, &self.prefix, start, end, order)
             .map(deserialize_kv::<T>);
         Box::new(mapped)
@@ -441,7 +441,7 @@ mod tests {
         bucket.save(b"maria", &maria).unwrap();
         bucket.save(b"jose", &jose).unwrap();
 
-        let res_data: StdResult<Vec<Pair<Data>>> =
+        let res_data: StdResult<Vec<Record<Data>>> =
             bucket.range(None, None, Order::Ascending).collect();
         let data = res_data.unwrap();
         assert_eq!(data.len(), 2);
@@ -450,7 +450,7 @@ mod tests {
 
         // also works for readonly
         let read_bucket = bucket_read::<Data>(&store, b"data");
-        let res_data: StdResult<Vec<Pair<Data>>> =
+        let res_data: StdResult<Vec<Record<Data>>> =
             read_bucket.range(None, None, Order::Ascending).collect();
         let data = res_data.unwrap();
         assert_eq!(data.len(), 2);

packages/storage/src/namespace_helpers.rs

@@ -1,6 +1,6 @@
 use cosmwasm_std::Storage;
 #[cfg(feature = "iterator")]
-use cosmwasm_std::{Order, Pair};
+use cosmwasm_std::{Order, Record};
 
 pub(crate) fn get_with_prefix(
     storage: &dyn Storage,
@@ -37,7 +37,7 @@ pub(crate) fn range_with_prefix<'a>(
     start: Option<&[u8]>,
     end: Option<&[u8]>,
     order: Order,
-) -> Box<dyn Iterator<Item = Pair> + 'a> {
+) -> Box<dyn Iterator<Item = Record> + 'a> {
     // prepare start, end with prefix
     let start = match start {
         Some(s) => concat(namespace, s),
@@ -153,7 +153,7 @@ mod tests {
 
         // ensure we get proper result from prefixed_range iterator
         let iter = range_with_prefix(&storage, &prefix, None, None, Order::Descending);
-        let elements: Vec<Pair> = iter.collect();
+        let elements: Vec<Record> = iter.collect();
         assert_eq!(
             elements,
             vec![
@@ -179,7 +179,7 @@ mod tests {
         set_with_prefix(&mut storage, &other_prefix, b"moon", b"buggy");
 
         // make sure start and end are applied properly
-        let res: Vec<Pair> =
+        let res: Vec<Record> =
             range_with_prefix(&storage, &prefix, Some(b"b"), Some(b"c"), Order::Ascending)
                 .collect();
         assert_eq!(res.len(), 1);
@@ -196,7 +196,7 @@ mod tests {
         .count();
         assert_eq!(res_count, 0);
 
-        let res: Vec<Pair> =
+        let res: Vec<Record> =
             range_with_prefix(&storage, &prefix, Some(b"ant"), None, Order::Ascending).collect();
         assert_eq!(res.len(), 2);
         assert_eq!(res[0], (b"bar".to_vec(), b"none".to_vec()));

packages/storage/src/prefixed_storage.rs

@@ -1,6 +1,6 @@
 use cosmwasm_std::Storage;
 #[cfg(feature = "iterator")]
-use cosmwasm_std::{Order, Pair};
+use cosmwasm_std::{Order, Record};
 
 use crate::length_prefixed::{to_length_prefixed, to_length_prefixed_nested};
 #[cfg(feature = "iterator")]
@@ -64,7 +64,7 @@ impl<'a> Storage for PrefixedStorage<'a> {
         start: Option<&[u8]>,
         end: Option<&[u8]>,
         order: Order,
-    ) -> Box<dyn Iterator<Item = Pair> + 'b> {
+    ) -> Box<dyn Iterator<Item = Record> + 'b> {
         range_with_prefix(self.storage, &self.prefix, start, end, order)
     }
 }
@@ -112,7 +112,7 @@ impl<'a> Storage for ReadonlyPrefixedStorage<'a> {
         start: Option<&[u8]>,
         end: Option<&[u8]>,
         order: Order,
-    ) -> Box<dyn Iterator<Item = Pair> + 'b> {
+    ) -> Box<dyn Iterator<Item = Record> + 'b> {
         range_with_prefix(self.storage, &self.prefix, start, end, order)
     }
 }

packages/storage/src/type_helpers.rs

@@ -2,7 +2,7 @@ use serde::de::DeserializeOwned;
 use std::any::type_name;
 
 #[cfg(feature = "iterator")]
-use cosmwasm_std::Pair;
+use cosmwasm_std::Record;
 use cosmwasm_std::{from_slice, StdError, StdResult};
 
 /// may_deserialize parses json bytes from storage (Option), returning Ok(None) if no data present
@@ -27,7 +27,7 @@ pub(crate) fn must_deserialize<T: DeserializeOwned>(value: &Option<Vec<u8>>) ->
 }
 
 #[cfg(feature = "iterator")]
-pub(crate) fn deserialize_kv<T: DeserializeOwned>(kv: Pair<Vec<u8>>) -> StdResult<Pair<T>> {
+pub(crate) fn deserialize_kv<T: DeserializeOwned>(kv: Record<Vec<u8>>) -> StdResult<Record<T>> {
     let (k, v) = kv;
     let t = from_slice::<T>(&v)?;
     Ok((k, t))