{"id":17651527,"url":"https://github.com/jsteemann/atoi","last_synced_at":"2025-05-07T08:03:22.154Z","repository":{"id":147863274,"uuid":"114578053","full_name":"jsteemann/atoi","owner":"jsteemann","description":"Fast string to integer conversion","archived":false,"fork":false,"pushed_at":"2018-01-11T18:49:43.000Z","size":1090,"stargazers_count":15,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-07T08:03:12.241Z","etag":null,"topics":["atoi","cpp","integer-conversion","library","performance"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jsteemann.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}},"created_at":"2017-12-18T00:04:02.000Z","updated_at":"2025-01-24T20:25:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"f8e726ff-6801-44af-90d5-62655d1bad9d","html_url":"https://github.com/jsteemann/atoi","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsteemann%2Fatoi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsteemann%2Fatoi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsteemann%2Fatoi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsteemann%2Fatoi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsteemann","download_url":"https://codeload.github.com/jsteemann/atoi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252839287,"owners_count":21812086,"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":["atoi","cpp","integer-conversion","library","performance"],"created_at":"2024-10-23T11:42:29.856Z","updated_at":"2025-05-07T08:03:22.146Z","avatar_url":"https://github.com/jsteemann.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"String to integer conversion library\n------------------------------------\n\nThis is a header-only library for converting a string containing a\nbase-10 number into an integer value of a configurable type T.  \n\nThe library offers functions to parse a string into an integer with\nvalidation of the input string or without validation. It is up to the\nembedder to pick the appropriate function.\n\nIf the validating functions are used, the input string is considered \nvalid only if it consists of the digits '0' to '9'. An optional '+' \nor '-' sign is allowed at the very beginning of the input string too. \nIf any other character is found, the input is considered invalid.\nThe input string does not need to be null-terminated.\n\nIf the parsed number value would be less or greater than what the \nnumber type T can store without truncation, the input is considered\ninvalid and parsing is stopped.\n\nThe non-validating functions do not validate the input string for\nvalidity nor do they check for overflow or underflow of the result\nvalue.\n\nThe library makes a few assumptions about the input in order to provide \ngood performance:\n\n* all input is treated as base-10 numbers - no support for hexadecimal\n  or octal numbers nor for floating point values\n* the library functions are optimized for valid input, i.e. strings that \n  contain only the digits '0' to '9' (with an optional '+' or '-' sign in \n  front). This is also true for the validating functions\n* the library will not handle leading whitespace in the input string. \n  input strings with leading or trailing whitespace are simply considered \n  invalid. The same is true for input strings containing non-integer\n  numbers\n* the library functions will not modify `errno` in any way, nor will they\n  throw any exceptions\n* the library functions will not allocate any memory on the heap\n\nIn contrast to other common string-to-integer functions, the functions\nof this library do not require null-terminated input strings. An input\nstring is delimited simply by a start pointer (`char const* p`) and an end \npointer (`char const* e`) into its data. All library functions guarantee\nto only read memory between `p` (inclusive) and `e` (exclusive).\n\nUse cases\n---------\n\nThis library's string-to-integer conversion functionality is not as flexible \nas the one provided by other string-to-integer functions, e.g. `std::stoull`\nfrom the standard library or `std::strtoull`.\n\nThis library sacrifices some of the generality for performance. It is also \noptimized for valid input strings, and provides special functions that do not \nvalidate the input at all. Embedders can use these functions when they know\nthe input strings are valid and will not overflow the target datatype.\n\nExample usage\n-------------\n\n```cpp\n#include \"jsteemann/atoi.h\"\n#include \u003ciostream\u003e\n\n// the string to be parsed\nstd::string value(\"12345678901234\");\n\nbool valid;\nauto result = jsteemann::atoi\u003cuint64_t\u003e(value.data(), value.data() + value.size(), valid);\n\nif (valid) {\n  // parsing succeeded!\n  std::cout \u003c\u003c \"successfully parsed '\" \u003c\u003c value \u003c\u003c \"' into number \" \u003c\u003c result \u003c\u003c std::endl;\n} else {\n  // parsing failed!\n  std::cout \u003c\u003c \"failed to parse '\" \u003c\u003c value \u003c\u003c \"' into a number!\" \u003c\u003c std::endl;\n}\n```\n\nThe library contains the following validating functions:\n```cpp\n// function to convert the string value between p \n// (inclusive) and e (exclusive) into a number value of type T\n//\n// the input string will always be interpreted as a base-10 number.\n// expects the input string to contain only the digits '0' to '9'. an\n// optional '+' or '-' sign is allowed too. \n// if any other character is found, the output parameter \"valid\" will \n// be set to false. if the parsed value is less or greater than what \n// type T can store without truncation, \"valid\" will also be set to \n// false. In this case the returned result should not be used.\n// this function will not modify errno.\ntemplate\u003ctypename T\u003e\nstatic inline T atoi(char const* p, char const* e, bool\u0026 valid) noexcept;\n\n// low-level worker function to convert the string value between p \n// (inclusive) and e (exclusive) into a positive number value of type T\n//\n// the input string will always be interpreted as a base-10 number.\n// expects the input string to contain only the digits '0' to '9'. \n// if any other character is found, the output parameter \"valid\" will \n// be set to false. if the parsed value is greater than what type T can\n// store without truncation, \"valid\" will also be set to false. In this\n// case the returned result should not be used.\n// this function will not modify errno.\ntemplate\u003ctypename T\u003e\nstatic inline T atoi_positive(char const* p, char const* e, bool\u0026 valid) noexcept;\n```\n\nThe library contains the following non-validating functions:\n```cpp\n// function to convert the string value between p \n// (inclusive) and e (exclusive) into a number value of type T, without\n// validation of the input string - use this only for trusted input!\n//\n// the input string will always be interpreted as a base-10 number.\n// expects the input string to contain only the digits '0' to '9'. an\n// optional '+' or '-' sign is allowed too. \n// there is no validation of the input string, and overflow or underflow\n// of the result value will not be detected.\n// this function will not modify errno.\ntemplate\u003ctypename T\u003e\ninline T atoi_unchecked(char const* p, char const* e) noexcept;\n\n// low-level worker function to convert the string value between p \n// (inclusive) and e (exclusive) into a positive number value of type T,\n// without validation of the input string - use this only for trusted input!\n//\n// the input string will always be interpreted as a base-10 number.\n// expects the input string to contain only the digits '0' to '9'. \n// there is no validation of the input string, and overflow or underflow\n// of the result value will not be detected.\n// this function will not modify errno.\ntemplate\u003ctypename T\u003e\ninline T atoi_positive_unchecked(char const* p, char const* e) noexcept;\n```\n\nBenchmark\n---------\n\nTo compare the performance of this library and the standard library's\n`std::stoull` and `std::strtoull` functions, there is a benchmark executable\nincluded.\n\nIt can be built and run as follows:\n```bash\nmkdir -p build\n# be sure to build in Release mode here for compiler optimizations\n(cd build \u0026\u0026 cmake -DCMAKE_BUILD_TYPE=Release ..)\nbuild/benchmark/bench\n```\n\nBenchmark results from local laptop (Linux x86-64):\n```\n500000000 iterations of std::stoull, string '7' took 4792 ms\n500000000 iterations of std::strtoull, string '7' took 4482 ms\n500000000 iterations of jsteemann::atoi, string '7' took 1027 ms\n500000000 iterations of jsteemann::atoi_positive, string '7' took 870 ms\n500000000 iterations of jsteemann::atoi_positive_unchecked, string '7' took 873 ms\n\n500000000 iterations of std::stoull, string '874' took 6495 ms\n500000000 iterations of std::strtoull, string '874' took 6241 ms\n500000000 iterations of jsteemann::atoi, string '874' took 2268 ms\n500000000 iterations of jsteemann::atoi_positive, string '874' took 2222 ms\n500000000 iterations of jsteemann::atoi_positive_unchecked, string '874' took 1092 ms\n\n500000000 iterations of std::stoull, string '123456' took 9172 ms\n500000000 iterations of std::strtoull, string '123456' took 8887 ms\n500000000 iterations of jsteemann::atoi, string '123456' took 3945 ms\n500000000 iterations of jsteemann::atoi_positive, string '123456' took 3883 ms\n500000000 iterations of jsteemann::atoi_positive_unchecked, string '123456' took 1956 ms\n\n500000000 iterations of std::stoull, string '12345654666646' took 16413 ms\n500000000 iterations of std::strtoull, string '12345654666646' took 16026 ms\n500000000 iterations of jsteemann::atoi, string '12345654666646' took 9061 ms\n500000000 iterations of jsteemann::atoi_positive, string '12345654666646' took 8527 ms\n500000000 iterations of jsteemann::atoi_positive_unchecked, string '12345654666646' took 4154 ms\n\n500000000 iterations of std::stoull, string '16323949897939569634' took 21772 ms\n500000000 iterations of std::strtoull, string '16323949897939569634' took 21537 ms\n500000000 iterations of jsteemann::atoi, string '16323949897939569634' took 16677 ms\n500000000 iterations of jsteemann::atoi_positive, string '16323949897939569634' took 15597 ms\n500000000 iterations of jsteemann::atoi_positive_unchecked, string '16323949897939569634' took 6203 ms\n```\n\nTests\n-----\n\nTo run the library's tests locally, execute the following commands:\n\n```bash\nmkdir -p build\n(cd build \u0026\u0026 cmake ..)\nbuild/tests/tests\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsteemann%2Fatoi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsteemann%2Fatoi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsteemann%2Fatoi/lists"}