golang.org/x/exp v0.0.0-20251023183803-a4bb9ffd2546: utf8string

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify golang.org/x/exp/utf8string in pkg:golang/golang.org/x/exp@v0.0.0-20251023183803-a4bb9ffd2546
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/exp@v0.0.0-20251023183803-a4bb9ffd2546
Demonstrate these symbols/APIs:
  - golang.org/x/exp/utf8string

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:b3b0a0c9497c7adb889a1856e075f661e062a73dc438c590a8e5418eb6bdb3f1","contract":["utf8string.NewString initializes String and reports RuneCount, IsASCII, and original string value","utf8string.At indexes multi-byte runes by character position without splitting multi-byte sequences","utf8string.Slice extracts string substrings using rune boundaries rather than byte offsets","utf8string.String.Init initializes an existing struct instance and supports rune counting and slicing"],"goal":"verify golang.org/x/exp/utf8string in pkg:golang/golang.org/x/exp@v0.0.0-20251023183803-a4bb9ffd2546","kind":"HOW","packages":["pkg:golang/golang.org/x/exp@v0.0.0-20251023183803-a4bb9ffd2546"],"schemaVersion":1,"symbols":["golang.org/x/exp/utf8string"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/golang.org/x/exp@v0.0.0-20251023183803-a4bb9ffd2546"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/exp@v0.0.0-20251023183803-a4bb9ffd2546","symbols":["golang.org/x/exp/utf8string"],"verifierAdapter":"golang@1"}

module example.com/utf8string-sample

go 1.26.0

require golang.org/x/exp v0.0.0-20251023183803-a4bb9ffd2546

golang.org/x/exp v0.0.0-20251023183803-a4bb9ffd2546 h1:mgKeJMpvi0yx/sU5GsxQ7p6s2wtOnGAHZWCHUM4KGzY=
golang.org/x/exp v0.0.0-20251023183803-a4bb9ffd2546/go.mod h1:j/pmGrbnkbPtQfxEe5D0VQhZC6qKbfKifgD0oM7sR70=

{
  "schemaVersion": 1,
  "goal": "verify golang.org/x/exp/utf8string in pkg:golang/golang.org/x/exp@v0.0.0-20251023183803-a4bb9ffd2546",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/exp@v0.0.0-20251023183803-a4bb9ffd2546"
  ],
  "symbols": [
    "golang.org/x/exp/utf8string"
  ]
}

package main

import (
	"fmt"
	"os"

	utf8sample "example.com/utf8string-sample"
	"golang.org/x/exp/utf8string"
)

