Fix the documentation for the substr() function

[p5pRT]

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

Searchable as RT900$

[p5pRT]

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<or equal to> 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<not> 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 <tolkin@mediaone.net>

[p5pRT]

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<or equal to> 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<not> 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.