Documentation refactoring. No code changes. (0.40.5)

web/documentation/strings/strings.md

@@ -0,0 +1,106 @@
+---
+layout: page
+published: true
+noToc: false
+noComments: false
+noDate: false
+title: Fun - Working with strings in Fun
+subtitle: Working with strings, literals/escaping, concatenation, substr/find, split, and conversions.
+description: Working with strings, literals/escaping, concatenation, substr/find, split, and conversions.
+permalink: /documentation/strings/
+lang: en
+tags:
+- concatenation
+- conversions
+- escaping
+- find
+- literals
+- split
+- strings
+- substr
+---
+
+This guide covers string literals, common operations (length, concatenation, substring, search, split), and interop patterns. Strings in Fun are immutable sequences of bytes/text.
+
+## TL;DR
+
+- Create with quotes: s = "hello". Escape with \n, \t, \", \\.
+- Concatenate with +. Convert non-strings with to_string(x).
+- Length: len(s). Substring: substr(s, start, length).
+- Find index: find(s, needle) → 0-based index or -1 if not found.
+- Split CSV: split("a,b,c", ",") → ["a","b","c"].
+
+## Literals and escaping
+
+<pre>s1 = "hello"
+s2 = "line1\nline2"   // newline
+s3 = "quote: \" and backslash: \\" // escaped quote and backslash
+
+print(s1)  // hello</pre>
+
+Notes:
+
+- Strings are immutable; operations return new strings rather than modifying in place.
+- Use to_string(x) when concatenating non-string values.
+
+## Basic operations
+
+Length and concatenation:
+
+<pre>name = "Ada"
+greet = "Hello, " + name + "!"    // "Hello, Ada!"
+print(len(greet))                   // 12</pre>
+
+Substring (start, length) and search:
+
+<pre>s = "hello, world"
+print(substr(s, 7, 5))   // world
+idx = find(s, ",")      // 5, or -1 if not found
+if idx >= 0 { print("comma at index " + to_string(idx)) }</pre>
+
+Splitting into arrays:
+
+<pre>parts = split("a,b,c", ",")  // ["a","b","c"]
+for i = 0; i < len(parts); i = i + 1 {
+  print(parts[i])
+}</pre>
+
+## Conversions and formatting
+
+<pre>n = 42
+pi = 3.14
+msg = "n=" + to_string(n) + ", pi=" + to_string(pi)
+print(msg)
+
+// parsing (may error if the string is not numeric)
+n2 = to_number("123")    // 123</pre>
+
+If you need a specific type, you can use cast for advanced cases, e.g. cast("123", "number").
+
+## Common patterns
+
+- Guard on find results before slicing:
+
+<pre>email = "user@example.org"
+at = find(email, "@")
+if at >= 0 {
+  user = substr(email, 0, at)
+  host = substr(email, at + 1, len(email) - at - 1)
+  print(user + " on " + host)
+}</pre>
+
+- Building paths or messages:
+
+<pre>base = "/tmp"
+file = "log.txt"
+path = base + "/" + file</pre>
+
+## Gotchas
+
+- Strings are immutable: repeated concatenation in big loops can be costly; consider collecting pieces in an array and joining at the end if you have a helper for that in your setup.
+- len(s) counts bytes/code units; be mindful when working with multibyte encodings.
+
+## See also
+
+- Core overview: [../types/](../types/)
+- Arrays guide (useful when splitting/collecting text): [../arrays/](../arrays/)