Merge pull request #9 from sCrypt-Inc/set

add doc for generic types & HashedSet

docs/contracts.rst

@@ -204,6 +204,13 @@ Most functions of `HashedMap` require not only a key, but also its index, ranked
 
         require(map.delete(b'1234', 0));
 
+* ``clear() : bool``
+  Delete all entries of the map.
+
+    .. code-block:: solidity
+
+        map.clear();
+
 * ``size() : int``
   Returns the size of map, i.e. the number of the keys it contains.
 
@@ -221,6 +228,76 @@ Most functions of `HashedMap` require not only a key, but also its index, ranked
         // this creates a deep copy of the map
         HashedMap<int, bool> mapCopy = new HashedMap(b);
 
+Library ``HashedSet``
+-----------------------
+
+The `HashedSet` library provides a set-like data structure.
+It can be regarded as a special `HashedMap` where a value is the same with its key and is thus omitted.
+Unique values are hashed before being stored.
+Most functions of `HashedSet` require an index, ranked by the value's sha256 hash in ascending order.
+
+**Constructor**
+
+* ``HashedSet(bytes data)``
+  Create an instance of ``HashedSet`` with some initial data.
+
+    .. code-block:: solidity
+        struct ST {
+          int x;
+          bool y;
+        }
+
+        HashedSet<ST> set = new HashedSet<ST>(b'');
+        // key and value types can be omitted
+        HashedSet<ST> set1 = new HashedSet(b'');
+        // key and value types cannot be omitted since they cannot be inferred
+        auto set2 = new HashedSet<ST>(b'');
+
+**Instance methods**
+
+* ``add(E entry, int index) : bool``
+  Add `entry` to set with the key index given by `index`. Returns `true` if successful; otherwise returns `false`.
+
+    .. code-block:: solidity
+
+        require(set.add(b'1234', 0));
+
+* ``has(E entry, int index) : bool``
+  Check whether `entry` exists in the set and its index is `index`. Returns `true` if both conditions are met; otherwise returns `false`.
+
+    .. code-block:: solidity
+
+        require(set.has(b'1234', 0));
+
+* ``delete(E entry, int index) : bool``
+  Delete the entry with given `entry` and the index is `index`. Returns `true` if successful; otherwise returns `false`.
+
+    .. code-block:: solidity
+
+        require(set.delete(b'1234', 0));
+
+* ``clear() : bool``
+  Delete all entries of the set.
+
+    .. code-block:: solidity
+
+        set.clear();
+
+* ``size() : int``
+  Returns the size of set, i.e. the number of the entries it contains.
+
+    .. code-block:: solidity
+
+        int s = set.size();
+
+* ``data() : bytes``
+  Returns the internal data representation of the set.
+
+    .. code-block:: solidity
+
+        bytes b = set.data();
+        // this creates a deep copy of the set
+        HashedSet<ST> setCopy = new HashedSet(b);
 
 Full List
 ---------
@@ -251,12 +328,22 @@ Full List
 
     * - 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()
+      - | set(K key, V val, int keyIndex)
+        | canGet(K key, V val, int keyIndex)
+        | delete(K key, int keyIndex)
+        | has(K key, int keyIndex)
+        | clear()
+        | size()
+        | data()
+
+    * - HashedSet<V>
+      - bytes data
+      - | add(V val, int index)
+        | delete(V val, int index)
+        | has(V val, int index)
+        | clear()
+        | 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

docs/functions.rst

@@ -123,6 +123,12 @@ Hashing
 
   sha256(sha256(b))
 
+* ``Sha256 flattenSha256(T a)``
+
+  Returns Sha256 for the given argument a of any type.
+  If ``T`` is a basic type, like ``bool / int / bytes``, the return is the same as ``sha256(a)``.
+  If ``T`` is a composite type (i.e., array and struct), it concatenates all the sha256 values for each flattened fields of a to form a joint bytes, and then call ``sha256`` on it to get the final result.
+
 Signature Verification
 ----------------------
 * ``bool checkSig(Sig sig, PubKey pk)``

docs/syntax.rst

@@ -168,6 +168,35 @@ Type aliases create a new name for a type. It does not actually create a new typ
         type Age = int;
         type Coordinate = int[2];
 
+Generics/Generic Types
+----------------------
+A generic type is a parameterized type. It allows a library to work over a variety of types rather than a single one.
+Users can consume these libraries and use their own concrete types.
+
+* **Declare Generic Types**
+
+Generic types can only be declared at library level and used within the library's scope. 
+
+    .. code-block:: solidity
+
+        // declare two generic type variables: K & V
+        library HashedMap<K, V> {
+
+          // use them as function parameters' type
+          function set(K k, V v, int idx) { 
+            ...
+          }
+
+        }
+
+* **Instantiate Generic Types**
+
+    .. code-block:: solidity
+
+        HashedMap<bytes, int> map = new HashedMap();
+        map.set(b'01', 1, 0);
+        map.set(2, 1, 1); // this will throw semantic error for the first argument's type `int`, which expects `bytes` 
+
 Domain Subtypes
 ===============
 There are several subtypes, specific to the Bitcoin context, used to further improve type safety.