Skip to content

Commit 8070332

Browse files
briandoyle81briandoyle81
authored
Merge pull request #227 from onflow/brian-doyle/add-string-interpolation-heading
Add 'String Interpolation' to heading and text for string templates f…
2 parents 1dff7c9 + 714aa9e commit 8070332

File tree

1 file changed

+132
-145
lines changed

1 file changed

+132
-145
lines changed

‎docs/language/values-and-types/strings-and-characters.md

Lines changed: 132 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ let thumbsUpText =
3838

3939
The type `Character` represents a single, human-readable character. Characters are extended grapheme clusters, which consist of one or more Unicode scalars.
4040

41-
For example, the single character `ü` can be represented in several ways in Unicode. First, it can be represented by a single Unicode scalar value `ü` ("LATIN SMALL LETTER U WITH DIAERESIS", code point U+00FC). Second, the same single character can be represented by two Unicode scalar values: `u` ("LATIN SMALL LETTER U", code point +0075), and "COMBINING DIAERESIS" (code point U+0308). The combining Unicode scalar value is applied to the scalar before it, which turns a `u` into a `ü`.
41+
For example, the single character `ü` can be represented in several ways in Unicode. First, it can be represented by a single Unicode scalar value `ü` ("LATIN SMALL LETTER U WITH DIAERESIS", code point U+00FC). Second, the same single character can be represented by two Unicode scalar values: `u` ("LATIN SMALL LETTER U", code point U+0075), and "COMBINING DIAERESIS" (code point U+0308). The combining Unicode scalar value is applied to the scalar before it, which turns a `u` into a `ü`.
4242

4343
Still, both variants represent the same human-readable character `ü`:
4444

@@ -61,11 +61,11 @@ let canadianFlag: Character = "\u{1F1E8}\u{1F1E6}"
6161
// `canadianFlag` is `🇨🇦`
6262
```
6363

64-
## String templates
64+
## String templates / String Interpolation
6565

66-
String templates allow constants, variables, and expressions to be inlined into strings simplifying the process of constructing dynamic strings. String templates are currently supported in single-line literals by wrapping the target in parentheses and prefixing it with a backslash (`\`).
66+
String templates, or string interpolation, allow constants, variables, and expressions to be inlined into strings simplifying the process of constructing dynamic strings. String templates are currently supported in single-line literals by wrapping the target in parentheses and prefixing it with a backslash (`\`).
6767

68-
The target in the parentheses must support the built-in function `toString()`, meaning it must evaluate to a `String`, `Number`, `Address`, `Character`, `Bool` or `Path`. Carriage returns, line feeds and nested string literals are not supported inside the parentheses.
68+
The target in the parentheses must support the built-in function `toString()`, meaning it must evaluate to a `String`, `Number`, `Address`, `Character`, `Bool` or `Path`. Carriage returns, line feeds and nested string literals are not supported inside the parentheses.
6969

7070
```cadence
7171
let result = 2 + 2
@@ -83,151 +83,142 @@ let arr: String = "\(x)"
8383

8484
Strings have multiple built-in functions you can use:
8585

86-
-
87-
```cadence
88-
let length: Int
89-
```
86+
- ```cadence
87+
let length: Int
88+
```
9089

91-
Returns the number of characters in the string as an integer.
90+
Returns the number of characters in the string as an integer.
9291

93-
```cadence
94-
let example = "hello"
92+
```cadence
93+
let example = "hello"
9594
96-
// Find the number of elements of the string.
97-
let length = example.length
98-
// `length` is `5`
99-
```
100-
-
101-
```cadence
102-
let utf8: [UInt8]
103-
```
95+
// Find the number of elements of the string.
96+
let length = example.length
97+
// `length` is `5`
98+
```
10499

105-
The byte array of the UTF-8 encoding.
100+
- ```cadence
101+
let utf8: [UInt8]
102+
```
106103

107-
```cadence
108-
let flowers = "Flowers \u{1F490}"
109-
let bytes = flowers.utf8
110-
// `bytes` is `[70, 108, 111, 119, 101, 114, 115, 32, 240, 159, 146, 144]`
111-
```
104+
The byte array of the UTF-8 encoding.
112105

113-
-
114-
```cadence
115-
view fun concat(_ other: String): String
116-
```
106+
```cadence
107+
let flowers = "Flowers \u{1F490}"
108+
let bytes = flowers.utf8
109+
// `bytes` is `[70, 108, 111, 119, 101, 114, 115, 32, 240, 159, 146, 144]`
110+
```
117111

118-
Concatenates the string `other` to the end of the original string, but does not modify the original string. This function creates a new string whose length is the sum of the lengths of the string the function is called on and the string given as a parameter.
112+
- ```cadence
113+
view fun concat(_ other: String): String
114+
```
119115

