Error in documentation on "perldata" #15954

p5pRT · 2017-04-17T12:17:44Z

Migrated from rt.perl.org#131166 (status was 'resolved')

Searchable as RT131166$

p5pRT · 2017-04-17T12:17:45Z

From wolf-dietrich_moeller@t-online.de

Created by wolf-dietrich_moeller@t-online.de

The documentation "perldata" reads in the section on "Scalar values" the
following:
"If you evaluate a hash in scalar context, it returns false if the hash is
empty. ..."
This statement not completely true.
- It is true if evaluated in Boolean context, e.g. in "if ( %hash )".
- But if used in scalar context expecting a string (e.g. 'n='.%hash), it
returns "0",
and not the empty string, which would be expected for a result = "false".

So the sentence cited above should read:
"If you evaluate a hash in scalar context, it returns 0 if the hash is
empty. ..."

Perl Info


Flags:
    category=docs
    severity=low

Site configuration information for perl 5.24.1:

Configured by strawberry-perl at Sun Jan 15 20:30:58 2017.

Summary of my perl5 (revision 5 version 24 subversion 1) configuration:
   
  Platform:
    osname=MSWin32, osvers=6.3, archname=MSWin32-x86-multi-thread-64int
    uname='Win32 strawberry-perl 5.24.1.1 #1 Sun Jan 15 20:28:53 2017 i386'
    config_args='undef'
    hint=recommended, useposix=true, d_sigaction=undef
    useithreads=define, usemultiplicity=define
    use64bitint=define, use64bitall=undef, uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='gcc', ccflags =' -s -O2 -DWIN32  -DPERL_TEXTMODE_SCRIPTS
-DPERL_IMPLICIT_CONTEXT -DPERL_IMPLICIT_SYS -fwrapv -fno-strict-aliasing
-mms-bitfields',
    optimize='-s -O2',
    cppflags='-DWIN32'
    ccversion='', gccversion='4.9.2', gccosandvers=''
    intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=12345678,
doublekind=3
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12,
longdblkind=3
    ivtype='long long', ivsize=8, nvtype='double', nvsize=8, Off_t='long
long', lseeksize=8
    alignbytes=8, prototype=define
  Linker and Libraries:
    ld='g++', ldflags ='-s -L"C:\Perl\perl\lib\CORE" -L"C:\Perl\c\lib"'
    libpth=C:\Perl\c\lib C:\Perl\c\i686-w64-mingw32\lib
C:\Perl\c\lib\gcc\i686-w64-mingw32\4.9.2
    libs=-lmoldname -lkernel32 -luser32 -lgdi32 -lwinspool -lcomdlg32
-ladvapi32 -lshell32 -lole32 -loleaut32 -lnetapi32 -luuid -lws2_32 -lmpr
-lwinmm -lversion -lodbc32 -lodbccp32 -lcomctl32
    perllibs=-lmoldname -lkernel32 -luser32 -lgdi32 -lwinspool -lcomdlg32
-ladvapi32 -lshell32 -lole32 -loleaut32 -lnetapi32 -luuid -lws2_32 -lmpr
-lwinmm -lversion -lodbc32 -lodbccp32 -lcomctl32
    libc=, so=dll, useshrplib=true, libperl=libperl524.a
    gnulibc_version=''
  Dynamic Linking:
    dlsrc=dl_win32.xs, dlext=xs.dll, d_dlsymun=undef, ccdlflags=' '
    cccdlflags=' ', lddlflags='-mdll -s -L"C:\Perl\perl\lib\CORE"
-L"C:\Perl\c\lib"'



@INC for perl 5.24.1:
    C:/Perl/perl/site/lib
    C:/Perl/perl/vendor/lib
    C:/Perl/perl/lib


Environment for perl 5.24.1:
    HOME (unset)
    LANG (unset)
    LANGUAGE (unset)
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=C:\Documents and Settings\All Users\Application
Data\Oracle\Java\javapath;C:\Program Files\Perl\site\bin;C:\Program
Files\Perl\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\Pr
ogram Files\Windows
Imaging\;C:\WINDOWS\system32\WindowsPowerShell\v1.0;C:\Bin;C:\Program
Files\QuickTime
Alternative\QTSystem;C:\Perl\c\bin;C:\Perl\perl\site\bin;C:\Perl\perl\bin
    PERL_BADLANG (unset)
    SHELL (unset)

p5pRT · 2017-04-18T18:56:56Z

