DOCS: Move String literal and inline array FAQ items #5437

ChrisChinchilla · 2018-11-15T11:01:25Z

Description

This PR moves String literal and inline array FAQ items, breaking apart https://github.com/ethereum/solidity/pull/4499/files

Checklist

Code compiles correctly
All tests are passing
New tests have been created which fail without the change (if possible)
README / documentation was extended, if necessary
Changelog entry (if change is visible to the user)
Used meaningful commit messages

docs/types.rst

codecov · 2018-11-23T16:20:18Z

Codecov Report

Merging #5437 into develop will increase coverage by 0.07%.
The diff coverage is n/a.

@@             Coverage Diff             @@
##           develop    #5437      +/-   ##
===========================================
+ Coverage    88.12%   88.19%   +0.07%     
===========================================
  Files          321      314       -7     
  Lines        31712    31419     -293     
  Branches      3809     3770      -39     
===========================================
- Hits         27945    27710     -235     
+ Misses        2481     2444      -37     
+ Partials      1286     1265      -21

Flag	Coverage Δ
#all	`88.19% <ø> (+0.07%)`	⬆️
#syntax	`29.05% <ø> (+0.08%)`	⬆️

docs/types.rst

ChrisChinchilla · 2018-11-26T09:50:59Z

Rebased and squashed

chriseth · 2018-11-26T11:31:15Z

docs/types.rst


 String literals are written with either double or single-quotes (``"foo"`` or ``'bar'``).  They do not imply trailing zeroes as in C; ``"foo"`` represents three bytes, not four.  As with integer literals, their type can vary, but they are implicitly convertible to ``bytes1``, ..., ``bytes32``, if they fit, to ``bytes`` and to ``string``.

+For example, with ``"stringliteral"`` the string literal is interpreted in its raw byte form and with certain tools, if you inspect it, you see a 32-byte hex value, which is the ``"stringliteral"`` in hex.


I think the section is better without this paragraph.

chriseth · 2018-11-26T11:31:44Z

docs/types.rst


 String literals are written with either double or single-quotes (``"foo"`` or ``'bar'``).  They do not imply trailing zeroes as in C; ``"foo"`` represents three bytes, not four.  As with integer literals, their type can vary, but they are implicitly convertible to ``bytes1``, ..., ``bytes32``, if they fit, to ``bytes`` and to ``string``.

+For example, with ``"stringliteral"`` the string literal is interpreted in its raw byte form and with certain tools, if you inspect it, you see a 32-byte hex value, which is the ``"stringliteral"`` in hex.
+
+A string literal becomes a ``string`` type when you assign it to a variable, for example::


Isn't the comment above ("can be converted") the same as here? Also note that in its current form, it is incorrect, because it says string here and bytes32 below.

They are slightly different in explanation, but now the above is deleted anyway (https://github.com/ethereum/solidity/pull/5437/files#r236217406) I think the duplication is gone.

This is still incorrect.

Ah, first I realised that the FAQ point matching this hadn't been removed in this new PR, and rereading that I clarified this text to make sense. But it may be now that the addition isn't so valuable.

chriseth · 2018-11-26T11:32:17Z

docs/types.rst

@@ -902,6 +908,23 @@ possible:
 It is planned to remove this restriction in the future but currently creates
 some complications because of how arrays are passed in the ABI.

+.. index:: !inline;arrays
+
+Inline Arrays


Inline arrays and array literals are two words for the same thing.

chriseth · 2018-11-26T11:32:50Z

docs/types.rst

+Inline Arrays
+^^^^^^^^^^^^^
+
+You can initialise a statically sized memory array inline using syntax such as ``string[] memory myarray = new string[](4);``. For example::


I would not complicate it my introducing the term "inline initializing" - it is just an assignment to a variable.

chriseth

I don't think these FAQ items provide any substantial value and would propose to just delete them.

ChrisChinchilla · 2018-11-26T13:39:25Z

Hmm @chriseth while the FAQ items maybe didn't add much, through this discussion we've ended clarifying a couple of different things.

Have a look at the latest changes that attempt to combine and consolidate the points more, and maybe the PR has grown slightly in scope, but it started with trying to merge the content from the PR.

chriseth · 2018-11-26T14:24:35Z

docs/types.rst


-Array literals are arrays that are written as an expression and are not
+Array literals (or inline arrays) are arrays that are written as an expression and are not


Perhaps more explicit "also called"?

chriseth · 2018-11-26T15:21:42Z

docs/types.rst

 assigned to a variable right away.

+You create a statically sized memory array literal using syntax such as
+``string[] memory myarray = new string[](4);``.


There is no array literal in this example.

The example below is correct, only this one does not fit this section.

This came from the FAQ point, I think the inline example is enough anyway, so let's just remove the longer example.

This example here is wrong. The one you removed is correct, and I think it is a good example.

I think something got lost in Git history, I think this is the example you mean, i.e. the one that's in current docs?

Do you think it's still worth adding something to show people how to initialise inline? I know it's quite simple syntax, but just for completeness. And that was one of the points made in the removed FAQ point.

chriseth · 2018-11-26T15:22:01Z

docs/types.rst

+     }
+  }
+
+You create multi-dimensional arrays in the same way, but filling arrays can