120-
```cadence
121-
let example = "hello"
122-
let new = "world"
116+
Concatenates the string `other` to the end of the original string, but does not modify the original string. This function creates a new string whose length is the sum of the lengths of the string the function is called on and the string given as a parameter.
123117

124-
// Concatenate the new string onto the example string and return the new string.
125-
let helloWorld = example.concat(new)
126-
// `helloWorld` is now `"helloworld"`
127-
```
118+
```cadence
119+
let example = "hello"
120+
let new = "world"
128121
129-
-
130-
```cadence
131-
view fun slice(from: Int, upTo: Int): String
132-
```
122+
// Concatenate the new string onto the example string and return the new string.
123+
let helloWorld = example.concat(new)
124+
// `helloWorld` is now `"helloworld"`
125+
```
133126

134-
Returns a string slice of the characters in the given string from start index `from` up to, but not including, the end index `upTo`. This function creates a new string whose length is `upTo - from`. It does not modify the original string. If either of the parameters are out of the bounds of the string, or the indices are invalid (`from > upTo`), then the function will fail.
127+
- ```cadence
128+
view fun slice(from: Int, upTo: Int): String
129+
```
135130

136-
```cadence
137-
let example = "helloworld"
131+
Returns a string slice of the characters in the given string from start index `from` up to, but not including, the end index `upTo`. This function creates a new string whose length is `upTo - from`. It does not modify the original string. If either of the parameters are out of the bounds of the string, or the indices are invalid (`from > upTo`), then the function will fail.
138132

139-
// Create a new slice of part of the original string.
140-
let slice = example.slice(from: 3, upTo: 6)
141-
// `slice` is now `"low"`
133+
```cadence
134+
let example = "helloworld"
142135
143-
// Run-time error: Out of bounds index, the program aborts.
144-
let outOfBounds = example.slice(from: 2, upTo: 10)
136+
// Create a new slice of part of the original string.
137+
let slice = example.slice(from: 3, upTo: 6)
138+
// `slice` is now `"low"`
145139
146-
// Run-time error: Invalid indices, the program aborts.
147-
let invalidIndices = example.slice(from: 2, upTo: 1)
148-
```
149-
-
150-
```cadence
151-
view fun decodeHex(): [UInt8]
152-
```
140+
// Run-time error: Out of bounds index, the program aborts.
141+
let outOfBounds = example.slice(from: 2, upTo: 10)
153142
154-
Returns an array containing the bytes represented by the given hexadecimal string.
143+
// Run-time error: Invalid indices, the program aborts.
144+
let invalidIndices = example.slice(from: 2, upTo: 1)
145+
```
155146

156-
The given string must only contain hexadecimal characters and must have an even length.
157-
If the string is malformed, the program aborts.
147+
- ```cadence
148+
view fun decodeHex(): [UInt8]
149+
```
158150

159-
```cadence
160-
let example = "436164656e636521"
151+
Returns an array containing the bytes represented by the given hexadecimal string.
161152

162-
example.decodeHex() // is `[67, 97, 100, 101, 110, 99, 101, 33]`
163-
```
153+
The given string must only contain hexadecimal characters and must have an even length.
154+
If the string is malformed, the program aborts.
164155

165-
-
166-
```cadence
167-
view fun toLower(): String
168-
```
156+
```cadence
157+
let example = "436164656e636521"
169158
170-
Returns a string where all upper case letters are replaced with lowercase characters.
159+
example.decodeHex() // is `[67, 97, 100, 101, 110, 99, 101, 33]`
160+
```
171161

172-
```cadence
173-
let example = "Flowers"
162+
- ```cadence
163+
view fun toLower(): String
164+
```
174165

175-
example.toLower() // is `flowers`
176-
```
166+
Returns a string where all upper case letters are replaced with lowercase characters.
177167

178-
-
179-
```cadence
180-
view fun replaceAll(of: String, with: String): String
181-
```
168+
```cadence
169+
let example = "Flowers"
182170
183-
Returns a string where all occurences of `of` are replaced with `with`. If `of` is empty, it matches at the beginning of the string and after each UTF-8 sequence yielding k+1 replacements for a string of length k.
171+
example.toLower() // is `flowers`
172+
```
184173

185-
```cadence
186-
let example = "abababa"
174+
- ```cadence
175+
view fun replaceAll(of: String, with: String): String
176+
```
187177

188-
example.replaceAll(of: "a", with: "o") // is `obobobo`
189-
```
178+
Returns a string where all occurences of `of` are replaced with `with`. If `of` is empty, it matches at the beginning of the string and after each UTF-8 sequence yielding k+1 replacements for a string of length k.
190179

191-
-
192-
```cadence
193-
view fun split(separator: String): [String]
194-
```
180+
```cadence
181+
let example = "abababa"
195182
196-
Returns the variable-sized array of strings created splitting the receiver string on the `separator`.
183+
example.replaceAll(of: "a", with: "o") // is `obobobo`
184+
```
197185

198-
```cadence
199-
let example = "hello world"
186+
- ```cadence
187+
view fun split(separator: String): [String]
188+
```
200189

201-
example.split(separator: " ") // is `["hello", "world"]`
202-
```
190+
Returns the variable-sized array of strings created splitting the receiver string on the `separator`.
203191

192+
```cadence
193+
let example = "hello world"
194+
195+
example.split(separator: " ") // is `["hello", "world"]`
196+
```
204197