From @jkeenan

On Mon, 17 Apr 2017 12:17:45 GMT, wolf-dietrich_moeller@t-online.de wrote:

This is a bug report for perl from wolf-dietrich_moeller@t-online.de,
generated with the help of perlbug 1.40 running under perl 5.24.1.

-----------------------------------------------------------------
[Please describe your issue here]
The documentation "perldata" reads in the section on "Scalar values" the
following:
"If you evaluate a hash in scalar context, it returns false if the hash is
empty. ..."
This statement not completely true.
- It is true if evaluated in Boolean context, e.g. in "if ( %hash )".

$ perl -wE '%hash = (); if (%hash) { say "Demonstrated"; } else { say "Not demonstrated"; }'
Not demonstrated

- But if used in scalar context expecting a string (e.g. 'n='.%hash), it
returns "0",
and not the empty string, which would be expected for a result = "false".

So the sentence cited above should read:
"If you evaluate a hash in scalar context, it returns 0 if the hash is
empty. ..."

[Please do not change anything below this line]
-----------------------------------------------------------------
---
Flags:
category=docs
severity=low
---
Site configuration information for perl 5.24.1:

Configured by strawberry-perl at Sun Jan 15 20:30:58 2017.

Summary of my perl5 (revision 5 version 24 subversion 1) configuration:

Platform:
osname=MSWin32, osvers=6.3, archname=MSWin32-x86-multi-thread-64int
uname='Win32 strawberry-perl 5.24.1.1 #1 Sun Jan 15 20:28:53 2017 i386'
config_args='undef'
hint=recommended, useposix=true, d_sigaction=undef
useithreads=define, usemultiplicity=define
use64bitint=define, use64bitall=undef, uselongdouble=undef
usemymalloc=n, bincompat5005=undef
Compiler:
cc='gcc', ccflags =' -s -O2 -DWIN32 -DPERL_TEXTMODE_SCRIPTS
-DPERL_IMPLICIT_CONTEXT -DPERL_IMPLICIT_SYS -fwrapv -fno-strict-aliasing
-mms-bitfields',
optimize='-s -O2',
cppflags='-DWIN32'
ccversion='', gccversion='4.9.2', gccosandvers=''
intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=12345678,
doublekind=3
d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12,
longdblkind=3
ivtype='long long', ivsize=8, nvtype='double', nvsize=8, Off_t='long
long', lseeksize=8
alignbytes=8, prototype=define
Linker and Libraries:
ld='g++', ldflags ='-s -L"C:\Perl\perl\lib\CORE" -L"C:\Perl\c\lib"'
libpth=C:\Perl\c\lib C:\Perl\c\i686-w64-mingw32\lib
C:\Perl\c\lib\gcc\i686-w64-mingw32\4.9.2
libs=-lmoldname -lkernel32 -luser32 -lgdi32 -lwinspool -lcomdlg32
-ladvapi32 -lshell32 -lole32 -loleaut32 -lnetapi32 -luuid -lws2_32 -lmpr
-lwinmm -lversion -lodbc32 -lodbccp32 -lcomctl32
perllibs=-lmoldname -lkernel32 -luser32 -lgdi32 -lwinspool -lcomdlg32
-ladvapi32 -lshell32 -lole32 -loleaut32 -lnetapi32 -luuid -lws2_32 -lmpr
-lwinmm -lversion -lodbc32 -lodbccp32 -lcomctl32
libc=, so=dll, useshrplib=true, libperl=libperl524.a
gnulibc_version=''
Dynamic Linking:
dlsrc=dl_win32.xs, dlext=xs.dll, d_dlsymun=undef, ccdlflags=' '
cccdlflags=' ', lddlflags='-mdll -s -L"C:\Perl\perl\lib\CORE"
-L"C:\Perl\c\lib"'

---
@INC for perl 5.24.1:
C:/Perl/perl/site/lib
C:/Perl/perl/vendor/lib
C:/Perl/perl/lib

---
Environment for perl 5.24.1:
HOME (unset)
LANG (unset)
LANGUAGE (unset)
LD_LIBRARY_PATH (unset)
LOGDIR (unset)
PATH=C:\Documents and Settings\All Users\Application
Data\Oracle\Java\javapath;C:\Program Files\Perl\site\bin;C:\Program
Files\Perl\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\Pr
ogram Files\Windows
Imaging\;C:\WINDOWS\system32\WindowsPowerShell\v1.0;C:\Bin;C:\Program
Files\QuickTime
Alternative\QTSystem;C:\Perl\c\bin;C:\Perl\perl\site\bin;C:\Perl\perl\bin
PERL_BADLANG (unset)
SHELL (unset)

