Documenting bytes.concat.

Co-authored-by: chriseth <chris@ethereum.org>

Changelog.md

@@ -1,7 +1,7 @@
 ### 0.8.4 (unreleased)
 
 Language Features:
-
+ * Possibility to use ``bytes.concat`` with variable number of ``bytes`` and ``bytesNN`` arguments which behaves as a restricted version of `abi.encodePacked` with a more descriptive name.
 
 Compiler Features:
 

docs/cheatsheet.rst

@@ -82,6 +82,8 @@ Global Variables
   the given arguments starting from the second and prepends the given four-byte selector
 - ``abi.encodeWithSignature(string memory signature, ...) returns (bytes memory)``: Equivalent
   to ``abi.encodeWithSelector(bytes4(keccak256(bytes(signature)), ...)```
+- ``bytes.concat(...) returns (bytes memory)``: :ref:`Concatenates variable number of
+  arguments to one byte array<bytes-concat>`
 - ``block.chainid`` (``uint``): current chain id
 - ``block.coinbase`` (``address payable``): current block miner's address
 - ``block.difficulty`` (``uint``): current block difficulty

docs/types/reference-types.rst

@@ -146,7 +146,7 @@ length or index access.
 Solidity does not have string manipulation functions, but there are
 third-party string libraries. You can also compare two strings by their keccak256-hash using
 ``keccak256(abi.encodePacked(s1)) == keccak256(abi.encodePacked(s2))`` and
-concatenate two strings using ``abi.encodePacked(s1, s2)``.
+concatenate two strings using ``bytes.concat(bytes(s1), bytes(s2))``.
 
 You should use ``bytes`` over ``byte[]`` because it is cheaper,
 since ``byte[]`` adds 31 padding bytes between the elements. As a general rule,
@@ -160,6 +160,32 @@ always use one of the value types ``bytes1`` to ``bytes32`` because they are muc
     that you are accessing the low-level bytes of the UTF-8 representation,
     and not the individual characters.
 
+.. index:: ! bytes-concat
+
+.. _bytes-concat:
+
+``bytes.concat`` function
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can concatenate a variable number of ``bytes`` or ``bytes1 ... bytes32`` using ``bytes.concat``.
+The function returns a single ``bytes memory`` array that contains the contents of the arguments without padding.
+If you want to use string parameters or other types, you need to convert them to ``bytes`` or ``bytes1``/.../``bytes32`` first.
+
+::
+
+    // SPDX-License-Identifier: GPL-3.0
+    pragma solidity >0.8.3;
+
+    contract C {
+        bytes s = "Storage";
+        function f(bytes calldata c, string memory m, bytes16 b) public view {
+            bytes memory a = bytes.concat(s, c, c[:2], "Literal", bytes(m), b);
+            assert((s.length + c.length + 2 + 7 + bytes(m).length + 16) == a.length);
+        }
+    }
+
+If you call ``bytes.concat`` without arguments it will return an empty ``bytes`` array.
+
 .. index:: ! array;allocating, new
 
 Allocating Memory Arrays
@@ -582,4 +608,4 @@ assigning it to a local variable, as in
 .. note::
     Until Solidity 0.7.0, memory-structs containing members of storage-only types (e.g. mappings)
     were allowed and assignments like ``campaigns[campaignID] = Campaign(beneficiary, goal, 0, 0)``
-    in the example above would work and just silently skip those members.
+    in the example above would work and just silently skip those members.

docs/units-and-global-variables.rst

@@ -136,6 +136,13 @@ ABI Encoding and Decoding Functions
 See the documentation about the :ref:`ABI <ABI>` and the
 :ref:`tightly packed encoding <abi_packed_mode>` for details about the encoding.
 
+.. index:: bytes members
+
+Members of bytes
+----------------
+
+- ``bytes.concat(...) returns (bytes memory)``: :ref:`Concatenates variable number of bytes and bytes1, ..., bytes32 arguments to one byte array<bytes-concat>`
+
 .. index:: assert, revert, require
 
 Error Handling