func main() {
	// Assertion 1: utf8string.NewString correctly computes RuneCount and IsASCII
	asciiStr := "Hello, World!"
	uAscii := utf8string.NewString(asciiStr)
	if uAscii.RuneCount() != 13 {
		fmt.Fprintf(os.Stderr, "FAIL: expected RuneCount 13 for ascii, got %d\n", uAscii.RuneCount())
		os.Exit(1)
	}
	if !uAscii.IsASCII() {
		fmt.Fprintf(os.Stderr, "FAIL: expected IsASCII true for %q\n", asciiStr)
		os.Exit(1)
	}
	if !utf8sample.IsASCIIString(asciiStr) {
		fmt.Fprintf(os.Stderr, "FAIL: helper IsASCIIString returned false for %q\n", asciiStr)
		os.Exit(1)
	}

	// Multi-byte Unicode: "안녕하세요 🚀" (5 Korean chars + 1 space + 1 emoji = 7 runes, but 20 bytes)
	multiByteStr := "안녕하세요 🚀"
	uMulti := utf8string.NewString(multiByteStr)
	if uMulti.RuneCount() != 7 {
		fmt.Fprintf(os.Stderr, "FAIL: expected RuneCount 7 for multi-byte, got %d\n", uMulti.RuneCount())
		os.Exit(1)
	}
	if uMulti.IsASCII() {
		fmt.Fprintf(os.Stderr, "FAIL: expected IsASCII false for %q\n", multiByteStr)
		os.Exit(1)
	}
	if uMulti.String() != multiByteStr {
		fmt.Fprintf(os.Stderr, "FAIL: String() mismatch, expected %q, got %q\n", multiByteStr, uMulti.String())
		os.Exit(1)
	}

	// Assertion 2: utf8string.At retrieves rune by rune-index without byte slicing errors
	// '안' = U+C548, '하' = U+D558, '세' = U+C138, '요' = U+C694, ' ' = U+0020, '🚀' = U+1F680
	if r := uMulti.At(0); r != '안' {
		fmt.Fprintf(os.Stderr, "FAIL: At(0) expected '안', got %c (%U)\n", r, r)
		os.Exit(1)
	}
	if r := uMulti.At(4); r != '요' {
		fmt.Fprintf(os.Stderr, "FAIL: At(4) expected '요', got %c (%U)\n", r, r)
		os.Exit(1)
	}
	if r := uMulti.At(6); r != '🚀' {
		fmt.Fprintf(os.Stderr, "FAIL: At(6) expected '🚀', got %c (%U)\n", r, r)
		os.Exit(1)
	}
	if r := utf8sample.RuneAt(multiByteStr, 6); r != '🚀' {
		fmt.Fprintf(os.Stderr, "FAIL: RuneAt helper expected '🚀', got %c (%U)\n", r, r)
		os.Exit(1)
	}

	// Assertion 3: utf8string.Slice slices by rune boundaries [i, j)
	// Subslice [0, 5) -> "안녕하세요"
	slicedGreeting := uMulti.Slice(0, 5)
	if slicedGreeting != "안녕하세요" {
		fmt.Fprintf(os.Stderr, "FAIL: Slice(0, 5) expected '안녕하세요', got %q\n", slicedGreeting)
		os.Exit(1)
	}
	// Subslice [6, 7) -> "🚀"
	slicedEmoji := uMulti.Slice(6, 7)
	if slicedEmoji != "🚀" {
		fmt.Fprintf(os.Stderr, "FAIL: Slice(6, 7) expected '🚀', got %q\n", slicedEmoji)
		os.Exit(1)
	}

	// Assertion 4: Helpers for safe truncation and sub-stringing by rune counts
	truncated := utf8sample.TruncateRunes(multiByteStr, 2)
	if truncated != "안녕" {
		fmt.Fprintf(os.Stderr, "FAIL: TruncateRunes expected '안녕', got %q\n", truncated)
		os.Exit(1)
	}
	sub := utf8sample.SubstringByRune(multiByteStr, 2, 5)
	if sub != "하세요" {
		fmt.Fprintf(os.Stderr, "FAIL: SubstringByRune expected '하세요', got %q\n", sub)
		os.Exit(1)
	}

	// Assertion 5: utf8string.String Init method works as alternative to NewString
	var directStr utf8string.String
	directStr.Init("Alpha Beta")
	if directStr.RuneCount() != 10 || directStr.Slice(6, 10) != "Beta" {
		fmt.Fprintf(os.Stderr, "FAIL: direct Init() failed\n")
		os.Exit(1)
	}

	fmt.Println("PASS: golang.org/x/exp/utf8string contract passed")
}

package utf8sample

import (
	"golang.org/x/exp/utf8string"
)

// TruncateRunes truncates a UTF-8 string to maxRunes without splitting multi-byte runes.
func TruncateRunes(s string, maxRunes int) string {
	u := utf8string.NewString(s)
	if u.RuneCount() <= maxRunes {
		return u.String()
	}
	return u.Slice(0, maxRunes)
}

// SubstringByRune extracts runes in [start, end) range safely.
func SubstringByRune(s string, start, end int) string {
	u := utf8string.NewString(s)
	count := u.RuneCount()
	if start < 0 {
		start = 0
	}
	if start > count {
		start = count
	}
	if end < start {
		end = start
	}
	if end > count {
		end = count
	}
	return u.Slice(start, end)
}

// RuneAt returns the rune at rune-index i.
func RuneAt(s string, i int) rune {
	u := utf8string.NewString(s)
	return u.At(i)
}

// IsASCIIString checks if the string contains only ASCII characters.
func IsASCIIString(s string) bool {
	u := utf8string.NewString(s)
	return u.IsASCII()
}