From fd0762b5eff5d28936c85bd8d57f78e336875a6a Mon Sep 17 00:00:00 2001
From: Djordje Mijovic <djordje.mijovic@gmail.com>
Date: Wed, 17 Mar 2021 13:46:26 +0100
Subject: [PATCH] Documenting bytes.concat.

Co-authored-by: chriseth <chris@ethereum.org>
---
 Changelog.md                        |  2 +-
 docs/cheatsheet.rst                 |  2 ++
 docs/types/reference-types.rst      | 30 +++++++++++++++++++++++++++--
 docs/units-and-global-variables.rst |  7 +++++++
 4 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/Changelog.md b/Changelog.md
index 024d3ddf3..187452bc8 100644
--- a/Changelog.md
+++ b/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:
 
diff --git a/docs/cheatsheet.rst b/docs/cheatsheet.rst
index 22ca5cc8e..10a7ce105 100644
--- a/docs/cheatsheet.rst
+++ b/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
diff --git a/docs/types/reference-types.rst b/docs/types/reference-types.rst
index fe58f07d7..09f4b7c55 100644
--- a/docs/types/reference-types.rst
+++ b/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.
\ No newline at end of file
+    in the example above would work and just silently skip those members.
diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst
index ae6bf014d..afb8b0067 100644
--- a/docs/units-and-global-variables.rst
+++ b/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