I would remove this paragraph.

chriseth · 2018-11-26T15:22:34Z

docs/types.rst

+
+The type of an array literal is a memory array of fixed size whose base
+type is the common type of the given elements. For example, the type of ``[1, 2, 3]`` is
+``uint8[3] memory``, because the type of each of these constants is ``uint8``. Because of this, it is necessary to convert the first element to ``uint``.


Perhaps replace one of the becauses by a different word.

chriseth · 2018-11-29T13:03:21Z

docs/types.rst

+
+  pragma solidity >=0.4.16 <0.6.0;
+
+  contract C {


This is the correct example, but it's the same as the one some lines further down...

OK, I wanted to have a syntax example, even if it's really basic, and somewhat unrealistic. Hopefully this is OK.

chriseth · 2018-11-29T13:03:39Z

docs/types.rst

+The type of an array literal is a memory array of fixed size whose base
+type is the common type of the given elements. For example, the type of ``[1, 2, 3]`` is
+``uint8[3] memory``, because the type of each of these constants is ``uint8``,
+it is necessary to convert the first element to ``uint``.


It is ONLY necessary to convert it if you want the result to be a uint[3] memory.

Updated, hopefully I understood you correctly.

chriseth · 2018-11-30T15:38:05Z

docs/types.rst

-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  contract C {
+    function f() public pure {
+      uint[] memory a;


This is not an inline array. It is a declaration of a variable of array type. If you want to have a very simple example that is different from the one below, it might be better to just use a snippet and not a full contract. Something like [1, x, y].

@chriseth OK, I must admit, I found the opening paragraph super confusing, and it was leading to my confusion and continual wrong examples. Unless I have completely miss-understood something (and I read some other language docs to clarify), I changed that opening paragraph (paraphrased from the JS MDN docs), and then the example.

Hopefully that clears up my confusion, and maybe the confusion of others.

chriseth · 2018-12-03T09:47:41Z

docs/types.rst

-      uint[] memory a;
-    }     
-  }
+An array literal is a list of zero or more array elements, enclosed in square


I don't think zero elements are possible. At least the compiler would not be able to assign a type to it.

Apart from that, it sounds really good :)

chriseth · 2018-12-03T10:15:12Z

docs/types.rst

-Array Literals / Inline Arrays
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+An array literal is a comma-separated list of one or more expressions, enclosed in square
+brackets (``[...]``). For example ``[1, a, f(3)]``. The elements must have a


all expressions always have a type.

I assume #5437 (comment) replaces this?

chriseth · 2018-12-03T10:16:11Z

docs/types.rst

-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+An array literal is a comma-separated list of one or more expressions, enclosed in square
+brackets (``[...]``). For example ``[1, a, f(3)]``. The elements must have a
+type so they can all be implicitly converted to and this is the elementary type of the array.


