[PATCH] hex() documentation not clear on invalid input #15006
Comments
From @epaCreated by @epaThe documentation in perlfunc for C<hex> says nothing about the If there is a consensus that this is the correct and intended (If the current behaviour is kept, is there any way to test whether Perl Info |
From zefram@fysh.orgEd Avis wrote:
You can always check /\A(?:0?[xX])?(?:_?[0-9a-fA-F])*\z/. Generally hex() -zefram |
|
The RT System itself - Status changed from 'new' to 'open' |
From @epaZefram <zefram <at> fysh.org> writes:
That's right, and of course I am doing that. Ah - and I see from your regexp that hex() does understand the 0x prefix, Generally even if I have extracted data with a regexp I still want to check -- |
From Eirik-Berg.Hanssen@allverden.noOn Fri, Oct 23, 2015 at 6:01 PM, Ed Avis <perlbug-followup@perl.org> wrote:
I'm not sure about documenting it, but … eval { use warnings "FATAL"; hex $foo } Though personally, I guess I'd trim (or at least chomp()) $foo first: $ perl -E 'say eval { use warnings "FATAL"; hex(s/^\s+|\s+$//rg) } // 26 Eirik |
From Eirik-Berg.Hanssen@allverden.noOn Fri, Oct 23, 2015 at 6:24 PM, Ed Avis <eda@waniasset.com> wrote:
do { use warnings "FATAL"; hex($x) } # ;-) Eirik |
From @epaProposed patch codifying the current behaviour: index f0a2abb..1811d8b 100644 Interprets EXPR as a hex string and returns the corresponding value. print hex '0xAf'; # prints '175' Hex strings may only represent integers. Strings that would cause =item import LIST |
From @epa...another question is to what extent 'x' instead of '0x' is supported? Should the docs for both hex and oct change to list both variants? Ditto 'b' vs '0b'. |
From @AbigailOn Mon, Oct 26, 2015 at 08:10:34AM -0700, Ed Avis via RT wrote:
I find the phrase "If you want to make sure that hex succeeds..." I'd also use "ignored" where you say "stripped". Because in my $hex = "0xF00"; the second line still prints the leading '0x', and nothing gets Abigail |
From @epaThanks for your comments; here's a revised patch. Note that perlfunc often uses 'stripped' to mean that certain data is ignored and not included in the output of a function, without implying that the function destructively modifies its input. Within the documentation for 'hex', I have standardized on 'ignored' as you suggest. --- a/pod/perlfunc.pod Interprets EXPR as a hex string and returns the corresponding value. print hex '0xAf'; # prints '175' Hex strings may only represent integers. Strings that would cause =item import LIST |
From @tonycozOn Fri Oct 23 09:01:10 2015, eda@waniasset.com wrote:
The behaviour is inconsistent - it croaks if the string contains a wide character: tony@mars:.../git/perl$ ./perl -le 'print hex("x20_00\x{101}")' which is probably a bug. Tony |
From @epa
Yet this appears deliberate: there is a test in t/oct.t which makes sure that wide characters cause an exception. On the other hand there are no test cases for ASCII, but non-hex-digit characters in the string. Should the behaviour be made consistent so that all bad characters, wide or not, throw an exception? Or should it be that all bad characters just raise a warning and the longest valid initial substring is taken as the hex input? Or do we just codify and test the current somewhat wonky semantics? If the perl5-porters can indicate the preferred way forward then I will include some test cases as well as the documentation change. |
From @ap* Ed Avis via RT <perlbug-followup@perl.org> [2015-10-26 16:45]:
This triples the length of the entry. Ignoring the wide character bug, Inline Patchdiff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index f0a2abbb4c..00332d8fbd 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3028,18 +3028,23 @@ X<hex> X<hexadecimal>
=item hex
-=for Pod::Functions convert a string to a hexadecimal number
+=for Pod::Functions convert a hexadecimal string to a number
-Interprets EXPR as a hex string and returns the corresponding value.
-(To convert strings that might start with either C<0>, C<0x>, or C<0b>, see
-L</oct>.) If EXPR is omitted, uses C<$_>.
+Interprets EXPR as a hex string and returns the corresponding numeric value.
+If EXPR is omitted, uses C<$_>.
print hex '0xAf'; # prints '175'
print hex 'aF'; # same
-Hex strings may only represent integers. Strings that would cause
-integer overflow trigger a warning. Leading whitespace is not stripped,
-unlike oct(). To present something as hex, look into L</printf>,
+A hex string consists of hex digits and an optional C<0x> or C<x> prefix.
+Each hex digit may be preceded by a single underscore, which will be ignored.
+Any other character triggers a warning and causes the rest of the string
+to be ignored (even leading whitespace, unlike L</oct>).
+Only integers can be represented, and integer overflow triggers a warning.
+
+To convert strings that might start with either C<0>, C<0x>, or C<0b>, see
+L</oct>.
+To present something as hex, look into L</printf>,
L</sprintf>, and L</unpack>.
=item import LIST |
From @epaI like your more concise wording. But I think it is useful to have Zefram's regexp of valid hex numbers and an idiot-proof example of how to use it; or alternatively the example of how to check that hex() succeeded by trapping warnings. Perhaps it is overkill to mention both, but one or the other should be there. Just as much of the documentation on open() talks about how to make sure it succeeded, so hex() needs to suggest and encourage good error checking practices. |
From @cowensOn Tue, Nov 3, 2015 at 7:36 AM Ed Avis via RT <perlbug-followup@perl.org> wrote:
Here is my take. It includes all of the variant headers and examples I also stripped the statement that only integers can be represented Inline Patchdiff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index f0a2abb..3babe72 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3028,19 +3028,27 @@ X<hex> X<hexadecimal>
=item hex
-=for Pod::Functions convert a string to a hexadecimal number
+=for Pod::Functions convert a hex string to a number
-Interprets EXPR as a hex string and returns the corresponding value.
-(To convert strings that might start with either C<0>, C<0x>, or C<0b>, see
-L</oct>.) If EXPR is omitted, uses C<$_>.
+Interprets EXPR as a hex string and returns the corresponding decimal value.
+If EXPR is omitted, uses C<$_>.
+
+ # All of these conversions are equivalent
+ for my $hex_string (qw/ 0xAf 0XAf xaF XaF aF 0x_a_f /) {
+ print hex($hex_string), "\n";
+ }
+
+A hex string consists of an optional header (C<0x|0X|x|X>), hexadecimal
+digits (C<[0-9a-fA-F]>), and optional digit separators (one C<_> is allowed
+before each digit). Any other character triggers a warning and causes the rest
+of the string to be ignored (even leading whitespace, unlike L<oct>). Strings
+that would cause integer overflow trigger a warning.
- print hex '0xAf'; # prints '175'
- print hex 'aF'; # same
+To convert strings that might start with one of C<0> (octal), C<0x> (hex),
+or C<0b> (binary), see L</oct>.
-Hex strings may only represent integers. Strings that would cause
-integer overflow trigger a warning. Leading whitespace is not stripped,
-unlike oct(). To present something as hex, look into L</printf>,
-L</sprintf>, and L</unpack>.
+To convert a number into hex, look into L</printf>, L</sprintf>, and
+L</unpack>.
=item import LIST
X<import> |
From @ap* Ed Avis via RT <perlbug-followup@perl.org> [2015-11-03 13:40]:
Actually, you’re right. I don’t think an explanation of the fact that you can fatalise warnings But even for the regexp I was reluctant, since it seemed redundant with So I went to propose adding just this line to the code examples (to keep $valid_input =~ /\A(?:0?[xX])?(?:_?[0-9a-fA-F])*\z/ But when I tried that on for size, I realised that the prose and pattern Does that work for you? Regards, |
From @epaIt depends on whether you see 'perlfunc' as reference or tutorial. As a reference or spec for Perl's builtin functions, it certainly should not repeat the same information about fatal warnings in random places. If a tutorial, then the emphasis should be on examples and reminding the reader of useful related information, even if that causes some redundancy. 'perlopentut' has lots of repeated boilerplate showing how to use die and If the regexp is included then that takes care of showing how to check that hex() will succeed, so an example of trapping warnings from it is less necessary. (It might be useful for that regexp itself to be provided in core, or for core to have a looks_like_hex() builtin... but that is for another day.) |
From @ap* Chas. Owens <chas.owens@gmail.com> [2015-11-03 15:25]:
Following the principle that they call “lots helps lots” in Germany? :-)
I considered that but decided to keep an explicit mention because Perl Other quibbles: • You dropped the pointer that oct() is capable of parsing non-oct • Minor: you have L<oct> in there; there is no such document to link to. Regards, |
From @ap* Ed Avis via RT <perlbug-followup@perl.org> [2015-11-03 19:15]:
But perldoc -f open is much less of a tutorial and we’re not talking
I’ve just pushed that patch as fc61cbf. |
From @jkeenanPatch was applied by Aristotle; closing. |
|
@jkeenan - Status changed from 'open' to 'resolved' |
Migrated from rt.perl.org#126437 (status was 'resolved')
Searchable as RT126437$
The text was updated successfully, but these errors were encountered: