This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta tweaks on the shift.
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
fc4c3cec
RS
5[ this is a template for a new perldelta file. Any text flagged as XXX needs
6to be processed before release. ]
7
8perldelta - what is new for perl v5.23.1
eabfc7bc 9
2cfe9b50 10=head1 DESCRIPTION
eabfc7bc 11
fc4c3cec 12This document describes differences between the 5.23.0 release and the 5.23.1
2cfe9b50 13release.
eabfc7bc 14
fc4c3cec
RS
15If you are upgrading from an earlier release such as 5.22.0, first read
16L<perl5230delta>, which describes differences between 5.22.0 and 5.23.0.
17
18=head1 Notice
19
20XXX Any important notices here
21
2cfe9b50 22=head1 Core Enhancements
eabfc7bc 23
fc4c3cec
RS
24XXX New core language features go here. Summarize user-visible core language
25enhancements. Particularly prominent performance optimisations could go
26here, but most should go in the L</Performance Enhancements> section.
ac71d2a0 27
fc4c3cec 28[ List each enhancement as a =head2 entry ]
ac71d2a0 29
fb7e9cdd 30=head2 Integer shift (C<< << >> and C<< >> >>) now more explicitly defined
deaaea8c
JH
31
32Negative shifts are reverse shifts: left shift becomes right shift,
33and right shift becomes left shift.
34
35Shifting by the number of bits in a native integer (or more) is zero,
36except when the "overshift" is right shifting a negative value under
37C<use integer>, in which case the result is -1 (arithmetic shift).
38
39Until now negative shifting and overshifting have been undefined
40because they have relied on whatever the C implementation happens
fb7e9cdd 41to do. For example, for the overshift a common C behavior is
deaaea8c
JH
42"modulo shift":
43
44 1 >> 64 == 1 >> (64 % 64) == 1 >> 0 == 1 # Common C behavior.
45
46 # And the same for <<, while Perl now produces 0 for both.
47
48Now these behaviors are well-defined under Perl, regardless of what
49the underlying C implementation does. Note, however, that you cannot
fb7e9cdd
JH
50escape the native integer width, you need to know how far left you
51can go. You can use for example:
52
53 use Config;
54 my $wordbits = $Config{uvsize} * 8; # Or $Config{uvsize} << 3.
55
56If you need a more bits on the left shift, you can use for example
57the C<bigint> pragma, or the C<Bit::Vector> module from CPAN.
deaaea8c 58
7d380357
RS
59=head2 Postfix dereferencing is no longer experimental
60
1c2511e0
AC
61Using the C<postderef> and C<postderef_qq> features no longer emits a
62warning. Existing code that disables the C<experimental::postderef> warning
63category that they previously used will continue to work. The C<postderef>
64feature has no effect; all Perl code can use postfix dereferencing,
65regardless of what feature declarations are in scope. The C<5.24> feature
66bundle now includes the C<postderef_qq> feature.
7d380357 67
0d610ac1
AC
68=head2 printf and sprintf now allow reordered precision arguments
69
70That is, C<< sprintf '|%.*2$|', 2, 3 >> now returns C<|002|>. This extends
71the existing reordering mechanism (which allows reordering for arguments
72that are used as format fields, widths, and vector separators).
73
fc4c3cec 74=head1 Security
2ad792cd 75
fc4c3cec
RS
76XXX Any security-related notices go here. In particular, any security
77vulnerabilities closed should be noted here rather than in the
78L</Selected Bug Fixes> section.
79
80[ List each security issue as a =head2 entry ]
2ad792cd 81
2cfe9b50 82=head1 Incompatible Changes
eabfc7bc 83
ce4793f1
KW
84=head2 ASCII characters in variable names must now be all visible
85
86It was legal until now on ASCII platforms for variable names to contain
87non-graphical ASCII control characters (ordinals 0 through 31, and 127,
88which are the C0 controls and C<DELETE>). This usage has been
89deprecated since v5.20, and as of now causes a syntax error. The
90variables these names referred to are special, reserved by Perl for
91whatever use it may choose, now, or in the future. Each such variable
92has an alternative way of spelling it. Instead of the single
93non-graphic control character, a two character sequence beginning with a
94caret is used, like C<$^]> and C<${^GLOBAL_PHASE}>. Details are at
95L<perlvar>. It remains legal, though unwise and deprecated (raising a
96deprecation warning), to use certain non-graphic non-ASCII characters in
97variables names when not under S<C<use utf8>>. No code should do this,
98as all such variables are reserved by Perl, and Perl doesn't currently
99define any of them (but could at any time, without notice).
eabfc7bc 100
26230909
AC
101=head2 The C<autoderef> feature has been removed
102
103The experimental C<autoderef> feature (which allowed calling C<push>,
104C<pop>, C<shift>, C<unshift>, C<splice>, C<keys>, C<values>, and C<each> on
105a scalar argument) has been deemed unsuccessful. It has now been removed;
106trying to use the feature (or to disable the C<experimental::autoderef>
107warning it previously triggered) now yields an exception.
108
fc4c3cec 109=head1 Deprecations
eabfc7bc 110
fc4c3cec 111XXX Any deprecated features, syntax, modules etc. should be listed here.
eabfc7bc 112
fc4c3cec
RS
113=head2 Module removals
114
115XXX Remove this section if inapplicable.
116
117The following modules will be removed from the core distribution in a
118future release, and will at that time need to be installed from CPAN.
119Distributions on CPAN which require these modules will need to list them as
120prerequisites.
121
122The core versions of these modules will now issue C<"deprecated">-category
123warnings to alert you to this fact. To silence these deprecation warnings,
124install the modules in question from CPAN.
125
126Note that these are (with rare exceptions) fine modules that you are encouraged
127to continue to use. Their disinclusion from core primarily hinges on their
128necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
129not usually on concerns over their design.
130
131=over
132
133=item XXX
134
135XXX Note that deprecated modules should be listed here even if they are listed
136as an updated module in the L</Modules and Pragmata> section.
137
138=back
139
140[ List each other deprecation as a =head2 entry ]
141
142=head1 Performance Enhancements
143
144XXX Changes which enhance performance without changing behaviour go here.
145There may well be none in a stable release.
146
147[ List each enhancement as a =item entry ]
eabfc7bc 148
73d6481e 149=over 4
eabfc7bc 150
73d6481e 151=item *
eabfc7bc 152
fc4c3cec 153XXX
eabfc7bc 154
fc4c3cec 155=back
eabfc7bc 156
fc4c3cec 157=head1 Modules and Pragmata
eabfc7bc 158
fc4c3cec
RS
159XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
160go here. If Module::CoreList is updated, generate an initial draft of the
161following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
162for important changes should then be added by hand. In an ideal world,
163dual-life modules would have a F<Changes> file that could be cribbed.
eabfc7bc 164
fc4c3cec 165[ Within each section, list entries as a =item entry ]
eabfc7bc 166
fc4c3cec 167=head2 New Modules and Pragmata
eabfc7bc 168
fc4c3cec 169=over 4
eabfc7bc 170
73d6481e 171=item *
eabfc7bc 172
fc4c3cec 173XXX
eabfc7bc 174
fc4c3cec 175=back
eabfc7bc 176
fc4c3cec
RS
177=head2 Updated Modules and Pragmata
178
179=over 4
eabfc7bc
RS
180
181=item *
182
dc013420
SH
183L<autodie> has been upgraded from version 2.28 to 2.29.
184
185=item *
186
c85f23b2
DD
187L<IPC::Open3> has been upgraded from version 1.18 to 1.19.
188
189If a Perl exception was thrown from inside this module, the exception
779c45ce 190C<IPC::Open3> threw to the callers of C<open3> would have an irrelevant
c85f23b2
DD
191message derived from C<$!> which was in an undefined state, instead of the
192C<$@> message which triggers the failure path inside C<open3>.
eabfc7bc 193
6962a25d
SH
194=item *
195
196L<Unicode::Collate> has been upgraded from version 1.12 to 1.14.
197
0b8e4842
SH
198=item *
199
200L<Unicode::Normalize> has been upgraded from version 1.18 to 1.19.
201
fc4c3cec
RS
202=back
203
204=head2 Removed Modules and Pragmata
eabfc7bc 205
fc4c3cec 206=over 4
374c951f
SH
207
208=item *
209
fc4c3cec 210XXX
e586de20 211
fc4c3cec 212=back
e586de20 213
fc4c3cec 214=head1 Documentation
fd0a842f 215
fc4c3cec
RS
216XXX Changes to files in F<pod/> go here. Consider grouping entries by
217file and be sure to link to the appropriate page, e.g. L<perlfunc>.
fd0a842f 218
fc4c3cec 219=head2 New Documentation
99527ef1 220
fc4c3cec 221XXX Changes which create B<new> files in F<pod/> go here.
99527ef1 222
fc4c3cec 223=head3 L<XXX>
a4f8ff46 224
fc4c3cec 225XXX Description of the purpose of the new file here
a4f8ff46 226
fc4c3cec 227=head2 Changes to Existing Documentation
73d6481e 228
fc4c3cec
RS
229XXX Changes which significantly change existing files in F<pod/> go here.
230However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
231section.
232
233=head3 L<XXX>
73d6481e 234
fc4c3cec 235=over 4
eabfc7bc
RS
236
237=item *
238
fc4c3cec 239XXX Description of the change here
b7b593d8 240
fc4c3cec 241=back
b7b593d8 242
fc4c3cec 243=head1 Diagnostics
b7b593d8 244
fc4c3cec
RS
245The following additions or changes have been made to diagnostic output,
246including warnings and fatal error messages. For the complete list of
247diagnostic messages, see L<perldiag>.
b7b593d8 248
fc4c3cec
RS
249XXX New or changed warnings emitted by the core's C<C> code go here. Also
250include any changes in L<perldiag> that reconcile it to the C<C> code.
b7b593d8 251
fc4c3cec 252=head2 New Diagnostics
b7b593d8 253
fc4c3cec
RS
254XXX Newly added diagnostic messages go under here, separated into New Errors
255and New Warnings
b7b593d8 256
fc4c3cec
RS
257=head3 New Errors
258
259=over 4
eabfc7bc 260
ef5cf9f5
TC
261=item *
262
fc4c3cec 263XXX L<message|perldiag/"message">
72b8c7a2 264
fc4c3cec 265=back
72b8c7a2 266
fc4c3cec
RS
267=head3 New Warnings
268
269=over 4
bdb6acef
SH
270
271=item *
272
fc4c3cec 273XXX L<message|perldiag/"message">
ef5cf9f5 274
fc4c3cec 275=back
3d58dd24 276
fc4c3cec
RS
277=head2 Changes to Existing Diagnostics
278
279XXX Changes (i.e. rewording) of diagnostic messages go here
280
281=over 4
4b951711
TC
282
283=item *
284
0d610ac1
AC
285The C<printf> and C<sprintf> builtins are now more careful about the
286warnings they emit: argument reordering now disables the "redundant
287argument" warning in all cases; and invalid format strings are no longer
288treated as absorbing arguments (so "redundant argument" warnings can
289correctly be emitted by such code).
eabfc7bc 290
fc4c3cec 291=back
eabfc7bc 292
fc4c3cec 293=head1 Utility Changes
eabfc7bc 294
fc4c3cec
RS
295XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
296Most of these are built within the directory F<utils>.
eabfc7bc 297
fc4c3cec
RS
298[ List utility changes as a =head2 entry for each utility and =item
299entries for each change
300Use L<XXX> with program names to get proper documentation linking. ]
eabfc7bc 301
fc4c3cec
RS
302=head2 L<XXX>
303
304=over 4
eabfc7bc
RS
305
306=item *
307
fc4c3cec 308XXX
eabfc7bc 309
fc4c3cec 310=back
eabfc7bc 311
fc4c3cec 312=head1 Configuration and Compilation
eabfc7bc 313
fc4c3cec
RS
314XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
315go here. Any other changes to the Perl build process should be listed here.
316However, any platform-specific changes should be listed in the
317L</Platform Support> section, instead.
eabfc7bc 318
fc4c3cec 319[ List changes as a =item entry ].
eabfc7bc 320
fc4c3cec 321=over 4
eabfc7bc
RS
322
323=item *
324
fc4c3cec 325XXX
eabfc7bc 326
fc4c3cec 327=back
eabfc7bc 328
fc4c3cec 329=head1 Testing
eabfc7bc 330
fc4c3cec
RS
331XXX Any significant changes to the testing of a freshly built perl should be
332listed here. Changes which create B<new> files in F<t/> go here as do any
333large changes to the testing harness (e.g. when parallel testing was added).
334Changes to existing files in F<t/> aren't worth summarizing, although the bugs
335that they represent may be covered elsewhere.
336
337[ List each test improvement as a =item entry ]
338
339=over 4
eabfc7bc 340
fc4c3cec 341=item *
eabfc7bc 342
fc4c3cec 343XXX
eabfc7bc 344
2cfe9b50 345=back
33ca8d3c 346
73d6481e 347=head1 Platform Support
eabfc7bc 348
fc4c3cec 349XXX Any changes to platform support should be listed in the sections below.
eabfc7bc 350
fc4c3cec
RS
351[ Within the sections, list each platform as a =item entry with specific
352changes as paragraphs below it. ]
eabfc7bc 353
fc4c3cec 354=head2 New Platforms
42fe7840 355
fc4c3cec
RS
356XXX List any platforms that this version of perl compiles on, that previous
357versions did not. These will either be enabled by new files in the F<hints/>
358directories, or new subdirectories and F<README> files at the top level of the
359source tree.
360
361=over 4
42fe7840 362
fc4c3cec
RS
363=item XXX-some-platform
364
365XXX
42fe7840
CB
366
367=back
368
fc4c3cec 369=head2 Discontinued Platforms
eabfc7bc 370
fc4c3cec 371XXX List any platforms that this version of perl no longer compiles on.
269713a1 372
fc4c3cec 373=over 4
269713a1 374
fc4c3cec 375=item XXX-some-platform
269713a1 376
fc4c3cec 377XXX
463e63a4 378
fc4c3cec 379=back
463e63a4 380
fc4c3cec 381=head2 Platform-Specific Notes
9c0328ac 382
fc4c3cec
RS
383XXX List any changes for specific platforms. This could include configuration
384and compilation changes or changes in portability/compatibility. However,
385changes within modules for platforms should generally be listed in the
386L</Modules and Pragmata> section.
9c0328ac 387
fc4c3cec
RS
388=over 4
389
7d380357 390=item VMS
fc4c3cec 391
7d380357
RS
392=over
393
394=item *
395
396The minimum supported version of VMS is now v7.3-2, released in 2003. As a
397side effect of this change, VAX is no longer supported as the terminal
398release of OpenVMS VAX was v7.3 in 2001.
399
400=back
eabfc7bc 401
2cfe9b50 402=back
eabfc7bc 403
fc4c3cec
RS
404=head1 Internal Changes
405
406XXX Changes which affect the interface available to C<XS> code go here. Other
407significant internal changes for future core maintainers should be noted as
408well.
409
410[ List each change as a =item entry ]
eabfc7bc 411
2cfe9b50 412=over 4
eabfc7bc
RS
413
414=item *
415
0d610ac1
AC
416C<sv_catpvf> and related functions (including C<sv_vcatpvfn_flags> when
417called with a C<va_list> rather than an array of SV pointers) have never
418handled argument reordering. Attempts to reorder arguments now yield an
419exception, rather than being silently ignored.
eabfc7bc 420
fc4c3cec 421=back
302ef3d4 422
fc4c3cec 423=head1 Selected Bug Fixes
302ef3d4 424
fc4c3cec
RS
425XXX Important bug fixes in the core language are summarized here. Bug fixes in
426files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
eabfc7bc 427
fc4c3cec
RS
428[ List each fix as a =item entry ]
429
430=over 4
eabfc7bc 431
73d6481e 432=item *
eabfc7bc 433
7ed1d857
DD
434A leak in the XS typemap caused one scalar to be leaked each time a C<FILE *>
435or a C<PerlIO *> was C<OUTPUT:>ed or imported to Perl, since perl 5.000. These
436particular typemap entries are thought to be extremely rarely used by XS
437modules. [perl #124181]
eabfc7bc 438
fc4c3cec
RS
439=back
440
441=head1 Known Problems
442
443XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
444tests that had to be C<TODO>ed for the release would be noted here. Unfixed
445platform specific bugs also go here.
446
447[ List each fix as a =item entry ]
eabfc7bc 448
fc4c3cec
RS
449=over 4
450
451=item *
eabfc7bc 452
fc4c3cec 453XXX
eabfc7bc 454
73d6481e 455=back
eabfc7bc 456
fc4c3cec 457=head1 Errata From Previous Releases
eabfc7bc 458
fc4c3cec 459=over 4
eabfc7bc 460
fc4c3cec 461=item *
2a7a05b4 462
fc4c3cec
RS
463XXX Add anything here that we forgot to add, or were mistaken about, in
464the perldelta of a previous release.
30aa8e3f 465
fc4c3cec 466=back
30aa8e3f 467
fc4c3cec
RS
468=head1 Obituary
469
470XXX If any significant core contributor has died, we've added a short obituary
471here.
472
473=head1 Acknowledgements
2a7a05b4 474
fc4c3cec 475XXX Generate this with:
2cfe9b50 476
fc4c3cec 477 perl Porting/acknowledgements.pl v5.23.1..HEAD
f5b73711 478
44691e6f
AB
479=head1 Reporting Bugs
480
e08634c5
SH
481If you find what you think is a bug, you might check the articles recently
482posted to the comp.lang.perl.misc newsgroup and the perl bug database at
fc4c3cec
RS
483L<https://rt.perl.org/> . There may also be information at
484L<http://www.perl.org/> , the Perl Home Page.
44691e6f 485
e08634c5
SH
486If you believe you have an unreported bug, please run the L<perlbug> program
487included with your release. Be sure to trim your bug down to a tiny but
488sufficient test case. Your bug report, along with the output of C<perl -V>,
489will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
490
491If the bug you are reporting has security implications, which make it
e08634c5
SH
492inappropriate to send to a publicly archived mailing list, then please send it
493to perl5-security-report@perl.org. This points to a closed subscription
494unarchived mailing list, which includes all the core committers, who will be
495able to help assess the impact of issues, figure out a resolution, and help
f9001595 496co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
497platforms on which Perl is supported. Please only use this address for
498security issues in the Perl core, not for modules independently distributed on
499CPAN.
44691e6f
AB
500
501=head1 SEE ALSO
502
e08634c5
SH
503The F<Changes> file for an explanation of how to view exhaustive details on
504what changed.
44691e6f
AB
505
506The F<INSTALL> file for how to build Perl.
507
508The F<README> file for general stuff.
509
510The F<Artistic> and F<Copying> files for copyright information.
511
512=cut