Merge pull request #37 from mgomes/string-methods-phase6

Add phase-6 regex, byte helpers, and bang parity

Author: mgomes

docs/strings.md

@@ -12,6 +12,31 @@ Alias for `size`, returns the number of characters:
 "héllo".length  # 5
 ```
 
+### `bytesize`
+
+Returns the number of bytes in UTF-8 encoding:
+
+```vibe
+"hé".bytesize  # 3
+```
+
+### `ord`
+
+Returns the codepoint of the first character:
+
+```vibe
+"hé".ord  # 104
+```
+
+### `chr`
+
+Returns the first character (or `nil` for empty strings):
+
+```vibe
+"hé".chr  # "h"
+"".chr    # nil
+```
+
 ### `empty?`
 
 Returns true when the string has no characters:
@@ -130,6 +155,22 @@ Returns true when `substring` appears in the string:
 "vibescript".include?("script") # true
 ```
 
+### `match(pattern)`
+
+Regex match returning `[full, capture1, ...]` or `nil`:
+
+```vibe
+"ID-12 ID-34".match("ID-([0-9]+)") # ["ID-12", "12"]
+```
+
+### `scan(pattern)`
+
+Regex scan returning all full matches:
+
+```vibe
+"ID-12 ID-34".scan("ID-[0-9]+") # ["ID-12", "ID-34"]
+```
+
 ### `index(substring, offset = 0)`
 
 Returns the first character index for `substring`, or `nil` when not found:
@@ -159,20 +200,22 @@ Returns a character or substring; returns `nil` when out of bounds:
 "héllo".slice(99)   # nil
 ```
 
-### `sub(pattern, replacement)`
+### `sub(pattern, replacement, regex: false)`
 
-Replaces the first occurrence of `pattern` (string-only):
+Replaces the first occurrence of `pattern`:
 
 ```vibe
 "bananas".sub("na", "NA") # "baNAnas"
+"ID-12 ID-34".sub("ID-[0-9]+", "X", regex: true) # "X ID-34"
 ```
 
-### `gsub(pattern, replacement)`
+### `gsub(pattern, replacement, regex: false)`
 
-Replaces all occurrences of `pattern` (string-only):
+Replaces all occurrences of `pattern`:
 
 ```vibe
 "bananas".gsub("na", "NA") # "baNANAs"
