Add numeric conversion builtins

Author: mgomes

ROADMAP.md

@@ -285,7 +285,7 @@ Goal: reduce host-side boilerplate for common scripting tasks.
 - [x] Add regex matching/replacement helpers.
 - [x] Add UUID/random identifier utilities with deterministic test hooks.
 - [x] Add richer date/time parsing helpers for common layouts.
-- [ ] Add safer numeric conversions and clamp/round helpers.
+- [x] Add safer numeric conversions and clamp/round helpers.
 
 ### Collections and Strings
 

docs/builtins.md

@@ -75,6 +75,21 @@ short = random_id(8)
 token = random_id()
 ```
 
+## Numeric Conversion
+
+### `to_int(value)`
+
+Converts `int`, integral `float`, or base-10 numeric `string` values into `int`.
+
+### `to_float(value)`
+
+Converts `int`, `float`, or numeric `string` values into `float`.
+
+```vibe
+count = to_int("42")
+ratio = to_float("1.25")
+```
+
 ## JSON
 
 ### `JSON.parse(string)`

vibes/builtins.go

@@ -5,8 +5,10 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"math"
 	"reflect"
 	"regexp"
+	"strconv"
 	"strings"
 	"time"
 )
@@ -132,6 +134,76 @@ func builtinRandomID(exec *Execution, receiver Value, args []Value, kwargs map[s
 	return NewString(string(chars)), nil
 }
 
+func builtinToInt(exec *Execution, receiver Value, args []Value, kwargs map[string]Value, block Value) (Value, error) {
+	if len(args) != 1 {
+		return NewNil(), fmt.Errorf("to_int expects a single value argument")
+	}
+	if len(kwargs) > 0 {
+		return NewNil(), fmt.Errorf("to_int does not accept keyword arguments")
+	}
+	if !block.IsNil() {
+		return NewNil(), fmt.Errorf("to_int does not accept blocks")
+	}
+
+	switch args[0].Kind() {
+	case KindInt:
+		return args[0], nil
+	case KindFloat:
+		f := args[0].Float()
+		if math.Trunc(f) != f {
+			return NewNil(), fmt.Errorf("to_int cannot convert non-integer float")
+		}
+		n, err := floatToInt64Checked(f, "to_int")
+		if err != nil {
+			return NewNil(), err
+		}
+		return NewInt(n), nil
+	case KindString:
+		s := strings.TrimSpace(args[0].String())
+		if s == "" {
+			return NewNil(), fmt.Errorf("to_int expects a numeric string")
+		}
+		n, err := strconv.ParseInt(s, 10, 64)
+		if err != nil {
+			return NewNil(), fmt.Errorf("to_int expects a base-10 integer string")
+		}
+		return NewInt(n), nil
+	default:
+		return NewNil(), fmt.Errorf("to_int expects int, float, or string")
+	}
+}
+
+func builtinToFloat(exec *Execution, receiver Value, args []Value, kwargs map[string]Value, block Value) (Value, error) {
+	if len(args) != 1 {
+		return NewNil(), fmt.Errorf("to_float expects a single value argument")
+	}
+	if len(kwargs) > 0 {
+		return NewNil(), fmt.Errorf("to_float does not accept keyword arguments")
+	}
+	if !block.IsNil() {
+		return NewNil(), fmt.Errorf("to_float does not accept blocks")
+	}
+
+	switch args[0].Kind() {
+	case KindInt:
+		return NewFloat(float64(args[0].Int())), nil
+	case KindFloat:
+		return args[0], nil
+	case KindString:
+		s := strings.TrimSpace(args[0].String())
+		if s == "" {
+			return NewNil(), fmt.Errorf("to_float expects a numeric string")
+		}
+		f, err := strconv.ParseFloat(s, 64)
+		if err != nil {
+			return NewNil(), fmt.Errorf("to_float expects a numeric string")
+		}
+		return NewFloat(f), nil
+	default:
+		return NewNil(), fmt.Errorf("to_float expects int, float, or string")
+	}
+}
+
 func formatUUIDv4(raw []byte) string {
 	hexValue := hex.EncodeToString(raw)
 	return hexValue[0:8] + "-" + hexValue[8:12] + "-" + hexValue[12:16] + "-" + hexValue[16:20] + "-" + hexValue[20:32]

vibes/interpreter.go

@@ -77,6 +77,8 @@ func NewEngine(cfg Config) (*Engine, error) {
 	engine.RegisterZeroArgBuiltin("now", builtinNow)
 	engine.RegisterZeroArgBuiltin("uuid", builtinUUID)
 	engine.RegisterBuiltin("random_id", builtinRandomID)
+	engine.RegisterBuiltin("to_int", builtinToInt)
+	engine.RegisterBuiltin("to_float", builtinToFloat)
 	engine.builtins["JSON"] = NewObject(map[string]Value{
 		"parse":     NewBuiltin("JSON.parse", builtinJSONParse),
 		"stringify": NewBuiltin("JSON.stringify", builtinJSONStringify),

vibes/runtime_test.go

@@ -1689,6 +1689,64 @@ func TestTimeParseCommonLayouts(t *testing.T) {
 	}
 }
 
+func TestNumericConversionBuiltins(t *testing.T) {
+	script := compileScript(t, `
+    def conversions()
+      {
+        int_from_int: to_int(5),
+        int_from_float: to_int(5.0),
+        int_from_string: to_int("42"),
+        float_from_int: to_float(5),
+        float_from_float: to_float(1.25),
+        float_from_string: to_float("2.5")
+      }
+    end
+
+    def bad_int_fraction()
+      to_int(1.5)
+    end
+
+    def bad_int_string()
+      to_int("abc")
+    end
+
+    def bad_float_string()
+      to_float("abc")
+    end
+    `)
+
+	result := callFunc(t, script, "conversions", nil)
+	if result.Kind() != KindHash {
+		t.Fatalf("expected hash, got %v", result.Kind())
+	}
+	got := result.Hash()
+	if !got["int_from_int"].Equal(NewInt(5)) || !got["int_from_float"].Equal(NewInt(5)) || !got["int_from_string"].Equal(NewInt(42)) {
+		t.Fatalf("to_int conversions mismatch: %#v", got)
+	}
+	if got["float_from_int"].Kind() != KindFloat || got["float_from_int"].Float() != 5 {
+		t.Fatalf("float_from_int mismatch: %v", got["float_from_int"])
+	}
+	if got["float_from_float"].Kind() != KindFloat || got["float_from_float"].Float() != 1.25 {
+		t.Fatalf("float_from_float mismatch: %v", got["float_from_float"])
+	}
+	if got["float_from_string"].Kind() != KindFloat || got["float_from_string"].Float() != 2.5 {
+		t.Fatalf("float_from_string mismatch: %v", got["float_from_string"])
+	}
+
+	_, err := script.Call(context.Background(), "bad_int_fraction", nil, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "to_int cannot convert non-integer float") {
+		t.Fatalf("expected fractional to_int error, got %v", err)
+	}
+	_, err = script.Call(context.Background(), "bad_int_string", nil, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "to_int expects a base-10 integer string") {
+		t.Fatalf("expected string to_int error, got %v", err)
+	}
+	_, err = script.Call(context.Background(), "bad_float_string", nil, CallOptions{})
+	if err == nil || !strings.Contains(err.Error(), "to_float expects a numeric string") {
+		t.Fatalf("expected string to_float error, got %v", err)
+	}
+}
+
 func TestJSONBuiltins(t *testing.T) {
 	script := compileScript(t, `
     def parse_payload()