205198
The `String` type also provides the following functions:
206199

207-
-
208-
```cadence
209-
view fun String.encodeHex(_ data: [UInt8]): String
210-
```
200+
- ```cadence
201+
view fun String.encodeHex(_ data: [UInt8]): String
202+
```
211203

212-
Returns a hexadecimal string for the given byte array
204+
Returns a hexadecimal string for the given byte array
213205

214-
```cadence
215-
let data = [1 as UInt8, 2, 3, 0xCA, 0xDE]
206+
```cadence
207+
let data = [1 as UInt8, 2, 3, 0xCA, 0xDE]
216208
217-
String.encodeHex(data) // is `"010203cade"`
218-
```
209+
String.encodeHex(data) // is `"010203cade"`
210+
```
219211

220-
-
221-
```cadence
222-
view fun String.join(_ strings: [String], separator: String): String
223-
```
212+
- ```cadence
213+
view fun String.join(_ strings: [String], separator: String): String
214+
```
224215

225-
Returns the string created by joining the array of `strings` with the provided `separator`.
216+
Returns the string created by joining the array of `strings` with the provided `separator`.
226217

227-
```cadence
228-
let strings = ["hello", "world"]
229-
String.join(strings, " ") // is "hello world"
230-
```
218+
```cadence
219+
let strings = ["hello", "world"]
220+
String.join(strings, separator: " ") // is "hello world"
221+
```
231222

232223
`String`s are also indexable, returning a `Character` value.
233224

@@ -236,60 +227,56 @@ let str = "abc"
236227
let c = str[0] // is the Character "a"
237228
```
238229

239-
-
240-
```cadence
241-
view fun String.fromUTF8(_ input: [UInt8]): String?
242-
```
230+
- ```cadence
231+
view fun String.fromUTF8(_ input: [UInt8]): String?
232+
```
243233

244-
Attempts to convert a UTF-8 encoded byte array into a `String`. This function returns `nil` if the byte array contains invalid UTF-8,
245-
such as incomplete codepoint sequences or undefined graphemes.
234+
Attempts to convert a UTF-8 encoded byte array into a `String`. This function returns `nil` if the byte array contains invalid UTF-8,
235+
such as incomplete codepoint sequences or undefined graphemes.
246236

247-
For a given string `s`, `String.fromUTF8(s.utf8)` is equivalent to wrapping `s` up in an [optional].
237+
For a given string `s`, `String.fromUTF8(s.utf8)` is equivalent to wrapping `s` up in an [optional].
248238

249239
## Character fields and functions
250240

251241
`Character` values can be converted into `String` values using the `toString` function:
252242

253-
-
254-
```cadence
255-
view fun toString(): String`
256-
```
243+
- ```cadence
244+
view fun toString(): String`
245+
```
257246

258-
Returns the string representation of the character.
247+
Returns the string representation of the character.
259248

260-
```cadence
261-
let c: Character = "x"
249+
```cadence
250+
let c: Character = "x"
262251
263-
c.toString() // is "x"
264-
```
252+
c.toString() // is "x"
253+
```
265254

266-
-
267-
```cadence
268-
view fun String.fromCharacters(_ characters: [Character]): String
269-
```
255+
- ```cadence
256+
view fun String.fromCharacters(_ characters: [Character]): String
257+
```
270258

271-
Builds a new `String` value from an array of `Character`s. Because `String`s are immutable, this operation makes a copy of the input array.
259+
Builds a new `String` value from an array of `Character`s. Because `String`s are immutable, this operation makes a copy of the input array.
272260

273-
```cadence
274-
let rawUwU: [Character] = ["U", "w", "U"]
275-
let uwu: String = String.fromCharacters(rawUwU) // "UwU"
276-
```
261+
```cadence
262+
let rawUwU: [Character] = ["U", "w", "U"]
263+
let uwu: String = String.fromCharacters(rawUwU) // "UwU"
264+
```
277265

278-
-
279-
```cadence
280-
let utf8: [UInt8]
281-
```
266+
- ```cadence
267+
let utf8: [UInt8]
268+
```
282269

283-
The byte array of the UTF-8 encoding.
270+
The byte array of the UTF-8 encoding.
284271

285-
```cadence
286-
let a: Character = "a"
287-
let a_bytes = a.utf8 // `a_bytes` is `[97]`
272+
```cadence
273+
let a: Character = "a"
274+
let a_bytes = a.utf8 // `a_bytes` is `[97]`
288275
289-
let bouquet: Character = "\u{1F490}"
290-
let bouquet_bytes = bouquet.utf8 // `bouquet_bytes` is `[240, 159, 146, 144]`
291-
```
276+
let bouquet: Character = "\u{1F490}"
277+
let bouquet_bytes = bouquet.utf8 // `bouquet_bytes` is `[240, 159, 146, 144]`
278+
```
292279

293280
<!-- Relative links. Will not render on the page -->
294281

295-
[optional]: ./anystruct-anyresource-opts-never.md#optionals
282+
[optional]: ./anystruct-anyresource-opts-never.md#optionals

0 commit comments

Comments
 (0)