From d76b55a9c6a4b84fb3ab5150befbddb1afcd4b24 Mon Sep 17 00:00:00 2001
From: Nick Treleaven <n@trelsoft.com>
Date: Sun, 11 Oct 2020 19:36:01 +0100
Subject: [PATCH] doc: Improve string section (#6599)

---
 doc/docs.md | 86 +++++++++++++++++++++++++++++++++--------------------
 1 file changed, 54 insertions(+), 32 deletions(-)

diff --git a/doc/docs.md b/doc/docs.md
index b2cf74ed9b..86f50f910a 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -342,46 +342,82 @@ negative values).
 
 ```v
 name := 'Bob'
-println('Hello, $name!')  // `$` is used for string interpolation
 println(name.len)
+println(name[0]) // indexing gives a byte B
+println(name[1..3]) // slicing gives a string 'ob'
 
-bobby := name + 'by' // + is used to concatenate strings
-println(bobby) // "Bobby"
-
-println(bobby[1..3]) // "ob"
-mut s := 'hello '
-s += 'world' // `+=` is used to append to a string
-println(s) // "hello world"
+windows_newline := '\r\n' // escape special characters like in C
+assert windows_newline.len == 2
 ```
 
 In V, a string is a read-only array of bytes. String data is encoded using UTF-8.
-
-String values are immutable. The following code will raise an error:
+String values are immutable. You cannot mutate elements:
 
 ```v
-mut s := 'hello'
-s[0] = `H`
+mut s := 'hello 🌎'
+s[0] = `H` // not allowed
+```
+> error: cannot assign to `s[i]` since V strings are immutable
+
+Note that indexing a string will produce a `byte`, not a `rune`. Indexes correspond
+to bytes in the string, not Unicode code points.
+
+Character literals have type `rune`. To denote them, use `
+
+```v
+rocket := `🚀`
+assert 'aloha!'[0] == `a`
 ```
 
 Both single and double quotes can be used to denote strings. For consistency,
 `vfmt` converts double quotes to single quotes unless the string contains a single quote character.
 
-Interpolation syntax is pretty simple. It also works with fields:
-`'age = $user.age'`. If you need more complex expressions, use `${}`: `'can register = ${user.age > 13}'`.
+For raw strings, prepend `r`. Raw strings are not escaped:
+
+```v
+s := r'hello\nworld'
+println(s) // "hello\nworld"
+```
+
+### String interpolation
+
+Basic interpolation syntax is pretty simple - use `$` before a variable name.
+The variable will be converted to a string and embedded into the literal:
+```v
+name := 'Bob'
+println('Hello, $name!') // Hello, Bob!
+```
+It also works with fields: `'age = $user.age'`.
+If you need more complex expressions, use `${}`: `'can register = ${user.age > 13}'`.
 
 Format specifiers similar to those in C's `printf()` are also supported. `f`, `g`, `x`, etc. are optional
 and specify the output format. The compiler takes care of the storage size, so there is no `hd` or `llu`.
 
 ```v
-println('x = ${x:12.3f}')
-println('${item:-20} ${n:20d}')
+x := 123.4567
+println('x = ${x:4.2f}')
+println('[${x:10}]')       // pad with spaces on the left
+println('[${int(x):-10}]') // pad with spaces on the right
 ```
 
-All operators in V must have values of the same type on both sides. This code will not compile if `age` is not a string (for example if `age` were an `int`):
+### String operators
 
 ```v
-println('age = ' + age)
+bobby := name + 'by' // + is used to concatenate strings
+println(bobby) // "Bobby"
+
+mut s := 'hello '
+s += 'world' // `+=` is used to append to a string
+println(s) // "hello world"
 ```
+All operators in V must have values of the same type on both sides.
+You cannot concatenate an integer to a string:
+
+```v
+age := 10
+println('age = ' + age) // not allowed
+```
+> error: infix expr: cannot use `int` (right expression) as `string`
 
 We have to either convert `age` to a `string`:
 
@@ -395,20 +431,6 @@ or use string interpolation (preferred):
 println('age = $age')
 ```
 
-To denote character literals, use `
-
-```v
-a := `a`
-assert 'aloha!'[0] == `a`
-```
-
-For raw strings, prepend `r`. Raw strings are not escaped:
-
-```v
-s := r'hello\nworld'
-println(s) // "hello\nworld"
-```
-
 ### Numbers
 
 ```v