Add OptionStrict for strict UTF-8 handling

Implemented `OptionStrict` which allows `WordsToFormattedCase` to return an error when invalid UTF-8 sequences are encountered.
Updated `upperCaseFirstLower` to accept a `strict` boolean.
Updated `WordsToFormattedCase` to use `upperCaseFirstLower` with the strict setting from `caseConfig`.
Added tests for `OptionStrict`.

Co-authored-by: arran4 <111667+arran4@users.noreply.github.com>

Author: google-labs-jules[bot]

types.go

@@ -36,7 +36,10 @@ type SeparatorWord string
 
 // String implementations
 func (w SingleCaseWord) String() string     { return strings.ToLower(string(w)) }
-func (w FirstUpperCaseWord) String() string { return upperCaseFirstLower(string(w)) }
+func (w FirstUpperCaseWord) String() string {
+	res, _ := upperCaseFirstLower(string(w), false)
+	return res
+}
 func (w AcronymWord) String() string        { return string(w) }
 func (w UpperCaseWord) String() string      { return strings.ToUpper(string(w)) }
 func (w SeparatorWord) String() string      { return string(w) }
@@ -119,11 +122,14 @@ func MustLowerCaseFirst(s string) string {
 }
 
 // upperCaseFirstLower capitalizes the first character and lowercases the rest.
