{"id":35004752,"url":"https://github.com/carlos-sweb/z-string","last_synced_at":"2026-01-13T21:57:02.899Z","repository":{"id":330647389,"uuid":"1123466483","full_name":"carlos-sweb/z-string","owner":"carlos-sweb","description":"ECMAScript String API implementation in Zig - 96.4% spec compliance, UTF-16 indexing, runtime-ready","archived":false,"fork":false,"pushed_at":"2025-12-27T23:01:33.000Z","size":114,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-28T14:18:59.518Z","etag":null,"topics":["ecmascript","javascript","js-runtime","runtime","spec-compliance","string","string-api","utf16","zig","zig-lang"],"latest_commit_sha":null,"homepage":null,"language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carlos-sweb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-26T23:49:14.000Z","updated_at":"2025-12-27T23:01:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/carlos-sweb/z-string","commit_stats":null,"previous_names":["carlos-sweb/z-string"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/carlos-sweb/z-string","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlos-sweb%2Fz-string","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlos-sweb%2Fz-string/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlos-sweb%2Fz-string/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlos-sweb%2Fz-string/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlos-sweb","download_url":"https://codeload.github.com/carlos-sweb/z-string/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlos-sweb%2Fz-string/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ecmascript","javascript","js-runtime","runtime","spec-compliance","string","string-api","utf16","zig","zig-lang"],"created_at":"2025-12-27T04:33:21.477Z","updated_at":"2026-01-13T21:57:02.893Z","avatar_url":"https://github.com/carlos-sweb.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# z-string\n\n**ECMAScript String API implementation in Zig**\n\n[![Zig Version](https://img.shields.io/badge/zig-0.15.2-orange.svg)](https://ziglang.org/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Status](https://img.shields.io/badge/status-active-green.svg)](#-project-status)\n\nA Zig library that implements the ECMAScript 262 String API with full spec compliance. Designed to be the foundation for JavaScript/ECMAScript runtime engines written in Zig.\n\n## 🎯 Project Goals\n\n- **Spec Compliance**: Match ECMAScript 262 String API behavior exactly\n- **UTF-16 Indexing**: Use UTF-16 code units for indexing (like JavaScript)\n- **Performance**: Efficient implementation leveraging Zig's strengths\n- **Runtime Ready**: Built to be integrated into ECMAScript runtime engines\n\n## ✨ Features\n\n### ✅ Implemented (33/33 methods - 100%)\n\n#### Character Access (4 methods)\n- `charAt(index)` - Get character at index\n- `at(index)` - Get character with negative indexing support\n- `charCodeAt(index)` - Get UTF-16 code unit value\n- `codePointAt(index)` - Get Unicode code point\n\n#### Search (5 methods)\n- `indexOf(searchString, position?)` - Find first occurrence\n- `lastIndexOf(searchString, position?)` - Find last occurrence\n- `includes(searchString, position?)` - Check if contains substring\n- `startsWith(searchString, position?)` - Check if starts with substring\n- `endsWith(searchString, length?)` - Check if ends with substring\n\n#### Transform (4 methods)\n- `slice(start, end?)` - Extract substring with negative indices\n- `substring(start, end?)` - Extract substring (swaps if start \u003e end)\n- `concat(...strings)` - Concatenate strings\n- `repeat(count)` - Repeat string N times\n\n#### Padding (2 methods)\n- `padStart(targetLength, padString?)` - Pad from start\n- `padEnd(targetLength, padString?)` - Pad from end\n\n#### Trimming (5 methods)\n- `trim()` - Remove whitespace from both ends\n- `trimStart() / trimLeft()` - Remove whitespace from start\n- `trimEnd() / trimRight()` - Remove whitespace from end\n\n#### Split (1 method)\n- `split(separator?, limit?)` - Split string into array\n\n#### Case Conversion (4 methods)\n- `toLowerCase()` - Convert to lowercase\n- `toUpperCase()` - Convert to uppercase\n- `toLocaleLowerCase(locale?)` - Locale-aware lowercase*\n- `toLocaleUpperCase(locale?)` - Locale-aware uppercase*\n\n#### Utility (4 methods)\n- `toString()` - Get string value\n- `valueOf()` - Get primitive value\n- `localeCompare(that, locales?, options?)` - Compare strings*\n- `normalize(form?)` - Unicode normalization (NFC/NFD/NFKC/NFKD)**\n\n\\* Basic implementation without full locale support (ICU integration planned)\n\n\\*\\* Supports common Latin characters (À-ÿ range) with proper decomposition/composition\n\n#### Regex Methods (5 methods) ✅\n- `search(regexp)` - Search with regex\n- `match(regexp)` - Match with regex\n- `matchAll(regexp)` - Match all with regex\n- `replace(searchValue, replaceValue)` - Replace with regex support\n- `replaceAll(searchValue, replaceValue)` - Replace all with regex support\n\n## 📦 Installation\n\n### Language Support\n\nz-string can be used from multiple languages:\n- **Zig**: Native Zig API (recommended)\n- **C**: C-compatible API with manual memory management\n- **C++**: Modern C++17 API with RAII and STL integration\n\n📖 **See language-specific guides:**\n- **[C.md](C.md)** - Complete guide for C usage\n- **[CPP.md](CPP.md)** - Complete guide for C++ usage\n\n### Using Zig Package Manager (0.15.0+)\n\n**Note:** z-string depends on [zregexp](https://github.com/carlos-sweb/zregexp) for regex functionality. You'll need to set it up as a local dependency or wait for published releases.\n\n#### Quick Setup (Local Development)\n\n```bash\n# Clone z-string\ngit clone https://github.com/carlos-sweb/z-string.git\ncd z-string\n\n# Clone zregexp dependency\nmkdir -p deps\ngit clone https://github.com/carlos-sweb/zregexp.git deps/zregexp\n\n# Build and test\nzig build test\n```\n\n#### Future: Package Manager Installation\n\nOnce published, you'll be able to add to your `build.zig.zon`:\n\n```zig\n.{\n    .name = \"my-project\",\n    .version = \"0.1.0\",\n    .dependencies = .{\n        .zstring = .{\n            .url = \"https://github.com/carlos-sweb/z-string/archive/refs/tags/v0.2.0.tar.gz\",\n            .hash = \"1220...\", // Use zig fetch to get hash\n        },\n    },\n}\n```\n\nAdd to your `build.zig`:\n\n```zig\nconst zstring = b.dependency(\"zstring\", .{\n    .target = target,\n    .optimize = optimize,\n});\n\nexe.root_module.addImport(\"zstring\", zstring.module(\"zstring\"));\n```\n\n### Manual Installation\n\n```bash\ngit clone https://github.com/carlos-sweb/z-string.git\ncd z-string\nzig build test\n```\n\n## ⚠️ Error Handling\n\nz-string follows Zig's error handling philosophy. All operations that can fail return error unions:\n\n```zig\n// ✅ Proper error handling\nconst upper = try str.toUpperCase(allocator);\ndefer allocator.free(upper);\n\n// ✅ Handle specific errors\nconst result = str.toUpperCase(allocator) catch |err| {\n    std.log.err(\"Failed: {}\", .{err});\n    return err;\n};\n\n// ✅ Check optional returns\nconst char = try str.at(allocator, 0);\nif (char) |c| {\n    defer allocator.free(c);\n    // Use c...\n}\n```\n\n**📖 See [ERROR_HANDLING.md](ERROR_HANDLING.md) for comprehensive error handling guide.**\n\n## 🚀 Quick Start\n\n### Zig API\n\n```zig\nconst std = @import(\"std\");\nconst zstring = @import(\"zstring\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // Create a ZString\n    const str = zstring.ZString.init(\"Hello, World!\");\n\n    // Character access\n    const char = try str.charAt(allocator, 0);\n    defer allocator.free(char);\n    std.debug.print(\"First char: {s}\\n\", .{char}); // \"H\"\n\n    // Search\n    const pos = str.indexOf(\"World\", null);\n    std.debug.print(\"Position: {}\\n\", .{pos}); // 7\n\n    // Transform\n    const upper = try str.toUpperCase(allocator);\n    defer allocator.free(upper);\n    std.debug.print(\"Upper: {s}\\n\", .{upper}); // \"HELLO, WORLD!\"\n\n    // Split\n    const parts = try str.split(allocator, \", \", null);\n    defer zstring.ZString.freeSplitResult(allocator, parts);\n    std.debug.print(\"Parts: {s}, {s}\\n\", .{parts[0], parts[1]}); // \"Hello\", \"World!\"\n}\n```\n\n### C API\n\n```c\n#include \u003cstdio.h\u003e\n#include \"zstring.h\"\n\nint main(void) {\n    ZString* str = NULL;\n\n    // Create a string\n    if (zstring_init(\"Hello, World!\", \u0026str) != ZSTRING_OK) {\n        return 1;\n    }\n\n    // Convert to uppercase\n    char* upper = NULL;\n    if (zstring_to_upper_case(str, \u0026upper) == ZSTRING_OK) {\n        printf(\"Upper: %s\\n\", upper);  // \"HELLO, WORLD!\"\n        zstring_str_free(upper);\n    }\n\n    // Clean up\n    zstring_free(str);\n    return 0;\n}\n```\n\n**Build:** `gcc your_program.c -I./include -L. -lzstring -o your_program`\n\n📖 **See [C.md](C.md) for complete C API documentation.**\n\n### C++ API\n\n```cpp\n#include \u003ciostream\u003e\n#include \"zstring.hpp\"\n\nint main() {\n    try {\n        // Create a string (RAII - automatic cleanup)\n        zstring::String str(\"Hello, World!\");\n\n        // Convert to uppercase\n        auto upper = str.toUpperCase();\n        std::cout \u003c\u003c \"Upper: \" \u003c\u003c upper \u003c\u003c std::endl;  // \"HELLO, WORLD!\"\n\n        // Split into words\n        auto words = str.split(\" \");\n        for (const auto\u0026 word : words) {\n            std::cout \u003c\u003c \"Word: \" \u003c\u003c word \u003c\u003c std::endl;\n        }\n\n    } catch (const zstring::Exception\u0026 e) {\n        std::cerr \u003c\u003c \"Error: \" \u003c\u003c e.what() \u003c\u003c std::endl;\n        return 1;\n    }\n\n    return 0;\n}\n```\n\n**Build:** `g++ -std=c++17 your_program.cpp -I./include -L. -lzstring -o your_program`\n\n📖 **See [CPP.md](CPP.md) for complete C++ API documentation.**\n\n## 📚 Documentation\n\n### Key Concepts\n\n#### UTF-16 Indexing\n\nJavaScript uses UTF-16 code units for string indexing. z-string maintains this behavior for spec compliance:\n\n```zig\nconst str = zstring.ZString.init(\"😀\"); // Emoji (surrogate pair)\nstd.debug.print(\"Length: {}\\n\", .{str.length()}); // 2 (UTF-16 code units)\n```\n\n#### Memory Management\n\nMethods that return new strings require explicit memory management:\n\n```zig\nconst upper = try str.toUpperCase(allocator);\ndefer allocator.free(upper); // Caller owns the memory\n```\n\n#### Borrowed vs Owned Strings\n\n```zig\n// Borrowed (no allocation)\nconst borrowed = zstring.ZString.init(\"hello\");\n\n// Owned (allocated, must call deinit)\nvar owned = try zstring.ZString.initOwned(allocator, \"hello\");\ndefer owned.deinit();\n```\n\n### Examples\n\nSee the `examples/` directory for complete examples:\n- `character_access.zig` - Character access methods\n- `search_methods.zig` - Search and indexOf methods\n- `transform_methods.zig` - Slice, substring, concat, repeat\n- `padding_trimming_methods.zig` - Padding and trimming\n- `split_method.zig` - String splitting\n\nRun examples:\n```bash\nzig build example              # Character access\nzig build example-search       # Search methods\nzig build example-transform    # Transform methods\nzig build example-padding-trimming\nzig build example-split\nzig build example-errors       # Error handling (recommended!)\n```\n\n## 🧪 Testing\n\n```bash\n# Run all tests\nzig build test\n\n# Run benchmarks\nzig build bench\n```\n\n**Test Coverage:**\n- 372+ tests across all implemented methods\n- ECMAScript spec compliance tests\n- Unicode and emoji handling tests\n- Unicode normalization tests (NFC/NFD/NFKC/NFKD)\n- Edge case coverage\n\n## 🏗️ Architecture\n\n```\nz-string/\n├── src/\n│   ├── zstring.zig           # Public Zig API entry point\n│   ├── c_api.zig            # C API implementation\n│   ├── core/\n│   │   ├── utf16.zig         # UTF-8 ↔ UTF-16 conversion\n│   │   └── string.zig        # ZString struct\n│   └── methods/              # Method implementations (grouped by category)\n│       ├── access.zig        # charAt, at, charCodeAt, codePointAt\n│       ├── search.zig        # indexOf, lastIndexOf, includes, etc.\n│       ├── transform.zig     # slice, substring, concat, repeat\n│       ├── padding.zig       # padStart, padEnd\n│       ├── trimming.zig      # trim, trimStart, trimEnd\n│       ├── split.zig         # split\n│       ├── case.zig          # toLowerCase, toUpperCase\n│       ├── regex.zig         # search, match, matchAll, replace, replaceAll\n│       ├── unicode_normalize.zig  # NFC/NFD/NFKC/NFKD normalization\n│       └── utility.zig       # toString, valueOf, localeCompare, normalize\n├── include/\n│   ├── zstring.h            # C header file\n│   └── zstring.hpp          # C++ header file (RAII wrapper)\n├── tests/\n│   ├── spec/                 # ECMAScript spec compliance tests\n│   └── benchmarks/           # Performance benchmarks\n├── examples/                 # Usage examples\n├── C.md                     # Complete C API documentation\n└── CPP.md                   # Complete C++ API documentation\n```\n\n## 🔮 Roadmap\n\n### Phase 1: Core Methods ✅ (Complete - 100%)\n- [x] Character access methods\n- [x] Search methods (literal)\n- [x] Transform methods\n- [x] Padding and trimming\n- [x] Split (literal)\n- [x] Case conversion\n- [x] Utility methods\n- [x] Unicode normalization (NFC/NFD/NFKC/NFKD)\n\n### Phase 2: Regex Integration ✅ (Complete - 100%)\n- [x] Integrate zregexp as dependency\n- [x] Implement search() with regex\n- [x] Implement match() and matchAll()\n- [x] Implement replace() and replaceAll() with regex\n- [x] Comprehensive test coverage for regex methods\n\n### Phase 3: Advanced Features 🔮 (Future)\n- [ ] Full locale support (ICU integration)\n- [ ] Extended Unicode normalization (full UCD coverage beyond Latin-1)\n- [ ] Locale-aware case mapping (Turkish İ/i, etc.)\n\n## 🤝 Contributing\n\nContributions are welcome! This project is actively maintained.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/carlos-sweb/z-string.git\ncd z-string\nzig build test\n```\n\n### Guidelines\n\n- Follow ECMAScript 262 specification exactly\n- Maintain UTF-16 indexing compatibility\n- Include comprehensive tests for all changes\n- Document public APIs with examples\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🔗 Related Projects\n\n- **libzregexp** (in development) - Zig regex engine for ECMAScript compatibility\n- **Zig Standard Library** - UTF-8/UTF-16 utilities\n\n## 📊 Project Status\n\n**Current Version:** 0.3.0 (Development)\n\n**Compatibility:**\n- ✅ 33/33 methods implemented (100%)\n- ✅ 28/28 non-regex methods (100%)\n- ✅ 5/5 regex methods (100%)\n- ✅ Full Unicode normalization for common Latin characters\n\n**Production Ready:** Complete - all ECMAScript String API features available\n\n✅ **Project Status: ACTIVE**\n\nAll methods have been successfully implemented! The project now provides **complete ECMAScript 262 String API compatibility** with 100% of methods implemented, including full Unicode normalization (NFC/NFD/NFKC/NFKD) for common Latin characters.\n\n**Dependency Architecture:**\n- z-string depends on zregexp (one-way dependency)\n- No circular dependencies\n- Clean separation of concerns\n\n## 🙏 Acknowledgments\n\n- ECMAScript 262 specification\n- Zig community\n- All contributors\n\n---\n\n**Note:** For questions or discussions about the project architecture, please open an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlos-sweb%2Fz-string","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlos-sweb%2Fz-string","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlos-sweb%2Fz-string/lists"}