+"ID-12 ID-34".gsub("ID-[0-9]+", "X", regex: true) # "X X"
 ```
 
 ### `delete_prefix(prefix)`
@@ -222,7 +265,8 @@ Returns `replacement`:
 
 ### Bang aliases
 
-The following methods are supported as aliases and return transformed strings:
+The following methods are supported as aliases and return transformed strings.
+When there is no change, bang methods return `nil`.
 
 - `strip!`, `lstrip!`, `rstrip!`, `chomp!`
 - `delete_prefix!`, `delete_suffix!`

examples/strings/operations.vibe

@@ -18,16 +18,25 @@ def run
   sample = "  Vibescript Example  "
   indexed = "héllo hello"
   immutable = "  hello  "
+  ids = "ID-12 ID-34"
   {
     normalized: normalize(sample),
+    bytesize: "hé".bytesize,
+    ord: "hé".ord,
+    chr: "hé".chr,
     upper: sample.strip.upcase,
     lower: sample.strip.downcase,
     capitalize: "hÉLLo wORLD".capitalize,
     swapcase: "Hello VIBE".swapcase,
     reverse: "héllo".reverse,
     sub: "bananas".sub("na", "NA"),
     gsub: "bananas".gsub("na", "NA"),
+    sub_regex: ids.sub("ID-[0-9]+", "X", regex: true),
+    gsub_regex: ids.gsub("ID-[0-9]+", "X", regex: true),
+    match: ids.match("ID-([0-9]+)"),
+    scan: ids.scan("ID-[0-9]+"),
     strip_bang: immutable.strip!,
+    strip_bang_nochange: "hello".strip!,
     immutable_after: immutable,
     clear: "hello".clear,
     concat: "he".concat("llo", "!"),

vibes/examples_test.go

@@ -1519,41 +1519,49 @@ func TestExamples(t *testing.T) {
 			file:     "strings/operations.vibe",
 			function: "run",
 			want: hashVal(map[string]Value{
-				"normalized":      strVal("vibescript example"),
-				"upper":           strVal("VIBESCRIPT EXAMPLE"),
-				"lower":           strVal("vibescript example"),
-				"capitalize":      strVal("Héllo world"),
-				"swapcase":        strVal("hELLO vibe"),
-				"reverse":         strVal("olléh"),
-				"sub":             strVal("baNAnas"),
-				"gsub":            strVal("baNANAs"),
-				"strip_bang":      strVal("hello"),
-				"immutable_after": strVal("  hello  "),
-				"clear":           strVal(""),
-				"concat":          strVal("hello!"),
-				"concat_noop":     strVal("hello"),
-				"replace":         strVal("new"),
-				"sub_bang":        strVal("baNAnas"),
-				"gsub_bang":       strVal("baNANAs"),
-				"lstrip":          strVal("hello\t"),
-				"rstrip":          strVal("\thello"),
-				"chomp_default":   strVal("line"),
-				"chomp_custom":    strVal("path//"),
-				"delete_prefix":   strVal("happy"),
-				"delete_suffix":   strVal("report"),
-				"split_default":   arrayVal(strVal("one"), strVal("two"), strVal("three")),
-				"split_custom":    arrayVal(strVal("a"), strVal("b"), strVal("c")),
-				"tags":            arrayVal(strVal("ruby"), strVal("go"), strVal("vibescript")),
-				"empty_true":      boolVal(true),
-				"empty_false":     boolVal(false),
-				"starts":          boolVal(true),
-				"ends":            boolVal(true),
-				"include":         boolVal(true),
-				"index":           intVal(2),
-				"rindex":          intVal(8),
-				"slice_char":      strVal("é"),
-				"slice_range":     strVal("éllo"),
-				"length":          intVal(5),
+				"normalized":          strVal("vibescript example"),
+				"bytesize":            intVal(3),
+				"ord":                 intVal(104),
+				"chr":                 strVal("h"),
+				"upper":               strVal("VIBESCRIPT EXAMPLE"),
+				"lower":               strVal("vibescript example"),
+				"capitalize":          strVal("Héllo world"),
+				"swapcase":            strVal("hELLO vibe"),
+				"reverse":             strVal("olléh"),
+				"sub":                 strVal("baNAnas"),
+				"gsub":                strVal("baNANAs"),
+				"sub_regex":           strVal("X ID-34"),
+				"gsub_regex":          strVal("X X"),
+				"match":               arrayVal(strVal("ID-12"), strVal("12")),
+				"scan":                arrayVal(strVal("ID-12"), strVal("ID-34")),
+				"strip_bang":          strVal("hello"),
+				"strip_bang_nochange": nilVal(),
+				"immutable_after":     strVal("  hello  "),
+				"clear":               strVal(""),
+				"concat":              strVal("hello!"),
+				"concat_noop":         strVal("hello"),
+				"replace":             strVal("new"),
+				"sub_bang":            strVal("baNAnas"),
+				"gsub_bang":           strVal("baNANAs"),
+				"lstrip":              strVal("hello\t"),
+				"rstrip":              strVal("\thello"),
+				"chomp_default":       strVal("line"),
+				"chomp_custom":        strVal("path//"),
+				"delete_prefix":       strVal("happy"),
+				"delete_suffix":       strVal("report"),
+				"split_default":       arrayVal(strVal("one"), strVal("two"), strVal("three")),
+				"split_custom":        arrayVal(strVal("a"), strVal("b"), strVal("c")),
+				"tags":                arrayVal(strVal("ruby"), strVal("go"), strVal("vibescript")),
+				"empty_true":          boolVal(true),
+				"empty_false":         boolVal(false),
+				"starts":              boolVal(true),
+				"ends":                boolVal(true),
+				"include":             boolVal(true),
+				"index":               intVal(2),
+				"rindex":              intVal(8),
+				"slice_char":          strVal("é"),
+				"slice_range":         strVal("éllo"),
+				"length":              intVal(5),
 			}),
 		},
 	}