Merge pull request #8 from sCrypt-Inc/map

add doc for `HashedMap`

docs/contracts.rst

@@ -153,6 +153,75 @@ As an example, contract ``CheckLockTimeVerify`` ensures coins are timelocked and
 More details can be found in this article `OP_PUSH_TX`_.
 To customize ECDSA signing, such as choosing ephemeral key, there is a more general version called ``Tx.checkPreimageAdvanced()``. see `Advanced OP_PUSH_TX`_.
 
+Library ``HashedMap``
+-----------------------
+
+The `HashedMap` library provides a map/hashtable-like data structure.
+Unique keys and their corresponding values are hashed before being stored.
+Most functions of `HashedMap` require not only a key, but also its index, ranked by key hash in ascending order.
+
+**Constructor**
+
+* ``HashedMap(bytes data)``
+  Create an instance of ``HashedMap`` with some initial data.
+
+    .. code-block:: solidity
+
+        HashedMap<bytes, int> map = new HashedMap<bytes, int>(b'');
+        // key and value types can be omitted
+        HashedMap<int, bool> map1 = new HashedMap(b'');
+        // key and value types cannot be omitted since they cannot be inferred
+        auto map2 = new HashedMap<int, int>(b'');
+
+**Instance methods**
+
+* ``set(K key, V val, int keyIndex) : bool``
+  Insert or update a (`key`, `val`) pair with the key index given by `keyIndex`. Returns `true` if successful; otherwise returns `false`.
+
+    .. code-block:: solidity
+
+        require(map.set(b'1234', 1, 0)); // insert
+        require(map.set(b'1234', 2, 0)); // update it
+
+* ``canGet(K key, V val, int keyIndex): bool``
+  Check whether we can get a (`key`, `val`) pair with the key index given by `keyIndex`. Returns `true` if successful; otherwise returns `false`.
+
+    .. code-block:: solidity
+
+        require(map.canGet(b'1234', 2, 0));
+
+* ``has(K key, int keyIndex) : bool``
+  Check whether `key` exists in the map and its index is `keyIndex`. Returns `true` if both conditions are met; otherwise returns `false`.
+
+    .. code-block:: solidity
+
+        require(map.has(b'1234', 0));
+
+* ``delete(K key, int keyIndex) : bool``
+  Delete the entry with given `key` and the key index is `keyIndex`. Returns `true` if successful; otherwise returns `false`.
+
+    .. code-block:: solidity
+
+        require(map.delete(b'1234', 0));
+
+* ``size() : int``
+  Returns the size of map, i.e. the number of the keys it contains.
+
+    .. code-block:: solidity
+
+        int s = map.size();
+
+
+* ``data() : bytes``
+  Returns the internal data representation of the map.
+
+    .. code-block:: solidity
+
+        bytes b = map.data();
+        // this creates a deep copy of the map
+        HashedMap<int, bool> mapCopy = new HashedMap(b);
+
+
 Full List
 ---------
 
@@ -180,6 +249,15 @@ Full List
       - None
       - checkPreimage(bytes sighashPreimage)
 
+    * - HashedMap<K, V>
+      - bytes data
+      - set(K key, V val, int keyIndex)
+        canGet(K key, V val, int keyIndex)
+        delete(K key, int keyIndex)
+        has(K key, int keyIndex)
+        size()
+        data()
+
 .. [#] ``X`` is hashing function and can be Ripemd160/Sha1/Sha256/Hash160
 .. [#] ``Y`` is hashing function return type and can be Ripemd160/Sha1/Sha256/Ripemd160