--
James E Keenan (jkeenan@cpan.org)

p5pRT · 2017-04-18T18:56:56Z

The RT System itself - Status changed from 'new' to 'open'

p5pRT · 2017-04-18T19:17:14Z

From zefram@fysh.org

On Mon, 17 Apr 2017 12:17:45 GMT, wolf-dietrich_moeller@t-online.de wrote:

- But if used in scalar context expecting a string (e.g. 'n='.%hash), it
returns "0",
and not the empty string, which would be expected for a result = "false".

"False" doesn't refer to a unique value. "0" is a false value, as is "".
The documentation is correct in describing the value yielded as false.

-zefram

p5pRT · 2017-04-19T10:34:24Z

From wolf-dietrich_moeller@t-online.de

Hi Zefram,
Please read the text in question carefully:

"If you evaluate a hash in scalar context, it returns false if the hash is
empty. ..."
This text does not talk about evaluation in "Boolean sense", but only in
scalar context. Thus the following program implements the text cited above
(instead of the test program given by James):

perl -wE "my %hash=(); my $x=%hash; print 'x=',$x;"
x=0

The test program given by James adds a second step, namely the evaluation
of the result of "$x=%hash" in Boolean sense. I never challenged that
result, but that program does not reflect the text in the documentation.

Therefore I still suggest changing the text in the documentation to

"If you evaluate a hash in scalar context, it returns 0 if the hash is
empty. ..."

