search

Perl / perl5

🐪 The Perl programming language
https://dev.perl.org/perl5/
Other
1.84k stars 524 forks source link

Fix the documentation for the substr() function #96

Closed p5pRT closed 20 years ago

p5pRT commented 24 years ago

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

Searchable as RT900$

p5pRT commented 24 years ago

From The RT System itself

Please modify the documentation for the substr() function in the perlfunc man page. It currently includes the following paragraph​:   If you specify a substring that is partly outside   the string\, the part within the string is returned.   If the substring is totally outside the string a   warning is produced.

The phrases "partially outside" and "totally outside" are not well defined and are confusing. This topic has been extensively discussed in the newsgroup compl.lang.perl.moderated\, starting 1999-06-18\, with subject​: substr does not warn when past the end of the string -- off by one bug?

Please rewrite this section.
Tom Phoenix has suggested the following wording​:   Whether substr() is an lvalue or not\, the offset should be less than   I\ the length of the string. If the offset is greater   than the length\, this is a fatal error for an lvalue substr() and   an optional warning for an rvalue substr().

  A warning is I\ triggered if the offset is equal to the length   of the string. When used as an rvalue\, this results in the empty   string\, which may surprise some people and their programs.

  my $name = 'fred';   substr($name\, 4) = 'dy'; # $name is now 'freddy'   my $null = substr $name\, 6; # gives empty string   my $oops = substr $name\, 7; # warning   substr($name\, 7) = 'gap'; # fatal error

Perl Info ``` Site configuration information for perl 5.00502: Summary of my perl5 (5.0 patchlevel 5 subversion 02) configuration: Platform: osname=MSWin32, osvers=4.0, archname=MSWin32-x86-object uname='' hint=recommended, useposix=true, d_sigaction=undef usethreads=undef useperlio=undef d_sfio=undef Compiler: cc='cl.exe', optimize='-O2 -MD -DNDEBUG -TP -GX', gccversion= cppflags='-DWIN32' ccflags ='-O2 -MD -DNDEBUG -TP -GX -DWIN32 -D_CONSOLE -DNO_STRICT -DHAVE_DES_FCRYPT -DPERL_OBJECT' stdchar='char', d_stdstdio=define, usevfork=false intsize=4, longsize=4, ptrsize=4, doublesize=8 d_longlong=undef, longlongsize=8, d_longdbl=define, longdblsize=10 alignbytes=8, usemymalloc=n, prototype=define Linker and Libraries: ld='link', ldflags ='-nologo -nodefaultlib -release -machine:x86' libpth="C:\Perl\lib\core" "" "C:\TGS3D\Lib" libs= oldnames.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib netapi32.lib uuid.lib wsock32.lib mpr.lib winmm.lib version.lib odbc32.lib odbccp32.lib PerlCRT.lib libc=C:\Perl\lib\core\PerlCRT.lib, so=dll, useshrplib=yes, libperl=perlcore.lib Dynamic Linking: dlsrc=dl_win32.xs, dlext=dll, d_dlsymun=undef, ccdlflags=' ' cccdlflags=' ', lddlflags='-dll -nologo -nodefaultlib -release -machine:x86' Locally applied patches: @INC for perl 5.00502: C:\PERL\lib C:\PERL\site\lib . Environment for perl 5.00502: HOME=c:\ LANG (unset) LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=C:\NOVELL\CLIENT32;C:\WINDOWS;C:\WINDOWS\COMMAND;C:\PERL\BIN;C:\GNU\H-I386-CYGWIN32\BIN;C:\EMACS\EMACS-20.3.1\BIN;C:\QTW\BIN;C:\USR\X11R6.3\BIN;C:\TGS3D\PROGRAM;C:\TGS3D\DOC PERL_BADLANG (unset) SHELL=c:\emacs\emacs-20.3.1\bin\cmdproxy.exe Steve -- Steven Tolkin tolkin@mediaone.net work: steve.tolkin@fmr.com Fidelity Investments 82 Devonshire St. R24D Boston MA 02109 617-563-0516 There is nothing so practical as a good theory. Comments are by me, not Fidelity Investments, its subsidiaries or affiliates. Steven Tolkin ```
p5pRT commented 24 years ago

