{"id":22310404,"url":"https://github.com/jk-jeon/dragonbox","last_synced_at":"2025-10-21T03:58:41.843Z","repository":{"id":37067600,"uuid":"289487913","full_name":"jk-jeon/dragonbox","owner":"jk-jeon","description":"Reference implementation of Dragonbox in C++","archived":false,"fork":false,"pushed_at":"2025-10-03T21:31:58.000Z","size":25156,"stargazers_count":768,"open_issues_count":9,"forks_count":50,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-10-20T04:24:02.791Z","etag":null,"topics":[],"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/jk-jeon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-Apache2-LLVM","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":"2020-08-22T12:57:02.000Z","updated_at":"2025-10-19T12:51:59.000Z","dependencies_parsed_at":"2023-02-08T02:18:20.179Z","dependency_job_id":"aabf6b10-641f-458b-9a98-8731ed448db9","html_url":"https://github.com/jk-jeon/dragonbox","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/jk-jeon/dragonbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jk-jeon%2Fdragonbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jk-jeon%2Fdragonbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jk-jeon%2Fdragonbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jk-jeon%2Fdragonbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jk-jeon","download_url":"https://codeload.github.com/jk-jeon/dragonbox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jk-jeon%2Fdragonbox/sbom","scorecard":{"id":522313,"data":{"date":"2025-08-11","repo":{"name":"github.com/jk-jeon/dragonbox","commit":"6c7c925b571d54486b9ffae8d9d18a822801cbda"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.5,"checks":[{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Code-Review","score":1,"reason":"Found 2/16 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Warn: no topLevel permission defined: .github/workflows/cross.yml:1","Warn: no topLevel permission defined: .github/workflows/os.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:48: update your workflow using https://app.stepsecurity.io/secureworkflow/jk-jeon/dragonbox/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:50: update your workflow using https://app.stepsecurity.io/secureworkflow/jk-jeon/dragonbox/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:70: update your workflow using https://app.stepsecurity.io/secureworkflow/jk-jeon/dragonbox/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:72: update your workflow using https://app.stepsecurity.io/secureworkflow/jk-jeon/dragonbox/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/jk-jeon/dragonbox/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/jk-jeon/dragonbox/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/cross.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/jk-jeon/dragonbox/cross.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/cross.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/jk-jeon/dragonbox/cross.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/os.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/jk-jeon/dragonbox/os.yml/master?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/cross.yml:36","Warn: pipCommand not pinned by hash: .github/workflows/cross.yml:37","Info:   0 out of   6 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   3 third-party GitHubAction dependencies pinned","Info:   0 out of   2 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE-Apache2-LLVM:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE-Apache2-LLVM:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 16 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-20T03:21:54.160Z","repository_id":37067600,"created_at":"2025-08-20T03:21:54.160Z","updated_at":"2025-08-20T03:21:54.160Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280200870,"owners_count":26289477,"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","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2024-12-03T21:01:24.082Z","updated_at":"2025-10-21T03:58:41.824Z","avatar_url":"https://github.com/jk-jeon.png","language":"C++","funding_links":[],"categories":["Miscellaneous","C++"],"sub_categories":[],"readme":"# Dragonbox\nThis library is a reference implementation of [Dragonbox](other_files/Dragonbox.pdf) in C++.\n\nDragonbox is a float-to-string conversion algorithm based on a beautiful algorithm [Schubfach](https://drive.google.com/file/d/1IEeATSVnEE6TkrHlCYNY2GjaraBjOT4f/edit), developed by Raffaello Giulietti in 2017-2018. Dragonbox is further inspired by [Grisu](https://www.cs.tufts.edu/~nr/cs257/archive/florian-loitsch/printf.pdf) and [Grisu-Exact](https://github.com/jk-jeon/Grisu-Exact).\n\n# Introduction\nDragonbox generates a pair of integers from a floating-point number: the decimal significand and the decimal exponent of the input floating-point number. These integers can then be used for string generation of decimal representation of the input floating-point number, the procedure commonly called ````ftoa```` or ````dtoa````.\n\nThe algorithm guarantees three things:\n\n1) It has the roundtrip guarantee; that is, a correct parser interprets the generated output string as the original input floating-point number. (See [here](https://github.com/jk-jeon/dragonbox/blob/master/README.md#precise-meaning-of-roundtrip-gurantee) for some explanation on this.)\n\n2) The output is of the shortest length; that is, no other output strings that are interpreted as the input number can contain less number of significand digits than the output of Dragonbox.\n\n3) The output is correctly rounded: the number generated by Dragonbox is the closest to the actual value of the input number among possible outputs of minimum number of digits.\n\n# About the Name \"Dragonbox\"\nThe core idea of Schubfach, which Dragonbox is based on, is a continuous analogue of discrete [pigeonhole principle](https://en.wikipedia.org/wiki/Pigeonhole_principle). The name *Schubfach* is coming from the German name of the pigeonhole principle, *Schubfachprinzip*, meaning \"drawer principle\". Since another name of the pigeonhole principle is *Dirichlet's box principle*, I decided to call my algorithm \"Dragonbox\" to honor its origins: Schubfach (box) and Grisu (dragon).\n\n# How to Use\nAlthough Dragonbox is intended for float-to-string conversion routines, the actual string generation is not officially a part of the algorithm. Dragonbox just outputs two integers (the decimal significand/exponent) that can be consumed by a string generation procedure. The header file [`include/dragonbox/dragonbox.h`](include/dragonbox/dragonbox.h) includes everything needed for this (it is header-only). Nevertheless, a string generation procedure is included in the library. There are two additional files needed for that: [`include/dragonbox/dragonbox_to_chars.h`](include/dragonbox/dragonbox_to_chars.h) and [`source/dragonbox_to_chars.cpp`](source/dragonbox_to_chars.cpp). Since there are only three files, it should be not difficult to set up this library manually if you want, but you can also use it via CMake as explained below. If you are not familiar with CMake, I recommend you to have a look at [this](https://cliutils.gitlab.io/modern-cmake/) wonderful introduction.\n\n## Installing Dragonbox\nThe following will create platform-specific build files on your directory:\n```\ngit clone https://github.com/jk-jeon/dragonbox\ncd dragonbox\nmkdir build\ncd build\ncmake ..\n```\nIf you only want [`dragonbox.h`](include/dragonbox/dragonbox.h) but not [`dragonbox_to_chars.h`](include/dragonbox/dragonbox_to_chars.h)/[`.cpp`](source/dragonbox_to_chars.cpp), you can do the following to install [`dragonbox.h`](include/dragonbox/dragonbox.h) into your system:\n```\ncmake .. -DDRAGONBOX_INSTALL_TO_CHARS=OFF\ncmake --install .\n```\nIf you want the string generation part as well, build the generated files using platform-specific build tools (`make` or Visual Studio for example) and then perform\n```\ncmake --install .\n```\non the `build` directory.\n\n## Including Dragonbox into CMake project\nThe easiest way to include Dragonbox in a CMake project is to do the following:\n```cmake\ninclude(FetchContent)\nFetchContent_Declare(\n        dragonbox\n        GIT_REPOSITORY https://github.com/jk-jeon/dragonbox\n)\nFetchContent_MakeAvailable(dragonbox)\ntarget_link_libraries(my_target dragonbox::dragonbox) # or dragonbox::dragonbox_to_chars\n```\nOr, if you already have installed Dragonbox in your system, you can include it with:\n```cmake\nfind_package(dragonbox)\ntarget_link_libraries(my_target dragonbox::dragonbox) # or dragonbox::dragonbox_to_chars\n```\n\n# Language Standard\nThe library requires C++11 or higher. Since C++20, every function provided is `constexpr`.\n\n# Usage Examples\n(Simple string generation from `float/double`)\n```cpp\n#include \"dragonbox/dragonbox_to_chars.h\"\nconstexpr int buffer_length = 1 + // for '\\0'\n  jkj::dragonbox::max_output_string_length\u003cjkj::dragonbox::ieee754_binary64\u003e;\ndouble x = 1.234;  // Also works for float\nchar buffer[buffer_length];\n\n// Null-terminate the buffer and return the pointer to the null character\n// Hence, the length of the string is (end_ptr - buffer)\n// buffer is now { '1', '.', '2', '3', '4', 'E', '0', '\\0', (garbages) }\nchar* end_ptr = jkj::dragonbox::to_chars(x, buffer);\n\n// Does not null-terminate the buffer; returns the next-to-end pointer\n// buffer is now { '1', '.', '2', '3', '4', 'E', '0', (garbages) }\n// you can wrap the buffer with things like std::string_view\nend_ptr = jkj::dragonbox::to_chars_n(x, buffer);\n```\n\n(Direct use of `jkj::dragonbox::to_decimal`)\n```cpp\n#include \"dragonbox/dragonbox.h\"\ndouble x = 1.234;   // Also works for float\n\n// Here, x should be a nonzero finite number!\n// The return value v is a struct with three members:\n// significand : decimal significand (1234 in this case);\n//               it is of type std::uint64_t for double, std::uint32_t for float\n//    exponent : decimal exponent (-3 in this case); it is of type int\n// is_negative : as the name suggests; it is of type bool\nauto v = jkj::dragonbox::to_decimal(x);\n```\n\nBy default, `jkj::dragonbox::to_decimal` returns a struct with three members (`significand`, `exponent`, and `is_negative`). But the return type and the return value can change if you specify policy parameters. See [below](https://github.com/jk-jeon/dragonbox#policies).\n\n***Important.*** `jkj::dragonbox::to_decimal` is designed to ***work only with finite nonzero*** inputs. The behavior of it when given with infinities/NaN's/`+0`/`-0` is undefined. `jkj::dragonbox::to_chars` and `jkj::dragonbox::to_chars_n` work fine for any inputs.\n\n# To people wanting to port the algorithm\nThose who want to port the algorithm into other languages or re-implement it from scratch are recommended to look at the [simpler implementation](https://github.com/jk-jeon/dragonbox/tree/master/subproject/simple) first rather than the main implementation, since the main implementation is riddled with template indirections obscuring the core logic of the algorithm. The simpler implementation offers less flexibility and somewhat slower performance, but is much more straightforward so it should be easier to understand.\n\n# Policies\nDragonbox provides several policies that the user can select. Most of the time the default policies will be sufficient, but for some situation this customizability might be useful. There are currently five different kinds of policies that you can specify: sign policy, trailing zero policy, decimal-to-binary (parsing) rounding policy, binary-to-decimal (formatting) rounding policy, and cache policy. Those policies live in the namespace `jkj::dragonbox::policy`. You can provide the policies as additional parameters to `jkj::dragonbox::to_decimal` or `jkj::dragonbox::to_chars` or `jkj::dragonbox::to_chars_n`. Here is an example usage:\n```cpp\n#include \"dragonbox/dragonbox.h\"\nauto v = jkj::dragonbox::to_decimal(x,\n    jkj::dragonbox::policy::sign::ignore,\n    jkj::dragonbox::policy::cache::compact);\n```\nIn this example, the `ignore` sign policy and the `compact` cache policy are specified. The return value will not include the member `is_negative`, and `jkj::dragonbox::to_decimal` will internally use the compressed cache for the computation, rather than the full cache. There is no particular order for policy parameters; you can give them in any order. Default policies will be chosen if you do not explicitly specify any. In the above example, for instance, `nearest_to_even` decimal-to-binary rounding mode policy is chosen, which is the default decimal-to-binary rounding mode policy. If you provide two or more policies of the same kind, or if you provide an invalid policy parameter, then the compliation will fail.\n\nPolicy parameters (e.g., `jkj::dragonbox::policy::sign::ignore` in the above example) are of different types, so different combinations of policies generally result in separate template instantiations, which might cause binary bloat. (However, it is only the combination that matters; giving the same parameter combination in a different order will usually not generate a separate binary.)\n\n## Sign policy\nDetermines whether or not `jkj::dragonbox::to_decimal` will extract and return the sign of the input parameter.\n\n- `jkj::dragonbox::policy::sign::ignore`: There is no `is_negative` member in the returned struct and the sign of the input is not returned. A string generation routine might anyway need to deal with the sign by itself, so often this member will not be needed. In that case, omitting `is_negative` member can reduce some overhead. `jkj::dragonbox::to_chars` and `jkj::dragonbox::to_chars_n` use this policy internally. In the implementation of `jkj::dragonbox::to_decimal`, the sign of the input is relevant only for deciding the rounding interval under certain rounding mode policies. Under the default rounding mode policies, the sign is completely ignored.\n- `jkj::dragonbox::policy::sign::return_sign`: **This is the default policy.** The sign of the input will be written in the `is_negative` member of the returned struct.\n\nYou cannot specify sign policy to `jkj::dragonbox::to_chars`/`jkj::dragonbox::to_chars_n`.\n\n## Trailing zero policy\nDetermines what `jkj::dragonbox::to_decimal` will do with possible trailing decimal zeros.\n\n- `jkj::dragonbox::policy::trailing_zero::ignore`: Do not care about trailing zeros; the output significand may contain trailing zeros. Since trailing zero removal is a relatively heavy operation involving lots of divisions, and a string generation routine will need to perform divisions anyway, it would be possible to get a better overall performance by omitting trailing zero removal from `jkj::dragonbox::to_decimal` and taking care of that in other places.\n- `jkj::dragonbox::policy::trailing_zero::remove`: **This is the default policy.** Remove all trailing zeros in the output. `jkj::dragonbox::to_chars` and `jkj::dragonbox::to_chars_n` use this policy internally for IEEE-754 binary32 format (aka `float`).\n- `jkj::dragonbox::policy::trailing_zero::report`: The output significand may contain trailing zeros, but such possibility will be reported in the additional member `may_have_trailing_zeros` of the returned struct. This member will be set to `true` if there might be trailing zeros, and it will be set to `false` if there should be no trailing zero. By how the algorithm works, it is guaranteed that whenever there might be trailing zeros, the maximum number of trailing zeros is 7 for binary32 and 15 for binary64.\n\nYou cannot specify trailing zero policy to `jkj::dragonbox::to_chars`/`jkj::dragonbox::to_chars_n`.\n\n## Decimal-to-binary rounding policy\nDragonbox provides a roundtrip guarantee. This means that if we convert the output of Dragonbox back to IEEE-754 binary floating-point format, the result should be equal to the original input to Dragonbox. However, converting the decimal output of Dragonbox back into binary floating-point number requires a rounding, so in order to ensure the roundtrip guarantee, Dragonbox must assume which kind of rounding will be performed for *the inverse, decimal-to-binary conversion*.\n\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_to_even`: **This is the default policy.** Use *round-to-nearest, tie-to-even* rounding mode.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_to_odd`: Use *round-to-nearest, tie-to-odd* rounding mode.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_toward_plus_infinity`: Use *round-to-nearest, tie-toward-plus-infinity* rounding mode.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_toward_minus_infinity`: Use *round-to-nearest, tie-toward-minus-infinity* rounding mode.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_toward_zero`: Use *round-to-nearest, tie-toward-zero* rounding mode. This will produce the fastest code among all *round-to-nearest* rounding modes.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_away_from_zero`: Use *round-to-nearest, tie-away-from-zero* rounding mode.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_to_even_static_boundary`: Use *round-to-nearest, tie-to-even* rounding mode, but there will be completely independent code paths for even inputs and odd inputs. This will produce a bigger binary, but might run faster than `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_to_even` for some situation.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_to_odd_static_boundary`: Use *round-to-nearest, tie-to-odd* rounding mode, but there will be completely independent code paths for even inputs and odd inputs. This will produce a bigger binary, but might run faster than `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_to_odd` for some situation.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_toward_plus_infinity_static_boundary`: Use *round-to-nearest, tie-toward-plus-infinity* rounding mode, but there will be completely independent code paths for positive inputs and negative inputs. This will produce a bigger binary, but might run faster than `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_toward_plus_infinity` for some situation.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_toward_minus_infinity_static_boundary`: Use *round-to-nearest, tie-toward-plus-infinity* rounding mode, but there will be completely independent code paths for positive inputs and negative inputs. This will produce a bigger binary, but might run faster than `jkj::dragonbox::policy::decimal_to_binary_rounding::nearest_toward_minus_infinity` for some situation.\n\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::toward_plus_infinity`: Use *round-toward-plus-infinity* rounding mode.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::toward_minus_infinity`: Use *round-toward-minus-infinity* rounding mode.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::toward_zero`: Use *round-toward-zero* rounding mode.\n- `jkj::dragonbox::policy::decimal_to_binary_rounding::away_from_zero`: Use *away-from-zero* rounding mode.\n\nAll of these policies can be specified also to `jkj::dragonbox::to_chars`/`jkj::dragonbox::to_chars_n`.\n\n## Binary-to-decimal rounding policy\nDetermines what `jkj::dragonbox::to_decimal` will do when rounding tie occurs while obtaining the decimal significand. This policy will be completely ignored if the specified binary-to-decimal rounding policy is not one of the round-to-nearest policies (because for other policies rounding tie simply doesn't exist).\n\n- `jkj::dragonbox::policy::binary_to_decimal_rounding::do_not_care`: Do not care about correct rounding at all and just find any shortest output with the correct roundtrip. It will produce a faster code, but the performance difference will not be big.\n- `jkj::dragonbox::policy::binary_to_decimal_rounding::to_even`: **This is the default policy.** Choose the even number when rounding tie occurs.\n- `jkj::dragonbox::policy::binary_to_decimal_rounding::to_odd`: Choose the odd number when rounding tie occurs.\n- `jkj::dragonbox::policy::binary_to_decimal_rounding::away_from_zero`: Choose the number with the bigger absolute value when rounding tie occurs.\n- `jkj::dragonbox::policy::binary_to_decimal_rounding::toward_zero`: Choose the number with the smaller absolute value when rounding tie occurs.\n\nAll of these policies can be specified also to `jkj::dragonbox::to_chars`/`jkj::dragonbox::to_chars_n`.\n\n## Cache policy\nChoose between the full cache table and the compressed one. Using the compressed cache will result in about 20% slower code, but it can significantly reduce the amount of required static data. It currently has no effect for binary32 (`float`) inputs. For binary64 (`double`) inputs, `jkj::dragonbox::cache_policy::full` will cause `jkj::dragonbox::to_decimal` to use `619*16 = 9904` bytes of static data table, while the corresponding amount for `jkj::dragonbox::cache_policy::compact` is `23*16 + 27*8 = 584` bytes.\n\n- `jkj::dragonbox::policy::cache::full`: **This is the default policy.** Use the full table.\n- `jkj::dragonbox::policy::cache::compact`: Use the compressed table.\n\nAll of these policies can be specified also to `jkj::dragonbox::to_chars`/`jkj::dragonbox::to_chars_n`.\n\n\n# Performance\nIn my machine (Intel Core i7-7700HQ 2.80GHz, Windows 10), it defeats or is on par with other contemporary algorithms including Grisu-Exact, Ryu, and Schubfach.\n\nThe following benchmark result (performed on 03/30/2024) is obtained using Milo's dtoa benchmark framework ([https://github.com/miloyip/dtoa-benchmark](https://github.com/miloyip/dtoa-benchmark)). The complete source code for the benchmark below is available [here](https://github.com/jk-jeon/dtoa-benchmark).\n\n![corei7_7700hq@2.80_win64_vc2019_randomdigit_time](other_files/unknown_win64_vc2019_randomdigit_time.png)\n![corei7_7700hq@2.80_win64_vc2019_randomdigit_time](other_files/unknown_win64_vc2019_randomdigit_timedigit.png)\n\nNote 1: `dragonbox` is the performance of Dragonbox with the full cache table, and `dragonbox_comp` is the performance of Dragonbox with the compact cache table.\n\nNote 2: [`fmt`](https://github.com/fmtlib/fmt) internally uses Dragonbox with an implementation almost identical to that in this repository.\n\nThere is also a benchmark done by myself (also performed on 03/30/2024):\n\n(top: benchmark for ````float```` data, bottom: benchmark for ````double```` data; solid lines are the averages, dashed lines are the medians, and the shaded regions show 30%, 50%, and 70% percentiles):\n\n(Clang)\n![digits_benchmark_binary32](subproject/benchmark/results/digits_benchmark_binary32_clang.png)\n![digits_benchmark_binary64](subproject/benchmark/results/digits_benchmark_binary64_clang.png)\n\n(MSVC)\n![digits_benchmark_binary32](subproject/benchmark/results/digits_benchmark_binary32_msvc.png)\n![digits_benchmark_binary64](subproject/benchmark/results/digits_benchmark_binary64_msvc.png)\n\nHere is another performance plot with uniformly randomly generated ````float````(top) or ````double````(bottom) data:\n\n(Clang)\n![uniform_benchmark_binary32](subproject/benchmark/results/uniform_benchmark_binary32_clang.png)\n![uniform_benchmark_binary64](subproject/benchmark/results/uniform_benchmark_binary64_clang.png)\n\n(MSVC)\n![uniform_benchmark_binary32](subproject/benchmark/results/uniform_benchmark_binary32_msvc.png)\n![uniform_benchmark_binary64](subproject/benchmark/results/uniform_benchmark_binary64_msvc.png)\n\n(Note: the comparison with Schubfach is not completely fair, since the implementation I benchmarked against uses a digit generation procedure with a different set of constraints. More fair comparison is available in [this repository](https://github.com/abolz/Drachennest).)\n\n# Comprehensive Explanation of the Algorithm\nPlease see [this](other_files/Dragonbox.pdf) paper.\n\n# How to Run Tests, Benchmark, and Others\nThere are four subprojects contained in this repository:\n1. [`common`](subproject/common): The subproject that other subprojects depend on.\n2. [`benchmark`](subproject/benchmark): Runs benchmark.\n3. [`test`](subproject/test): Runs tests.\n4. [`meta`](subproject/meta): Generates static data that the main library uses.\n\n## Build each subproject independently\nAll subprojects including tests and benchmark are standalone, which means that you can build and run each of them independently. For example, you can do the following to run tests:\n```\ngit clone https://github.com/jk-jeon/dragonbox\ncd dragonbox\nmkdir -p build/subproject/test\ncd build/subproject/test\ncmake ../../../subproject/test\ncmake --build .\nctest .\n```\n(You might need to pass the configuration option to `cmake` and `ctest` if you use multi-configuration generators like Visual Studio.)\n\n## Build all subprojects from the root directory\nIt is also possible to build all subprojects from the root directory by passing the option `-DDRAGONBOX_ENABLE_SUBPROJECT=On` to `cmake`:\n```\ngit clone https://github.com/jk-jeon/dragonbox\ncd dragonbox\nmkdir build\ncd build\ncmake .. -DDRAGONBOX_ENABLE_SUBPROJECT=On\ncmake --build .\n```\n\n## Notes on working directory\nSome executable files require the correct working directory to be set. For example, the executable for [`benchmark`](subproject/benchmark) runs some MATLAB scripts provided in [`subproject/benchmark/matlab`](subproject/benchmark/matlab) directory, which will fail to execute if the working directory is not set to [`subproject/benchmark`](subproject/benchmark). If you use the provided `CMakeLists.txt` files to generate a Visual Studio solution, the debugger's working directory is automatically set to the corresponding source directory. For example, the working directory is set to [`subproject/benchmark`](subproject/benchmark) for the benchmark subproject. However, other generators of cmake are not able to set the debugger's working directory, so in that case you need to manually set the correct working directory when running the executables in order to make them work correctly.\n\n\n# Notes\n\n## Correctness of the algorithm\n\nThe [paper](other_files/Dragonbox.pdf) provides a mathematical proof of the correctness of the algorithm, with the aid of verification programs in [`test`](test) and [`meta`](meta) directories. In addition to that, I did a fair amount of uniformly random tests against Ryu (which is extremely heavily tested in its own), and I also ran a joint test of Dragonbox with a binary-to-decimal floating-point conversion routine I developed, and confirmed correct roundtrip for all possible IEEE-754 binary32-encoded floating-point numbers (aka `float`) with the round-to-nearest, tie-to-even rounding mode. Therefore, I am pretty confident about the correctness of both of the algorithms.\n\n## Precise meaning of roundtrip guarantee\n\nThe precise meaning of roundtrip guarantee might be tricky, as it depends on the notion of \"correct parsers\". For example, given that `significand` and `exponent` are the outputs of Dragonbox with respect to an input floating-point number `x` of, say, type `double`, then things like `x == significand * pow(10.0, exponent)` might or might not be the case, because each of the floating-point operations in the expression `significand * pow(10.0, exponent)` can introduce rounding errors that can accumulate to a bigger error. What a correct parser should do is to precisely compute the floating-point number from the given expression according to the assumed rounding rule, and the result must be \"correctly rounded\" in the sense that only the minimum possible rounding error is allowed. Implementing a correct parser is indeed a very nontrivial job, so you may need additional libraries (like [Ryu](https://github.com/ulfjack/ryu) or [double-conversion](https://github.com/google/double-conversion)) if you want to check this roundtrip guarantee by yourself.\n\n# License\nAll code, except for those belong to third-party libraries (code in [`subproject/3rdparty`](subproject/3rdparty)), is licensed under either of\n\n * Apache License Version 2.0 with LLVM Exceptions ([LICENSE-Apache2-LLVM](LICENSE-Apache2-LLVM) or https://llvm.org/foundation/relicensing/LICENSE.txt) or\n * Boost Software License Version 1.0 ([LICENSE-Boost](LICENSE-Boost) or https://www.boost.org/LICENSE_1_0.txt).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjk-jeon%2Fdragonbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjk-jeon%2Fdragonbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjk-jeon%2Fdragonbox/lists"}