Suggestion: There must be a common type all elements can be implicitly converted to. This is the elementary type of the array.

chriseth · 2018-12-03T10:16:32Z

docs/types.rst

-Array literals are arrays that are written as an expression and are not
-assigned to a variable right away.
+In the example below, the type of ``[1, 2, 3]`` is
+``uint8[3] memory``. Because the type of each of these constants is ``uint8``, if you want the result to be a ``uint[3] memory`` type, you need to convert the first element to ``uint``.


Can you start a sentence with because?

You can in certain cases, and this one is OK :)

chriseth · 2018-12-03T10:49:11Z

Squashing.

Fix tab Update docs/types.rst Co-Authored-By: ChrisChinchilla <chriswhward@gmail.com> Update docs/types.rst Co-Authored-By: ChrisChinchilla <chriswhward@gmail.com>

ChrisChinchilla requested a review from chriseth November 15, 2018 11:01

axic added the documentation 📖 label Nov 22, 2018

erak reviewed Nov 23, 2018

View reviewed changes

docs/types.rst Outdated Show resolved Hide resolved

erak reviewed Nov 23, 2018

View reviewed changes

docs/types.rst Outdated Show resolved Hide resolved

erak requested changes Nov 23, 2018

View reviewed changes

docs/types.rst Outdated Show resolved Hide resolved

docs/types.rst Outdated Show resolved Hide resolved

docs/types.rst Outdated Show resolved Hide resolved

ChrisChinchilla force-pushed the docs-faq-types-inline-array branch from 394e379 to 6eae939 Compare November 26, 2018 09:50

chriseth reviewed Nov 26, 2018

View reviewed changes

chriseth suggested changes Nov 26, 2018

View reviewed changes

chriseth reviewed Nov 26, 2018

View reviewed changes

chriseth reviewed Nov 29, 2018

View reviewed changes

chriseth reviewed Nov 30, 2018

View reviewed changes

chriseth reviewed Dec 3, 2018

View reviewed changes

chriseth force-pushed the docs-faq-types-inline-array branch from d89b48b to ba58719 Compare December 3, 2018 09:51

chriseth reviewed Dec 3, 2018

View reviewed changes

Move String literal and inline array FAQ items

78ca280

Fix tab Update docs/types.rst Co-Authored-By: ChrisChinchilla <chriswhward@gmail.com> Update docs/types.rst Co-Authored-By: ChrisChinchilla <chriswhward@gmail.com>

chriseth force-pushed the docs-faq-types-inline-array branch from 4d4f4b6 to 78ca280 Compare December 3, 2018 10:49

chriseth approved these changes Dec 3, 2018

View reviewed changes

chriseth merged commit 04d9466 into develop Dec 3, 2018

axic deleted the docs-faq-types-inline-array branch January 22, 2019 02:55


		String literals are written with either double or single-quotes (``"foo"`` or ``'bar'``). They do not imply trailing zeroes as in C; ``"foo"`` represents three bytes, not four. As with integer literals, their type can vary, but they are implicitly convertible to ``bytes1``, ..., ``bytes32``, if they fit, to ``bytes`` and to ``string``.

		For example, with ``"stringliteral"`` the string literal is interpreted in its raw byte form and with certain tools, if you inspect it, you see a 32-byte hex value, which is the ``"stringliteral"`` in hex.


		Array literals are arrays that are written as an expression and are not
		Array literals (or inline arrays) are arrays that are written as an expression and are not

DOCS: Move String literal and inline array FAQ items #5437

DOCS: Move String literal and inline array FAQ items #5437

Uh oh!

Conversation

ChrisChinchilla commented Nov 15, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Nov 23, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ChrisChinchilla commented Nov 26, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chriseth left a comment

Choose a reason for hiding this comment

Uh oh!

ChrisChinchilla commented Nov 26, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

ChrisChinchilla commented Nov 15, 2018 •

edited

Loading

codecov bot commented Nov 23, 2018 •

edited

Loading