Error in documentation on "perldata"

[p5pRT]

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

Searchable as RT131166$

[p5pRT]

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]

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]

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

[p5pRT]

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]

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]

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]

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]

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]

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

[p5pRT]

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]

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