{"id":24746666,"url":"https://github.com/samuelmarks/c-str-span","last_synced_at":"2025-03-23T01:23:41.424Z","repository":{"id":150265200,"uuid":"484148977","full_name":"SamuelMarks/c-str-span","owner":"SamuelMarks","description":"UTF-8 replacement for C strings, supporting zero-copy use-cases (non-null-terminated).","archived":false,"fork":false,"pushed_at":"2023-06-20T11:58:49.000Z","size":378,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-28T04:32:02.515Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","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/SamuelMarks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-MIT","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}},"created_at":"2022-04-21T17:42:56.000Z","updated_at":"2022-04-21T22:50:49.000Z","dependencies_parsed_at":"2025-01-28T04:30:16.347Z","dependency_job_id":"92ea6d7c-7ee1-4d89-8331-7f44ad338107","html_url":"https://github.com/SamuelMarks/c-str-span","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelMarks%2Fc-str-span","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelMarks%2Fc-str-span/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelMarks%2Fc-str-span/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelMarks%2Fc-str-span/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SamuelMarks","download_url":"https://codeload.github.com/SamuelMarks/c-str-span/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245042148,"owners_count":20551525,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-01-28T04:29:49.774Z","updated_at":"2025-03-23T01:23:41.400Z","avatar_url":"https://github.com/SamuelMarks.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"c-str-span\n==========\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Linux, Windows, macOS](https://github.com/SamuelMarks/c-str-span/actions/workflows/linux-Windows-macOS.yml/badge.svg)](https://github.com/SamuelMarks/c-str-span/actions/workflows/linux-Windows-macOS.yml)\n\nUTF-8 replacement for C strings, supporting zero-copy use-cases (non-null-terminated).\n\nExtracted from https://github.com/Azure/azure-sdk-for-c @ [`ac28b8`](https://github.com/Azure/azure-sdk-for-c/tree/ac28b8af9254798c1e891945e896d2ae2bdf745e) with:\n  - No dependency on other Azure SDK for C functionalities;\n  - C89 (ANSI C) compliance;\n  - CTest integration;\n  - More `const` correctness;\n  - Use `size_t` over `int32_t` for size types;\n  - Implement `az_span_printf`;\n  - Added support for MSVC 2005, Open Watcom (incl. DOS target), MinGW, and Cygwin\n\nDocumentation originally from: https://github.com/Azure/azure-sdk-for-c/tree/main/sdk/docs/core#working-with-spans, now below:\n\n### Working with Spans\n\nAn `az_span` is a small data structure (defined in the [c_str_span.h](c_str_span/c_str_span.h) file) wrapping a byte buffer. Specifically, an `az_span` instance contains:\n\n  - a byte pointer\n  - an integer size\n\nUse this to create SDKs that pass `az_span` instances to functions to ensure that a buffer's address and size are always passed together; this reduces the chance of bugs. And, since we have the size, operations are fast; for example, we never need to call `strlen` to find the length of a string in order to append to it. Furthermore, when your SDK functions write or copy to an `az_span`, those functions ensure that we never write beyond the size of the buffer; this prevents data corruption. And finally, when reading from an `az_span`, we never read past the `az_span`'s size ensuring that we don't process uninitialized data.\n\nSince your SDK functions require `az_span` parameters, customers must know how to create `az_span` instances so that you can call functions in their SDK. Here are some examples.\n\nCreate an empty `az_span`:\n\n```c\naz_span empty_span = az_span_empty(); // size = 0\n```\n\nCreate an `az_span` expression from a byte buffer:\n\n```c\nuint8_t buffer[1024];\nsome_function(AZ_SPAN_FROM_BUFFER(buffer));  // size = 1024\n```\n\nCreate an `az_span` expression from a string (the span does NOT include the 0-terminating byte):\n\n```c\nsome_function(AZ_SPAN_FROM_STR(\"Hello\"));  // size = 5\n```\n\nAs shown above, an `az_span` over a string does not include the 0-terminator. If you need to 0-terminate the string, you can call this function to append a 0 byte (if the span's size is large enough to hold the extra byte):\n\n```c\naz_span az_span_copy_u8(az_span destination, uint8_t byte);\n```\n\nand then call this function to get the address of the 0-terminated string:\n\n```c\nchar* str = (char*) az_span_ptr(span); // str points to a 0-terminated string\n```\n\nOr, you can call this function to copy the string in the `az_span` to your own `char*` buffer; this function will 0-terminate the string in the `char*` buffer:\n\n```c\nvoid az_span_to_str(char* destination, size_t destination_max_size, az_span source);\n```\n\nThere are many functions to manipulate `az_span` instances. You can slice (subset an `az_span`), parse an `az_span` containing a string into a number, format a number as a string into an `az_span`, check if two `az_span` instances are equal or the contents of two `az_span` instances are equal, and more.\n\n### Strings\n\nA string is a span of UTF-8 characters. It's not a zero-terminated string. Defined in [c_str_span.h](c_str_span/c_str_span.h).\n\n```c\naz_span hello_world = AZ_SPAN_FROM_STR(\"Hello world!\");\n```\n\n---\n\n### License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelmarks%2Fc-str-span","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamuelmarks%2Fc-str-span","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelmarks%2Fc-str-span/lists"}