[{"data":1,"prerenderedAt":934},["ShallowReactive",2],{"doc-comparing-floating-point-numbers":3},{"id":4,"title":5,"body":6,"description":81,"extension":925,"meta":926,"navigation":927,"path":928,"seo":929,"slug":930,"source":931,"stem":932,"__hash__":933},"docs\u002Fdocs\u002Fcomparing-floating-point-numbers.md","Comparing floating point numbers with Catch3's compatibility API",{"type":7,"value":8,"toc":915},"minimark",[9,50,54,57,67,72,82,89,110,118,121,205,209,233,317,320,348,421,425,449,456,459,482,494,529,535,541,550,556,586,611,620,623,656,660,666,680,725,730,747,818,832,892,908,911],[10,11,12],"blockquote",{},[13,14,15,19,20,24,25,28,29,32,33,36,37,36,40,43,44,49],"p",{},[16,17,18],"strong",{},"Catch3 compatibility reference:"," This page describes the test-writing API Catch3 shares with Catch2: the macros, such as ",[21,22,23],"code",{},"TEST_CASE"," and ",[21,26,27],{},"REQUIRE",", and the ",[21,30,31],{},"Catch::"," namespace keep Catch2's names. Headers and build names are Catch3's own (",[21,34,35],{},"\u003CProgmasoft\u002FCatch3\u002FTestMacros.hpp>",", ",[21,38,39],{},"find_package(Catch3)",[21,41,42],{},"Catch3::Catch3WithMain","). See ",[45,46,48],"a",{"href":47},"\u002Fdocs\u002Fprogmasoft-catch3\u002F","Catch3 additions"," for Progmasoft APIs.",[51,52,5],"h1",{"id":53},"comparing-floating-point-numbers-with-catch3s-compatibility-api",[13,55,56],{},"If you are not deeply familiar with them, floating point numbers can be\nunintuitive. This also applies to comparing floating point numbers for\n(in)equality.",[13,58,59,60,66],{},"This page assumes that you have some understanding of both FP, and the\nmeaning of different kinds of comparisons, and only goes over what\nfunctionality Catch2 provides to help you with comparing floating point\nnumbers. If you do not have this understanding, we recommend that you first\nstudy up on floating point numbers and their comparisons, e.g. by ",[45,61,65],{"href":62,"rel":63},"https:\u002F\u002Fcodingnest.com\u002Fthe-little-things-comparing-floating-point-numbers\u002F",[64],"nofollow","reading\nthis blog post",".",[68,69,71],"h2",{"id":70},"floating-point-matchers","Floating point matchers",[73,74,79],"pre",{"className":75,"code":77,"language":78},[76],"language-text","#include \u003CProgmasoft\u002FCatch3\u002FMatchers\u002FFloatingPoint.hpp>\n","text",[21,80,77],{"__ignoreMap":81},"",[13,83,84,88],{},[45,85,87],{"href":86},"\u002Fdocs\u002Fmatchers\u002F","Matchers"," are the preferred way of comparing floating\npoint numbers in Catch2. We provide 3 of them:",[90,91,92,99,105],"ul",{},[93,94,95,98],"li",{},[21,96,97],{},"WithinAbs(double target, double margin)",",",[93,100,101,104],{},[21,102,103],{},"WithinRel(FloatingPoint target, FloatingPoint eps)",", and",[93,106,107,66],{},[21,108,109],{},"WithinULP(FloatingPoint target, uint64_t maxUlpDiff)",[10,111,112],{},[13,113,114,117],{},[21,115,116],{},"WithinRel"," matcher was introduced in Catch2 2.10.0",[13,119,120],{},"As with all matchers, you can combine multiple floating point matchers\nin a single assertion. For example, to check that some computation matches\na known good value within 0.1% or is close enough (no different to 5\ndecimal places) to zero, we would write this assertion:",[73,122,126],{"className":123,"code":124,"language":125,"meta":81,"style":81},"language-cpp shiki shiki-themes github-dark","    REQUIRE_THAT( computation(input),\n        Catch::Matchers::WithinRel(expected, 0.001)\n     || Catch::Matchers::WithinAbs(0, 0.000001) );\n","cpp",[21,127,128,147,172],{"__ignoreMap":81},[129,130,133,137,141,144],"span",{"class":131,"line":132},"line",1,[129,134,136],{"class":135},"svObZ","    REQUIRE_THAT",[129,138,140],{"class":139},"s95oV","( ",[129,142,143],{"class":135},"computation",[129,145,146],{"class":139},"(input),\n",[129,148,150,153,156,158,160,162,165,169],{"class":131,"line":149},2,[129,151,152],{"class":135},"        Catch",[129,154,155],{"class":139},"::",[129,157,87],{"class":135},[129,159,155],{"class":139},[129,161,116],{"class":135},[129,163,164],{"class":139},"(expected, ",[129,166,168],{"class":167},"sDLfK","0.001",[129,170,171],{"class":139},")\n",[129,173,175,179,182,184,186,188,191,194,197,199,202],{"class":131,"line":174},3,[129,176,178],{"class":177},"snl16","     ||",[129,180,181],{"class":135}," Catch",[129,183,155],{"class":139},[129,185,87],{"class":135},[129,187,155],{"class":139},[129,189,190],{"class":135},"WithinAbs",[129,192,193],{"class":139},"(",[129,195,196],{"class":167},"0",[129,198,36],{"class":139},[129,200,201],{"class":167},"0.000001",[129,203,204],{"class":139},") );\n",[206,207,190],"h3",{"id":208},"withinabs",[13,210,211,213,214,217,218,221,222,225,226,229,230,232],{},[21,212,190],{}," creates a matcher that accepts floating point numbers whose\ndifference with ",[21,215,216],{},"target"," is less-or-equal to the ",[21,219,220],{},"margin",". Since ",[21,223,224],{},"float","\ncan be converted to ",[21,227,228],{},"double"," without losing precision, only ",[21,231,228],{},"\noverload exists.",[73,234,236],{"className":123,"code":235,"language":125,"meta":81,"style":81},"REQUIRE_THAT(1.0, WithinAbs(1.2, 0.2));\nREQUIRE_THAT(0.f, !WithinAbs(1.0, 0.5));\n\u002F\u002F Notice that infinity == infinity for WithinAbs\nREQUIRE_THAT(INFINITY, WithinAbs(INFINITY, 0));\n",[21,237,238,265,295,301],{"__ignoreMap":81},[129,239,240,243,245,248,250,252,254,257,259,262],{"class":131,"line":132},[129,241,242],{"class":135},"REQUIRE_THAT",[129,244,193],{"class":139},[129,246,247],{"class":167},"1.0",[129,249,36],{"class":139},[129,251,190],{"class":135},[129,253,193],{"class":139},[129,255,256],{"class":167},"1.2",[129,258,36],{"class":139},[129,260,261],{"class":167},"0.2",[129,263,264],{"class":139},"));\n",[129,266,267,269,271,274,277,279,282,284,286,288,290,293],{"class":131,"line":149},[129,268,242],{"class":135},[129,270,193],{"class":139},[129,272,273],{"class":167},"0.",[129,275,276],{"class":177},"f",[129,278,36],{"class":139},[129,280,281],{"class":177},"!",[129,283,190],{"class":135},[129,285,193],{"class":139},[129,287,247],{"class":167},[129,289,36],{"class":139},[129,291,292],{"class":167},"0.5",[129,294,264],{"class":139},[129,296,297],{"class":131,"line":174},[129,298,300],{"class":299},"sAwPA","\u002F\u002F Notice that infinity == infinity for WithinAbs\n",[129,302,304,306,309,311,313,315],{"class":131,"line":303},4,[129,305,242],{"class":135},[129,307,308],{"class":139},"(INFINITY, ",[129,310,190],{"class":135},[129,312,308],{"class":139},[129,314,196],{"class":167},[129,316,264],{"class":139},[206,318,116],{"id":319},"withinrel",[13,321,322,324,325,329,330,332,333,336,337,340,341,36,344,347],{},[21,323,116],{}," creates a matcher that accepts floating point numbers that\nare ",[326,327,328],"em",{},"approximately equal"," to the ",[21,331,216],{}," with a tolerance of ",[21,334,335],{},"eps.","\nSpecifically, it matches if\n",[21,338,339],{},"|arg - target| \u003C= eps * max(|arg|, |target|)"," holds. If you do not\nspecify ",[21,342,343],{},"eps",[21,345,346],{},"std::numeric_limits\u003CFloatingPoint>::epsilon * 100","\nis used as the default.",[73,349,351],{"className":123,"code":350,"language":125,"meta":81,"style":81},"\u002F\u002F Notice that WithinRel comparison is symmetric, unlike Approx's.\nREQUIRE_THAT(1.0, WithinRel(1.1, 0.1));\nREQUIRE_THAT(1.1, WithinRel(1.0, 0.1));\n\u002F\u002F Notice that inifnity == infinity for WithinRel\nREQUIRE_THAT(INFINITY, WithinRel(INFINITY));\n",[21,352,353,358,382,404,409],{"__ignoreMap":81},[129,354,355],{"class":131,"line":132},[129,356,357],{"class":299},"\u002F\u002F Notice that WithinRel comparison is symmetric, unlike Approx's.\n",[129,359,360,362,364,366,368,370,372,375,377,380],{"class":131,"line":149},[129,361,242],{"class":135},[129,363,193],{"class":139},[129,365,247],{"class":167},[129,367,36],{"class":139},[129,369,116],{"class":135},[129,371,193],{"class":139},[129,373,374],{"class":167},"1.1",[129,376,36],{"class":139},[129,378,379],{"class":167},"0.1",[129,381,264],{"class":139},[129,383,384,386,388,390,392,394,396,398,400,402],{"class":131,"line":174},[129,385,242],{"class":135},[129,387,193],{"class":139},[129,389,374],{"class":167},[129,391,36],{"class":139},[129,393,116],{"class":135},[129,395,193],{"class":139},[129,397,247],{"class":167},[129,399,36],{"class":139},[129,401,379],{"class":167},[129,403,264],{"class":139},[129,405,406],{"class":131,"line":303},[129,407,408],{"class":299},"\u002F\u002F Notice that inifnity == infinity for WithinRel\n",[129,410,412,414,416,418],{"class":131,"line":411},5,[129,413,242],{"class":135},[129,415,308],{"class":139},[129,417,116],{"class":135},[129,419,420],{"class":139},"(INFINITY));\n",[206,422,424],{"id":423},"withinulp","WithinULP",[13,426,427,429,430,433,438,439,441,442,445,446,448],{},[21,428,424],{}," creates a matcher that accepts floating point numbers that\nare no more than ",[21,431,432],{},"maxUlpDiff",[45,434,437],{"href":435,"rel":436},"https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FUnit_in_the_last_place",[64],"ULPs","\naway from the ",[21,440,216],{}," value. The short version of what this means\nis that there is no more than ",[21,443,444],{},"maxUlpDiff - 1"," representable floating\npoint numbers between the argument for matching and the ",[21,447,216],{}," value.",[13,450,451,452,455],{},"When using the ULP matcher in Catch2, it is important to keep in mind\nthat Catch2 interprets ULP distance slightly differently than\ne.g. ",[21,453,454],{},"std::nextafter"," does.",[13,457,458],{},"Catch2's ULP calculation obeys these relations:",[90,460,461,466,472,477],{},[93,462,463],{},[21,464,465],{},"ulpDistance(-x, x) == 2 * ulpDistance(x, 0)",[93,467,468,471],{},[21,469,470],{},"ulpDistance(-0, 0) == 0"," (due to the above)",[93,473,474],{},[21,475,476],{},"ulpDistance(DBL_MAX, INFINITY) == 1",[93,478,479],{},[21,480,481],{},"ulpDistancE(NaN, x) == infinity",[13,483,484,487,488,493],{},[16,485,486],{},"Important",": The WithinULP matcher requires the platform to use the\n",[45,489,492],{"href":490,"rel":491},"https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FIEEE_754",[64],"IEEE-754"," representation for\nfloating point numbers.",[73,495,497],{"className":123,"code":496,"language":125,"meta":81,"style":81},"REQUIRE_THAT( -0.f, WithinULP( 0.f, 0 ) );\n",[21,498,499],{"__ignoreMap":81},[129,500,501,503,505,508,510,512,514,516,518,520,522,524,526],{"class":131,"line":132},[129,502,242],{"class":135},[129,504,140],{"class":139},[129,506,507],{"class":177},"-",[129,509,273],{"class":167},[129,511,276],{"class":177},[129,513,36],{"class":139},[129,515,424],{"class":135},[129,517,140],{"class":139},[129,519,273],{"class":167},[129,521,276],{"class":177},[129,523,36],{"class":139},[129,525,196],{"class":167},[129,527,528],{"class":139}," ) );\n",[68,530,532],{"id":531},"approx",[21,533,534],{},"Approx",[73,536,539],{"className":537,"code":538,"language":78},[76],"#include \u003CProgmasoft\u002FCatch3\u002FApprox.hpp>\n",[21,540,538],{"__ignoreMap":81},[13,542,543,549],{},[16,544,545,546,548],{},"We strongly recommend against using ",[21,547,534],{}," when writing new code.","\nYou should be using floating point matchers instead.",[13,551,552,553,555],{},"Catch2 provides one more way to handle floating point comparisons. It is\n",[21,554,534],{},", a special type with overloaded comparison operators, that can\nbe used in standard assertions, e.g.",[73,557,559],{"className":123,"code":558,"language":125,"meta":81,"style":81},"REQUIRE(0.99999 == Catch::Approx(1));\n",[21,560,561],{"__ignoreMap":81},[129,562,563,565,567,570,573,575,577,579,581,584],{"class":131,"line":132},[129,564,27],{"class":135},[129,566,193],{"class":139},[129,568,569],{"class":167},"0.99999",[129,571,572],{"class":177}," ==",[129,574,181],{"class":135},[129,576,155],{"class":139},[129,578,534],{"class":135},[129,580,193],{"class":139},[129,582,583],{"class":167},"1",[129,585,264],{"class":139},[13,587,588,590,591,36,594,36,597,36,600,603,604,606,607,610],{},[21,589,534],{}," supports four comparison operators, ",[21,592,593],{},"==",[21,595,596],{},"!=",[21,598,599],{},"\u003C=",[21,601,602],{},">=",", and can\nalso be used with strong typedefs over ",[21,605,228],{},"s. It can be used for both\nrelative and margin comparisons by using its three customization points.\nNote that the semantics of this is always that of an ",[326,608,609],{},"or",", so if either\nthe relative or absolute margin comparison passes, then the whole comparison\npasses.",[13,612,613,614,616,617,619],{},"The downside to ",[21,615,534],{}," is that it has a couple of issues that we cannot\nfix without breaking backwards compatibility. Because Catch2 also provides\ncomplete set of matchers that implement different floating point comparison\nmethods, ",[21,618,534],{}," is left as-is, is considered deprecated, and should\nnot be used in new code.",[13,621,622],{},"The issues are",[90,624,625,631,643],{},[93,626,627,628,630],{},"All internal computation is done in ",[21,629,228],{},"s, leading to slightly\ndifferent results if the inputs were floats.",[93,632,633,635,636,639,640,66],{},[21,634,534],{},"'s relative margin comparison is not symmetric. This means\nthat ",[21,637,638],{},"Approx( 10 ).epsilon(0.1) != 11.1"," but ",[21,641,642],{},"Approx( 11.1 ).epsilon(0.1) == 10",[93,644,645,646,648,649,652,653,66],{},"By default, ",[21,647,534],{}," only uses relative margin comparison. This means\nthat ",[21,650,651],{},"Approx(0) == X"," only passes for ",[21,654,655],{},"X == 0",[206,657,659],{"id":658},"approx-details","Approx details",[13,661,662,663,665],{},"If you still want\u002Fneed to know more about ",[21,664,534],{},", read on.",[13,667,668,669,671,672,675,676,679],{},"Catch2 provides a UDL for ",[21,670,534],{},"; ",[21,673,674],{},"_a",". It resides in the ",[21,677,678],{},"Catch::literals","\nnamespace, and can be used like this:",[73,681,683],{"className":123,"code":682,"language":125,"meta":81,"style":81},"using namespace Catch::literals;\nREQUIRE( performComputation() == 2.1_a );\n",[21,684,685,703],{"__ignoreMap":81},[129,686,687,690,693,695,697,700],{"class":131,"line":132},[129,688,689],{"class":177},"using",[129,691,692],{"class":177}," namespace",[129,694,181],{"class":135},[129,696,155],{"class":139},[129,698,699],{"class":135},"literals",[129,701,702],{"class":139},";\n",[129,704,705,707,709,712,715,717,720,722],{"class":131,"line":149},[129,706,27],{"class":135},[129,708,140],{"class":139},[129,710,711],{"class":135},"performComputation",[129,713,714],{"class":139},"() ",[129,716,593],{"class":177},[129,718,719],{"class":167}," 2.1",[129,721,674],{"class":177},[129,723,724],{"class":139}," );\n",[13,726,727,729],{},[21,728,534],{}," has three customization points for the comparison:",[90,731,732],{},[93,733,734,737,738,740,741],{},[16,735,736],{},"epsilon"," - epsilon sets the coefficient by which a result\ncan differ from ",[21,739,534],{},"'s value before it is rejected.\n",[326,742,743,744,66],{},"Defaults to ",[21,745,746],{},"std::numeric_limits\u003Cfloat>::epsilon()*100",[73,748,750],{"className":123,"code":749,"language":125,"meta":81,"style":81},"Approx target = Approx(100).epsilon(0.01);\n100.0 == target; \u002F\u002F Obviously true\n200.0 == target; \u002F\u002F Obviously still false\n100.5 == target; \u002F\u002F True, because we set target to allow up to 1% difference\n",[21,751,752,781,794,806],{"__ignoreMap":81},[129,753,754,757,760,763,765,768,771,773,775,778],{"class":131,"line":132},[129,755,756],{"class":139},"Approx target ",[129,758,759],{"class":177},"=",[129,761,762],{"class":135}," Approx",[129,764,193],{"class":139},[129,766,767],{"class":167},"100",[129,769,770],{"class":139},").",[129,772,736],{"class":135},[129,774,193],{"class":139},[129,776,777],{"class":167},"0.01",[129,779,780],{"class":139},");\n",[129,782,783,786,788,791],{"class":131,"line":149},[129,784,785],{"class":167},"100.0",[129,787,572],{"class":177},[129,789,790],{"class":139}," target;",[129,792,793],{"class":299}," \u002F\u002F Obviously true\n",[129,795,796,799,801,803],{"class":131,"line":174},[129,797,798],{"class":167},"200.0",[129,800,572],{"class":177},[129,802,790],{"class":139},[129,804,805],{"class":299}," \u002F\u002F Obviously still false\n",[129,807,808,811,813,815],{"class":131,"line":303},[129,809,810],{"class":167},"100.5",[129,812,572],{"class":177},[129,814,790],{"class":139},[129,816,817],{"class":299}," \u002F\u002F True, because we set target to allow up to 1% difference\n",[90,819,820],{},[93,821,822,824,825,740,827],{},[16,823,220],{}," - margin sets the absolute value by which\na result can differ from ",[21,826,534],{},[326,828,743,829,66],{},[21,830,831],{},"0.0",[73,833,835],{"className":123,"code":834,"language":125,"meta":81,"style":81},"Approx target = Approx(100).margin(5);\n100.0 == target; \u002F\u002F Obviously true\n200.0 == target; \u002F\u002F Obviously still false\n104.0 == target; \u002F\u002F True, because we set target to allow absolute difference of at most 5\n",[21,836,837,860,870,880],{"__ignoreMap":81},[129,838,839,841,843,845,847,849,851,853,855,858],{"class":131,"line":132},[129,840,756],{"class":139},[129,842,759],{"class":177},[129,844,762],{"class":135},[129,846,193],{"class":139},[129,848,767],{"class":167},[129,850,770],{"class":139},[129,852,220],{"class":135},[129,854,193],{"class":139},[129,856,857],{"class":167},"5",[129,859,780],{"class":139},[129,861,862,864,866,868],{"class":131,"line":149},[129,863,785],{"class":167},[129,865,572],{"class":177},[129,867,790],{"class":139},[129,869,793],{"class":299},[129,871,872,874,876,878],{"class":131,"line":174},[129,873,798],{"class":167},[129,875,572],{"class":177},[129,877,790],{"class":139},[129,879,805],{"class":299},[129,881,882,885,887,889],{"class":131,"line":303},[129,883,884],{"class":167},"104.0",[129,886,572],{"class":177},[129,888,790],{"class":139},[129,890,891],{"class":299}," \u002F\u002F True, because we set target to allow absolute difference of at most 5\n",[90,893,894],{},[93,895,896,899,900,902,903],{},[16,897,898],{},"scale"," - scale is used to change the magnitude of ",[21,901,534],{}," for the relative check.\n",[326,904,905,906,66],{},"By default, set to ",[21,907,831],{},[13,909,910],{},"Scale could be useful if the computation leading to the result worked\non a different scale than is used by the results. Approx's scale is added\nto Approx's value when computing the allowed relative margin from the\nApprox's value.",[912,913,914],"style",{},"html pre.shiki code .svObZ, html code.shiki .svObZ{--shiki-default:#B392F0}html pre.shiki code .s95oV, html code.shiki .s95oV{--shiki-default:#E1E4E8}html pre.shiki code .sDLfK, html code.shiki .sDLfK{--shiki-default:#79B8FF}html pre.shiki code .snl16, html code.shiki .snl16{--shiki-default:#F97583}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}",{"title":81,"searchDepth":149,"depth":149,"links":916},[917,922],{"id":70,"depth":149,"text":71,"children":918},[919,920,921],{"id":208,"depth":174,"text":190},{"id":319,"depth":174,"text":116},{"id":423,"depth":174,"text":424},{"id":531,"depth":149,"text":534,"children":923},[924],{"id":658,"depth":174,"text":659},"md",{},true,"\u002Fdocs\u002Fcomparing-floating-point-numbers",{"title":5,"description":81},"comparing-floating-point-numbers","docs\u002Fcomparing-floating-point-numbers.md","docs\u002Fcomparing-floating-point-numbers","MeyjlFk0IRNRP0rDKWN2QYT8E9eeLj93eaZt31HmZEY",1794961594988]