-func upperCaseFirstLower(s string) string {
+func upperCaseFirstLower(s string, strict bool) (string, error) {
 	if s == "" {
-		return ""
+		return "", nil
 	}
 	r, size := utf8.DecodeRuneInString(s)
+	if strict && r == utf8.RuneError {
+		return "", fmt.Errorf("%w: invalid rune", ErrRune)
+	}
 	u := unicode.ToUpper(r)
 
 	// Check if changes are needed.
@@ -133,6 +139,9 @@ func upperCaseFirstLower(s string) string {
 	needChange := (r != u) || (r == utf8.RuneError && size == 1)
 	if !needChange {
 		for _, rc := range s[size:] {
+			if strict && rc == utf8.RuneError {
+				return "", fmt.Errorf("%w: invalid rune", ErrRune)
+			}
 			if unicode.ToLower(rc) != rc {
 				needChange = true
 				break
@@ -141,16 +150,19 @@ func upperCaseFirstLower(s string) string {
 	}
 
 	if !needChange {
-		return s
+		return s, nil
 	}
 
 	var b strings.Builder
 	b.Grow(len(s))
 	b.WriteRune(u)
 	for _, rc := range s[size:] {
+		if strict && rc == utf8.RuneError {
+			return "", fmt.Errorf("%w: invalid rune", ErrRune)
+		}
 		b.WriteRune(unicode.ToLower(rc))
 	}
-	return b.String()
+	return b.String(), nil
 }
 
 func (w ExactCaseWord) String() string { return string(w) }
@@ -187,6 +199,7 @@ type caseConfig struct {
 	mixCaseSupport bool
 	firstUpper     bool
 	firstLower     bool
+	strict         bool
 }
 
 // OptionDelimiter sets the delimiter between words.
@@ -219,6 +232,11 @@ func OptionUpperIndicator(d string) Option {
 	return func(cfg *caseConfig) { cfg.upperIndicator = d }
 }
 
+// OptionStrict sets strict mode, which returns an error if invalid UTF-8 sequences are encountered.
+func OptionStrict() Option {
+	return func(cfg *caseConfig) { cfg.strict = true }
+}
+
 // ToFormattedCase generates formatted case strings with the given options
 // Deprecated: Use WordsToFormattedCase. This function suppresses errors for backward compatibility.
 func ToFormattedCase(words []Word, opts ...Option) string {
@@ -266,7 +284,11 @@ func WordsToFormattedCase(words []Word, opts ...any) (string, error) {
 			} else if cfg.allLower || cfg.whispering {
 				w = strings.ToLower(w)
 			} else if cfg.caseMode == CMAllTitle {
-				w = upperCaseFirstLower(w)
+				var err error
+				w, err = upperCaseFirstLower(w, cfg.strict)
+				if err != nil {
+					return "", err
+				}
 			} else {
 				w = strings.ToLower(w)
 			}
@@ -281,7 +303,11 @@ func WordsToFormattedCase(words []Word, opts ...any) (string, error) {
 				w = strings.ToLower(w)
 			}
 		case FirstUpperCaseWord:
-			w = word.String()
+			var err error
+			w, err = upperCaseFirstLower(string(word), cfg.strict)
+			if err != nil {
+				return "", err
+			}
 			if cfg.mixCaseSupport {
 				w = splitMixCase(w, cfg.delimiter)
 			}
@@ -297,7 +323,11 @@ func WordsToFormattedCase(words []Word, opts ...any) (string, error) {
 			} else if cfg.whispering {
 				w = strings.ToLower(w)
 			} else if cfg.caseMode == CMAllTitle {
-				w = upperCaseFirstLower(w)
+				var err error
+				w, err = upperCaseFirstLower(w, cfg.strict)
+				if err != nil {
+					return "", err
+				}
 			}
 		case UpperCaseWord:
 			w = word.String()
@@ -306,7 +336,11 @@ func WordsToFormattedCase(words []Word, opts ...any) (string, error) {
 			} else if cfg.allLower || cfg.whispering {
 				w = strings.ToLower(w)
 			} else if cfg.caseMode == CMAllTitle {
-				w = upperCaseFirstLower(w)
+				var err error
+				w, err = upperCaseFirstLower(w, cfg.strict)
+				if err != nil {
+					return "", err
+				}
 			} else {
 				w = strings.ToLower(w)
 			}

types_internal_test.go

@@ -1,6 +1,7 @@
 package strings2
 
 import (
+	"errors"
 	"testing"
 )
 
@@ -74,27 +75,77 @@ func TestUpperCaseFirstLower_Correctness(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got := upperCaseFirstLower(tt.input)
+			got, err := upperCaseFirstLower(tt.input, false)
+			if err != nil {
+				t.Errorf("upperCaseFirstLower(%q, false) returned unexpected error: %v", tt.input, err)
+			}
 			if got != tt.expected {
 				t.Errorf("upperCaseFirstLower(%q) = %q, want %q", tt.input, got, tt.expected)
 			}
 		})
 	}
 }
 
+func TestUpperCaseFirstLower_Strict(t *testing.T) {
+	tests := []struct {
+		name      string
+		input     string
+		expectErr bool
+	}{
+		{
+			name:      "Valid ASCII",
+			input:     "test",
+			expectErr: false,
+		},
+		{
+			name:      "Valid Unicode",
+			input:     "äpfel",
+			expectErr: false,
+		},
+		{
+			name:      "Invalid UTF-8 Start",
+			input:     "\xfftest",
+			expectErr: true,
+		},
+		{
+			name:      "Invalid UTF-8 Middle",
+			input:     "te\xffst",
+			expectErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := upperCaseFirstLower(tt.input, true)
+			if tt.expectErr {
+				if err == nil {
+					t.Errorf("upperCaseFirstLower(%q, true) expected error, got nil", tt.input)
+				}
+				if !errors.Is(err, ErrRune) {
+					t.Errorf("upperCaseFirstLower(%q, true) expected ErrRune, got %v", tt.input, err)
+				}
+			} else {
+				if err != nil {
+					t.Errorf("upperCaseFirstLower(%q, true) unexpected error: %v", tt.input, err)
+				}
+			}
+		})
+	}
+}
+
 func TestUpperCaseFirstLower_Allocations(t *testing.T) {
 	// Tests that no allocation occurs if the string is already correct
 	input := "Test"
 	if testing.AllocsPerRun(10, func() {
-		upperCaseFirstLower(input)
+		_, _ = upperCaseFirstLower(input, false)
 	}) > 0 {
 		t.Errorf("upperCaseFirstLower(%q) allocated memory when no change was needed", input)
 	}
 
 	// Test that allocation occurs when change IS needed
 	input2 := "test"
 	if testing.AllocsPerRun(10, func() {
-		upperCaseFirstLower(input2)
+		_, _ = upperCaseFirstLower(input2, false)
 	}) == 0 {
 		t.Errorf("upperCaseFirstLower(%q) did not allocate memory when change was needed", input2)
 	}

types_test.go

@@ -454,3 +454,63 @@ func TestToFormattedCase_MultibyteFirstLower(t *testing.T) {
 		t.Errorf("ToFormattedCase with OptionFirstLower for %q = %q, want %q", "Äpfel", got, want)
 	}
 }
+
+func TestOptionStrict(t *testing.T) {
+	tests := []struct {
+		name      string
+		words     []Word
+		options   []Option
+		expectErr bool
+	}{
+		{
+			name: "FirstUpperCaseWord Invalid UTF-8 Strict",
+			words: []Word{
+				FirstUpperCaseWord("\xfftest"),
+			},
+			options:   []Option{OptionStrict()},
+			expectErr: true,
+		},
+		{
+			name: "FirstUpperCaseWord Invalid UTF-8 Non-Strict",
+			words: []Word{
+				FirstUpperCaseWord("\xfftest"),
+			},
+			options:   []Option{},
+			expectErr: false,
+		},
+		{
+			name: "SingleCaseWord CMAllTitle Invalid UTF-8 Strict",
+			words: []Word{
+				SingleCaseWord("\xfftest"),
+			},
+			options:   []Option{OptionCaseMode(CMAllTitle), OptionStrict()},
+			expectErr: true,
+		},
+		{
+			name: "SingleCaseWord CMAllTitle Invalid UTF-8 Non-Strict",
+			words: []Word{
+				SingleCaseWord("\xfftest"),
+			},
+			options:   []Option{OptionCaseMode(CMAllTitle)},
+			expectErr: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := WordsToFormattedCase(tt.words, convertOptions(tt.options)...)
+			if tt.expectErr {
+				if err == nil {
+					t.Error("expected error, got nil")
+				}
+				if !errors.Is(err, ErrRune) {
+					t.Errorf("expected ErrRune, got %v", err)
+				}
+			} else {
+				if err != nil {
+					t.Errorf("unexpected error: %v", err)
+				}
+			}
+		})
+	}
+}