Best regards
Wolf
-----Original Message-----
From: Zefram via RT [mailto:perlbug-followup@perl.org]
Sent: Dienstag, 18. April 2017 21:17
To: wolf-dietrich_moeller@t-online.de
Subject: Re: [perl #131166] Error in documentation on "perldata"

On Mon, 17 Apr 2017 12:17:45 GMT, wolf-dietrich_moeller@t-online.de wrote:

- But if used in scalar context expecting a string (e.g. 'n='.%hash), it
returns "0",
and not the empty string, which would be expected for a result = "false".

"False" doesn't refer to a unique value. "0" is a false value, as is "".
The documentation is correct in describing the value yielded as false.

-zefram

p5pRT · 2017-04-25T11:21:06Z

From @iabyn

On Tue, Apr 18, 2017 at 08:16:11PM +0100, Zefram wrote:

On Mon, 17 Apr 2017 12:17:45 GMT, wolf-dietrich_moeller@t-online.de wrote:

- But if used in scalar context expecting a string (e.g. 'n='.%hash), it
returns "0",
and not the empty string, which would be expected for a result = "false".

"False" doesn't refer to a unique value. "0" is a false value, as is "".
The documentation is correct in describing the value yielded as false.

The documentation in blead says:

If you evaluate a hash in scalar context, it returns false if the
hash is empty. If there are any key/value pairs, it returns true.
A more precise definition is version dependent.

(it then goes on to document what it actually returns pre- and
post-5.25).

While technically correct ("the best sort of correct!"), that paragraph
could be misinterpreted. There are two well-known specific values for
false and true which many perl functions are documented to return (i.e.
PL_sv_yes/no internally), and a casual reader of the documentation may
assume that those specific values are been returned here. I suggest
changing the paragraph to include indefinite articles:

If you evaluate a hash in scalar context, it returns a false value if
the hash is empty. If there are any key/value pairs, it returns a
true value. A more precise definition is version dependent.

--
Lear: Dost thou call me fool, boy?
Fool: All thy other titles thou hast given away; that thou wast born with.

p5pRT · 2017-04-25T15:16:12Z

From @khwilliamson

On 04/25/2017 05:20 AM, Dave Mitchell wrote:

On Tue, Apr 18, 2017 at 08:16:11PM +0100, Zefram wrote:

On Mon, 17 Apr 2017 12:17:45 GMT, wolf-dietrich_moeller@t-online.de wrote:

- But if used in scalar context expecting a string (e.g. 'n='.%hash), it
returns "0",
and not the empty string, which would be expected for a result = "false".

"False" doesn't refer to a unique value. "0" is a false value, as is "".
The documentation is correct in describing the value yielded as false.

The documentation in blead says:
If you evaluate a hash in scalar context\, it returns false if the
hash is empty\.  If there are any key/value pairs\, it returns true\.
A more precise definition is version dependent\.

$it then goes on to document what it actually returns pre\- and
post\-5\.25$\.
While technically correct ("the best sort of correct!"), that paragraph
could be misinterpreted. There are two well-known specific values for
false and true which many perl functions are documented to return (i.e.
PL_sv_yes/no internally), and a casual reader of the documentation may
assume that those specific values are been returned here. I suggest
changing the paragraph to include indefinite articles:
If you evaluate a hash in scalar context\, it returns a false value if
the hash is empty\.  If there are any key/value pairs\, it returns a
true value\.  A more precise definition is version dependent\.

+1

p5pRT · 2017-06-05T14:40:55Z

From @iabyn

On Tue, Apr 25, 2017 at 12:20:40PM +0100, Dave Mitchell wrote:

On Tue, Apr 18, 2017 at 08:16:11PM +0100, Zefram wrote:

On Mon, 17 Apr 2017 12:17:45 GMT, wolf-dietrich_moeller@t-online.de wrote:

- But if used in scalar context expecting a string (e.g. 'n='.%hash), it
returns "0",
and not the empty string, which would be expected for a result = "false".

"False" doesn't refer to a unique value. "0" is a false value, as is "".
The documentation is correct in describing the value yielded as false.

The documentation in blead says:
If you evaluate a hash in scalar context\, it returns false if the
hash is empty\.  If there are any key/value pairs\, it returns true\.
A more precise definition is version dependent\.

$it then goes on to document what it actually returns pre\- and
post\-5\.25$\.
While technically correct ("the best sort of correct!"), that paragraph
could be misinterpreted. There are two well-known specific values for
false and true which many perl functions are documented to return (i.e.
PL_sv_yes/no internally), and a casual reader of the documentation may
assume that those specific values are been returned here. I suggest
changing the paragraph to include indefinite articles:
If you evaluate a hash in scalar context\, it returns a false value if
the hash is empty\.  If there are any key/value pairs\, it returns a
true value\.  A more precise definition is version dependent\.

Now done with v5.27.0-120-gb74e7b8.

--
No matter how many dust sheets you use, you will get paint on the carpet.

p5pRT · 2017-06-06T07:29:28Z

@iabyn - Status changed from 'open' to 'pending release'

p5pRT · 2018-06-23T15:29:58Z

From @khwilliamson

Thank you for filing this report. You have helped make Perl better.

With the release yesterday of Perl 5.28.0, this and 185 other issues have been
resolved.

Perl 5.28.0 may be downloaded via:
https://metacpan.org/release/XSAWYERX/perl-5.28.0

If you find that the problem persists, feel free to reopen this ticket.

p5pRT · 2018-06-23T15:29:59Z

@khwilliamson - Status changed from 'pending release' to 'resolved'

p5pRT closed this as completed Jun 23, 2018

p5pRT added Severity Low distro-mswin32 documentation labels Oct 19, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Error in documentation on "perldata" #15954

Error in documentation on "perldata" #15954

p5pRT commented Apr 17, 2017

p5pRT commented Apr 17, 2017

p5pRT commented Apr 18, 2017

p5pRT commented Apr 18, 2017

p5pRT commented Apr 18, 2017

p5pRT commented Apr 19, 2017

p5pRT commented Apr 25, 2017

p5pRT commented Apr 25, 2017

p5pRT commented Jun 5, 2017

p5pRT commented Jun 6, 2017

p5pRT commented Jun 23, 2018

p5pRT commented Jun 23, 2018

Error in documentation on "perldata" #15954

Error in documentation on "perldata" #15954

Comments

p5pRT commented Apr 17, 2017

p5pRT commented Apr 17, 2017

From wolf-dietrich_moeller@t-online.de

Created by wolf-dietrich_moeller@t-online.de

p5pRT commented Apr 18, 2017

From @jkeenan

p5pRT commented Apr 18, 2017

p5pRT commented Apr 18, 2017

From zefram@fysh.org

p5pRT commented Apr 19, 2017

From wolf-dietrich_moeller@t-online.de

p5pRT commented Apr 25, 2017

From @iabyn

p5pRT commented Apr 25, 2017

From @khwilliamson

p5pRT commented Jun 5, 2017

From @iabyn

p5pRT commented Jun 6, 2017

p5pRT commented Jun 23, 2018

From @khwilliamson

p5pRT commented Jun 23, 2018