From 9a8882c9fc2e296d32be31ff9754cb554133ffc6 Mon Sep 17 00:00:00 2001 From: Chris Ward Date: Wed, 16 Jan 2019 15:43:47 +0200 Subject: [PATCH] Move string manipulation FAQ items to type docs Update docs/types/value-types.rst Co-Authored-By: ChrisChinchilla Update docs/types/value-types.rst Co-Authored-By: ChrisChinchilla Fixed formatting Re-add example Clarify text Rearrange string manipulation --- docs/control-structures.rst | 8 +++--- docs/frequently-asked-questions.rst | 38 ----------------------------- docs/types/reference-types.rst | 14 ++++++++--- docs/types/value-types.rst | 2 +- 4 files changed, 16 insertions(+), 46 deletions(-) diff --git a/docs/control-structures.rst b/docs/control-structures.rst index 46b3a7f1d..45ba190ec 100644 --- a/docs/control-structures.rst +++ b/docs/control-structures.rst @@ -264,13 +264,13 @@ Complications for Arrays and Structs The semantics of assignments are a bit more complicated for non-value types like arrays and structs. Assigning *to* a state variable always creates an independent copy. On the other hand, assigning to a local variable creates an independent copy only for elementary types, i.e. static types that fit into 32 bytes. If structs or arrays (including ``bytes`` and ``string``) are assigned from a state variable to a local variable, the local variable holds a reference to the original state variable. A second assignment to the local variable does not modify the state but only changes the reference. Assignments to members (or elements) of the local variable *do* change the state. -In the example below the call to ``g(x)`` has no effect on ``x`` because it needs -to create an independent copy of the storage value in memory. However ``h(x)`` modifies ``x`` because a reference and -not a copy is passed. +In the example below the call to ``g(x)`` has no effect on ``x`` because it creates +an independent copy of the storage value in memory. However, ``h(x)`` successfully modifies ``x`` +because only a reference and not a copy is passed. :: - pragma solidity >=0.4.16 <0.6.0; + pragma solidity >=0.4.16 <0.6.0; contract C { uint[20] x; diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst index 645789cee..f009d3af5 100644 --- a/docs/frequently-asked-questions.rst +++ b/docs/frequently-asked-questions.rst @@ -16,44 +16,6 @@ Enums are not supported by the ABI, they are just supported by Solidity. You have to do the mapping yourself for now, we might provide some help later. -What are some examples of basic string manipulation (``substring``, ``indexOf``, ``charAt``, etc)? -================================================================================================== - -There are some string utility functions at `stringUtils.sol `_ -which will be extended in the future. In addition, Arachnid has written `solidity-stringutils `_. - -For now, if you want to modify a string (even when you only want to know its length), -you should always convert it to a ``bytes`` first:: - - pragma solidity >=0.4.0 <0.6.0; - - contract C { - string s; - - function append(byte c) public { - bytes(s).push(c); - } - - function set(uint i, byte c) public { - bytes(s)[i] = c; - } - } - - -Can I concatenate two strings? -============================== - -Yes, you can use ``abi.encodePacked``:: - - pragma solidity >=0.4.0 <0.6.0; - - library ConcatHelper { - function concat(bytes memory a, bytes memory b) - internal pure returns (bytes memory) { - return abi.encodePacked(a, b); - } - } - ****************** Advanced Questions ****************** diff --git a/docs/types/reference-types.rst b/docs/types/reference-types.rst index b9fd9194a..99d977f6c 100644 --- a/docs/types/reference-types.rst +++ b/docs/types/reference-types.rst @@ -106,13 +106,24 @@ Array elements can be of any type, including mapping or struct. The general restrictions for types apply, in that mappings can only be stored in the ``storage`` data location and publicly-visible functions need parameters that are :ref:`ABI types `. +It is possible to mark arrays ``public`` and have Solidity create a :ref:`getter `. +The numeric index becomes a required parameter for the getter. + Accessing an array past its end causes a failing assertion. You can use the ``.push()`` method to append a new element at the end or assign to the ``.length`` :ref:`member ` to change the size (see below for caveats). method or increase the ``.length`` :ref:`member ` to add elements. +``bytes`` and ``strings`` as Arrays +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Variables of type ``bytes`` and ``string`` are special arrays. A ``bytes`` is similar to ``byte[]``, but it is packed tightly in calldata and memory. ``string`` is equal to ``bytes`` but does not allow length or index access. +While Solidity does not have string manipulation functions, you can use +this implicit conversion for equivalent functionality. For example to compare +two strings ``keccak256(abi.encode(s1)) == keccak256(abi.encode(s2))``, or to +concatenate two strings already encoded with ``abi.encodePacked(s1, s2);``. + You should use ``bytes`` over ``byte[]`` because it is cheaper, since ``byte[]`` adds 31 padding bytes between the elements. As a general rule, use ``bytes`` for arbitrary-length raw byte data and ``string`` for arbitrary-length string (UTF-8) data. If you can limit the length to a certain number of bytes, @@ -124,9 +135,6 @@ 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. -It is possible to mark arrays ``public`` and have Solidity create a :ref:`getter `. -The numeric index becomes a required parameter for the getter. - .. index:: ! array;allocating, new Allocating Memory Arrays diff --git a/docs/types/value-types.rst b/docs/types/value-types.rst index 09db1423c..a8846eaf0 100644 --- a/docs/types/value-types.rst +++ b/docs/types/value-types.rst @@ -708,4 +708,4 @@ Another example that uses external function types:: } .. note:: - Lambda or inline functions are planned but not yet supported. \ No newline at end of file + Lambda or inline functions are planned but not yet supported.