From [Unknown Contact. See original ticket]

Created by tolkin@mediaone.net

Please modify the documentation for the substr() function in the perlfunc man page. It currently includes the following paragraph​:   If you specify a substring that is partly outside   the string\, the part within the string is returned.   If the substring is totally outside the string a   warning is produced.

The phrases "partially outside" and "totally outside" are not well defined and are confusing. This topic has been extensively discussed in the newsgroup compl.lang.perl.moderated\, starting 1999-06-18\, with subject​: substr does not warn when past the end of the string -- off by one bug?

Please rewrite this section.
Tom Phoenix has suggested the following wording​:   Whether substr() is an lvalue or not\, the offset should be less than   I\ the length of the string. If the offset is greater   than the length\, this is a fatal error for an lvalue substr() and   an optional warning for an rvalue substr().

  A warning is I\ triggered if the offset is equal to the length   of the string. When used as an rvalue\, this results in the empty   string\, which may surprise some people and their programs.

  my $name = 'fred';   substr($name\, 4) = 'dy'; # $name is now 'freddy'   my $null = substr $name\, 6; # gives empty string   my $oops = substr $name\, 7; # warning   substr($name\, 7) = 'gap'; # fatal error

Perl Info ``` Site configuration information for perl 5.00502: Summary of my perl5 (5.0 patchlevel 5 subversion 02) configuration: Platform: osname=MSWin32, osvers=4.0, archname=MSWin32-x86-object uname='' hint=recommended, useposix=true, d_sigaction=undef usethreads=undef useperlio=undef d_sfio=undef Compiler: cc='cl.exe', optimize='-O2 -MD -DNDEBUG -TP -GX', gccversion= cppflags='-DWIN32' ccflags ='-O2 -MD -DNDEBUG -TP -GX -DWIN32 -D_CONSOLE -DNO_STRICT -DHAVE_DES_FCRYPT -DPERL_OBJECT' stdchar='char', d_stdstdio=define, usevfork=false intsize=4, longsize=4, ptrsize=4, doublesize=8 d_longlong=undef, longlongsize=8, d_longdbl=define, longdblsize=10 alignbytes=8, usemymalloc=n, prototype=define Linker and Libraries: ld='link', ldflags ='-nologo -nodefaultlib -release -machine:x86' libpth="C:\Perl\lib\core" "" "C:\TGS3D\Lib" libs= oldnames.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib netapi32.lib uuid.lib wsock32.lib mpr.lib winmm.lib version.lib odbc32.lib odbccp32.lib PerlCRT.lib libc=C:\Perl\lib\core\PerlCRT.lib, so=dll, useshrplib=yes, libperl=perlcore.lib Dynamic Linking: dlsrc=dl_win32.xs, dlext=dll, d_dlsymun=undef, ccdlflags=' ' cccdlflags=' ', lddlflags='-dll -nologo -nodefaultlib -release -machine:x86' Locally applied patches: @INC for perl 5.00502: C:\PERL\lib C:\PERL\site\lib . Environment for perl 5.00502: HOME=c:\ LANG (unset) LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=C:\NOVELL\CLIENT32;C:\WINDOWS;C:\WINDOWS\COMMAND;C:\PERL\BIN;C:\GNU\H-I 386-CYGWIN32\BIN;C:\EMACS\EMACS-20.3.1\BIN;C:\QTW\BIN;C:\USR\X11R6.3\BIN;C:\ TGS3D\PROGRAM;C:\TGS3D\DOC PERL_BADLANG (unset) SHELL=c:\emacs\emacs-20.3.1\bin\cmdproxy.exe Steve -- Steven Tolkin tolkin@mediaone.net work: steve.tolkin@fmr.com Fidelity Investments 82 Devonshire St. R24D Boston MA 02109 617-563-0516 There is nothing so practical as a good theory. Comments are by me, not Fidelity Investments, its subsidiaries or affiliates. ```