Bug #99162 for Digest-SHA: Documentation tweak

Fri Sep 26 13:41:27 2014 warren [...] etr-usa.com - Ticket created

Subject:	Documentation tweak
Date:	Fri, 26 Sep 2014 11:41:17 -0600
To:	bug-Digest-SHA [...] rt.cpan.org
From:	Warren Young <warren [...] etr-usa.com>

Hi, I thought you might like to give this trick in the Digest::SHA docs in place of the current while loop you have for padding Base64 strings: $b64_digest .= '=' x (-length($b64_digest) % 4); It not only does the same work in a single line, it avoids the loop entirely. The math is a little tricky. length($b64_digest) % 4 tells us how many characters over the next lower multiple of 4 we are. By negating the length first, we get the number of characters to the *next* multiple of 4, which tells us how many = signs to append. Perl's uncommon 'x' operator does the rest. I confess that I did not come up with this numeric trick myself. I initially constructed it like this: $b64_digest .= '=' x ((4 - (length($b64_digest) % 4)) % 4); I thought there had to be a better way to express it, so I asked Wolfram Alpha, and it came up with the formulation above. :)

Sat Sep 27 06:22:12 2014 mshelor [...] cpan.org - Correspondence added

Thank you very much for your attention and suggestion of expert code. Indeed the 'while' loop in the documentation is inefficient. But its virtue is that it demonstrates the padding logic in the most straightforward manner: by looking at this simple code, one sees immediately how padding works. In practice I always use code such as yours for padding. But for those programmers unfamiliar with the behavior of the 'mod' operator on negative numbers, using such code as yours in the documentation might serve to confuse rather than to enlighten; more words would need to be expended to explain the 'mod' behavior, which would then detract from the main topic. But I do appreciate your suggestion. Perhaps in later releases I'll mention that the code fragment is for illustrative purposes only, and that a more efficient version might be desired in practice.

Sat Sep 27 06:22:12 2014 The RT System itself - Status changed from 'new' to 'open'

Sat Sep 27 06:22:13 2014 mshelor [...] cpan.org - Status changed from 'open' to 'rejected'

Mon Sep 29 15:18:25 2014 warren [...] etr-usa.com - Correspondence added

Subject:	Re: [rt.cpan.org #99162] Documentation tweak
Date:	Mon, 29 Sep 2014 13:18:12 -0600
To:	bug-Digest-SHA [...] rt.cpan.org
From:	Warren Young <warren [...] etr-usa.com>

On 9/27/2014 04:22, Mark Shelor via RT wrote: Show quoted text

> using such code as yours in the documentation > might serve to confuse rather than to enlighten; more words would > need to be expended to explain the 'mod' behavior, which would then > detract from the main topic.

I don't think you *should* explain it. Just drop it in, and everyone will benefit to the extent of their own curiosity. Those seeking magic incantations get what they want, and the curious ones go figure out *why* it works and maybe learn a new trick. The alternative is that the incurious copy-paste inefficient code, and the smarter sort either don't figure out that a better way is possible, or end up wasting time reinventing a perfectly good wheel, the very sort of thing CPAN was created to prevent.