{"action":"created","issue":{"url":"https://api.github.com/repos/JuliaLang/julia/issues/13841","labels_url":"https://api.github.com/repos/JuliaLang/julia/issues/13841/labels{/name}","comments_url":"https://api.github.com/repos/JuliaLang/julia/issues/13841/comments","events_url":"https://api.github.com/repos/JuliaLang/julia/issues/13841/events","html_url":"https://github.com/JuliaLang/julia/pull/13841","id":114431340,"number":13841,"title":"Documented abs overflow behavior, added checked_abs for overflow prot…","user":{"login":"MichaeLeroy","id":9284100,"avatar_url":"https://avatars.githubusercontent.com/u/9284100?v=3","gravatar_id":"","url":"https://api.github.com/users/MichaeLeroy","html_url":"https://github.com/MichaeLeroy","followers_url":"https://api.github.com/users/MichaeLeroy/followers","following_url":"https://api.github.com/users/MichaeLeroy/following{/other_user}","gists_url":"https://api.github.com/users/MichaeLeroy/gists{/gist_id}","starred_url":"https://api.github.com/users/MichaeLeroy/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MichaeLeroy/subscriptions","organizations_url":"https://api.github.com/users/MichaeLeroy/orgs","repos_url":"https://api.github.com/users/MichaeLeroy/repos","events_url":"https://api.github.com/users/MichaeLeroy/events{/privacy}","received_events_url":"https://api.github.com/users/MichaeLeroy/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":20,"created_at":"2015-10-31T20:13:33Z","updated_at":"2015-11-02T00:43:29Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/JuliaLang/julia/pulls/13841","html_url":"https://github.com/JuliaLang/julia/pull/13841","diff_url":"https://github.com/JuliaLang/julia/pull/13841.diff","patch_url":"https://github.com/JuliaLang/julia/pull/13841.patch"},"body":"…ection\r\n\r\n## Summary\r\nThis PR is to address, in part, #13549.  It adds documentation to the signed integer version of `abs` that explains its overflow behavior.  It also adds an overflow trapped version of this function, `Base.checked_abs`.  As yet unaddressed is the addition of an *Integer overflow* entry to Julia's FAQ.\r\n\r\n## `abs` Documentation\r\nWith this change, the documentation for `abs` reads:\r\n```\r\njulia> @doc abs\r\n  abs(x::Signed)\r\n\r\n  The absolute value of x.  When abs is applied to signed integers, overflow may occur, resulting in the\r\n  return of a negative value.  This overflow occurs only when abs is applied to the minimum representable\r\n  value of a signed integer.  That is when x == typemin(typeof(x)), abs(x) == x, not -x as might be\r\n  expected.\r\n\r\n  abs(x)\r\n\r\n  Absolute value of x\r\n```\r\nIt is interesting that the added signed integer specific `abs` documentation is printed prior to the already existing generic documentation.  As far as I can tell, such presentation is a result of the design of the documentation system, which presents documentation in order of descending specificity,\r\n\r\n## `Base.checked_abs`\r\nThis function's documentation tells most of the story:\r\n```\r\njulia> @doc Base.checked_abs\r\n  checked_abs(x::Signed)\r\n\r\n  The absolute value of x, with signed integer overflow error trapping. checked_abs will throw an\r\n  OverflowError when x == typemin(typeof(x)).  Otherwise checked_abs behaves as abs, though the overflow\r\n  protection may impose a perceptible performance penalty.\r\n```\r\n I chose to implement this function only for Signed types, rather than (trivially) making it more generic.  I did so, because it struck me as a sort of false advertising to provide this function for other types when it useful only for Signed types.  That said, I have no strong feelings against making it more generic.\r\n"},"comment":{"url":"https://api.github.com/repos/JuliaLang/julia/issues/comments/152883099","html_url":"https://github.com/JuliaLang/julia/pull/13841#issuecomment-152883099","issue_url":"https://api.github.com/repos/JuliaLang/julia/issues/13841","id":152883099,"user":{"login":"MichaeLeroy","id":9284100,"avatar_url":"https://avatars.githubusercontent.com/u/9284100?v=3","gravatar_id":"","url":"https://api.github.com/users/MichaeLeroy","html_url":"https://github.com/MichaeLeroy","followers_url":"https://api.github.com/users/MichaeLeroy/followers","following_url":"https://api.github.com/users/MichaeLeroy/following{/other_user}","gists_url":"https://api.github.com/users/MichaeLeroy/gists{/gist_id}","starred_url":"https://api.github.com/users/MichaeLeroy/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MichaeLeroy/subscriptions","organizations_url":"https://api.github.com/users/MichaeLeroy/orgs","repos_url":"https://api.github.com/users/MichaeLeroy/repos","events_url":"https://api.github.com/users/MichaeLeroy/events{/privacy}","received_events_url":"https://api.github.com/users/MichaeLeroy/received_events","type":"User","site_admin":false},"created_at":"2015-11-02T00:43:29Z","updated_at":"2015-11-02T00:43:29Z","body":"@simonster and @yuyichao thanks for your inputs.  I have only a bit of work time left in my day (and am frazzled from the `checked_abs` versus `scott_abs` discussion), but I'll attempt to get the appropriate tests implemented and checked in the time I have.  If not, finalization will have to wait for my morning some 12 hours hence."}}