"Fossies" - the Fresh Open Source Software Archive

Member "RPerl-5.002000/lib/RPerl/Learning.pm" (28 Nov 2019, 847816 Bytes) of package /linux/misc/RPerl-5.002000.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "Learning.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 5.000000_vs_5.002000.

    1 # [[[ HEADER ]]]
    2 use RPerl;
    3 package RPerl::Learning;
    4 use strict;
    5 use warnings;
    6 our $VERSION = 0.195_000;
    7 
    8 # [[[ OO INHERITANCE ]]]
    9 # NEED FIX: why does the following 'use parent' command cause $VERSION to become undefined???
   10 #use parent qw(RPerl::CompileUnit::Module::Class);
   11 #use RPerl::CompileUnit::Module::Class;
   12 
   13 # [[[ CRITICS ]]]
   14 ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
   15 ## no critic qw(ProhibitUnreachableCode RequirePodSections RequirePodAtEnd)  # DEVELOPER DEFAULT 1b: allow POD & unreachable or POD-commented code, must be after line 1
   16 
   17 # [[[ OO PROPERTIES ]]]
   18 our hashref $properties = {};
   19 
   20 1;    # end of class
   21 
   22 __END__
   23 
   24 =encoding utf8
   25 
   26 =for comment DEV NOTE: BEGIN INLINE CSS DIV
   27 
   28 =begin html
   29 
   30 <div id="scoped-content"><style type="text/css" scoped>
   31 
   32 table.rperl {
   33     border-style: solid;
   34     border-width: 2px;
   35 }
   36 
   37 table.rperl > tbody > tr > th {
   38     background-color: #e0e0e0;
   39     text-align: center;
   40 }
   41 
   42 table.rperl > tbody > tr:nth-child(odd)  { background-color: #f5f5f5; }
   43 table.rperl > tbody > tr:nth-child(even) { background-color: #ffffff; }
   44 
   45 table.rperl > tbody > tr > th, td {
   46     border-style: solid;
   47     border-width: 1px;
   48     border-color: #cccccc;
   49     padding: 5px;
   50 }
   51 
   52 /* disable ".pod p" margins inside tables only */
   53 table.rperl > tbody > tr > th > p { margin: 0px; }
   54 table.rperl > tbody > tr > td > p { margin: 0px; }
   55 
   56 /* right alignment for numeric precedence column of operators tables */
   57 table.operators > tbody > tr > td:nth-child(5)  { text-align: right; }
   58 
   59 </style>
   60 
   61 =end html
   62 
   63 =head1 NAME
   64 
   65 Learning RPerl
   66 
   67 =head1 COPYRIGHT
   68 
   69 Learning RPerl is Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019 William N. Braswell, Jr.
   70 All Rights Reserved.
   71 
   72 Learning RPerl is part of the RPerl Family of software and documentation.
   73 
   74 =head1 BOOK TITLE
   75 
   76 =begin text
   77 
   78     .;,..                                                                                                                                               
   79     .2prp02;'.                                                                                                                                          
   80       ,0LRRRLLp1;.                                                                                                                                      
   81       .,20LRPEEPRL02'.                                                                                                                                  
   82         .'2rREEEEPRRLp1:,.                                                                                                                              
   83            .1pLRPEEEPRRLLrl;.                                                                                                                           
   84             .;2lpLREEEEEPRRLpl2,.                                                                                                                       
   85              .':lrLPEEEPPPPPRRLLpl:,.                                                                                                                   
   86                 .'20LRPPPPPPPEEPRLLrpl:'.                                                                                                               
   87                     .2rLRPPRRPPPEEPRRLLrp1;'.                                                                                                           
   88                       .;lpLRRRRRPPPEEEPLLLrr0:'.                                                                                                        
   89                          .,1LRRRLLRPPPRRRRLLLrr01,.                                                                                                     
   90                             .,1pLRRRRLLRRRRRLLLLrrpl:'.                                                                                                 
   91                                 .:lrLRRLLRLLLLLLLrrrrp02,.                                                                                              
   92                                    ..:lpLRRRRLLLLLLLrppp002,.                                                                                           
   93                                        .';1pLLRRLLLrpprpp0ppl2,.                                                                                        
   94                                            .'1prLRRLLrpprLrrrLLL0:.                                                        ....                         
   95                                              ..;1pLLLLLLLLLLLLLLLLr0:.                                                   '0LLLLr01;..                   
   96                                                 .;20rrrLLLLLLLLrprLLLrl:'.                                              'rEEEEEEEEPRL1,.                
   97                                                    .':10pLLLLLLLLLrp0pprp02;..                                          ;LPPEPPEEPPPRLLp2.              
   98                                                        .';1rLLrrrrpppp0000pp0l1;'..            ...',;::2222222::;,'..    2REEPPPPPPRRLLrrp2.            
   99                                                            .,20rLLrrrrrpppppprrrrrrrpl2:221lppprLLRPPPPEEEEEEEEEEPERLL021LEEPPLrprrprrpppLL0.           
  100                                                                .,1prprprrrLLLLRPPPEEEEPPPPPPRPPRRRRRLLRRPE333EEEE3EE33333EPRPERLpppprp000prLp1:,..      
  101                                                                   .,20rrppLRPPEEEEEEEEEEEEPPRRRRLLLLLLLRRPPPPPRRRPPEE33333PREEEEEPRLppp0pplll0p0001:'.  
  102                                                                      .';20LPEEEEEEEEE3EEEEEPPRRLLLLLLLLLLRRLLLLLLLRPPEPPEEERLLLLLLLrrrpl0l;'..'',;;::,. 
  103                                                                          '0LPEEEEEEEEEEPRRPPPRRRRLLLLrrLLrrLrprLLLrrLLLrLLL010prrLLrpp00:.              
  104                                                                            ;rRPEE3EPPEERLLLLRPPLLLLLrrp0ll0p0l0p0l112:1lll2:1lll0l0pLLRp.               
  105                                                                             ':lREPPEPPPRLRPEERLLLLrprLLLr0ll01:1l1::12::::2::2::::1120L0.               
  106                                                                           .:0prLPPPPRLLRPPRRLLLrrrLLLLRRPLpll2:;::;,:12::::,,,;;;::;:200,               
  107                                                                         .:0LLRRRPRPEPLLLLRRLrrLRRRRRLLLLrpp00l2:2222112211:,,,'',;:,,2l0,               
  108                                                                          ...'',:1lpLRRLRLLLLLLLREEEEERrppppp0ppl11lp0pp0012:;;,,;;;,;2l1.               
  109                                                                                    .,1rRPPPPPPRRPEEEEPLrLLrrpprLLLLrrrLrrp1:;;,;::;;20l;                
  110                                                                                       .:LEEEPRrpppppppppprLLRPPPRRRRRLrrp0l2222::22101'                 
  111                                                                                         'rPPPLplll121llll0pprrrpppprLr0l12222221lll2'.                  
  112                                                                                          .;0PPRLLrpll11222:;;,,,,:10rrrrrrrp0ll1:;.                     
  113                                                                                            .1RLrRRLLr02:;,........,;:;;;;;,'..                          
  114                                                                                              2r22rLrpp1;.                                               
  115                                                                                              .lL2;1l12'                                                 
  116                                                                                               .0L;.2L0.                                                 
  117                                                                                          ,2:'. ,rp;,0L0.   .,2;..                                       
  118                                                                                          .:1l00pLLrprRPp2221ll,.                                        
  119                                                                                           .',,;;;,,;:10Lr1'.                                            
  120                                                                                                        '0l'                                             
  121                                                                                                         .ll'                                            
  122                                                                                                     ':::2pp1:,.....',.                                  
  123                                                                                                  ..'';2ll1;,;::21l111;..                                
  124                                                                                                  ..,'...       ...',;;...                               
  125 
  126 =end text
  127 
  128 =begin man
  129 
  130     .;,..                                                                                                                                               
  131     .2prp02;'.                                                                                                                                          
  132       ,0LRRRLLp1;.                                                                                                                                      
  133       .,20LRPEEPRL02'.                                                                                                                                  
  134         .'2rREEEEPRRLp1:,.                                                                                                                              
  135            .1pLRPEEEPRRLLrl;.                                                                                                                           
  136             .;2lpLREEEEEPRRLpl2,.                                                                                                                       
  137              .':lrLPEEEPPPPPRRLLpl:,.                                                                                                                   
  138                 .'20LRPPPPPPPEEPRLLrpl:'.                                                                                                               
  139                     .2rLRPPRRPPPEEPRRLLrp1;'.                                                                                                           
  140                       .;lpLRRRRRPPPEEEPLLLrr0:'.                                                                                                        
  141                          .,1LRRRLLRPPPRRRRLLLrr01,.                                                                                                     
  142                             .,1pLRRRRLLRRRRRLLLLrrpl:'.                                                                                                 
  143                                 .:lrLRRLLRLLLLLLLrrrrp02,.                                                                                              
  144                                    ..:lpLRRRRLLLLLLLrppp002,.                                                                                           
  145                                        .';1pLLRRLLLrpprpp0ppl2,.                                                                                        
  146                                            .'1prLRRLLrpprLrrrLLL0:.                                                        ....                         
  147                                              ..;1pLLLLLLLLLLLLLLLLr0:.                                                   '0LLLLr01;..                   
  148                                                 .;20rrrLLLLLLLLrprLLLrl:'.                                              'rEEEEEEEEPRL1,.                
  149                                                    .':10pLLLLLLLLLrp0pprp02;..                                          ;LPPEPPEEPPPRLLp2.              
  150                                                        .';1rLLrrrrpppp0000pp0l1;'..            ...',;::2222222::;,'..    2REEPPPPPPRRLLrrp2.            
  151                                                            .,20rLLrrrrrpppppprrrrrrrpl2:221lppprLLRPPPPEEEEEEEEEEPERLL021LEEPPLrprrprrpppLL0.           
  152                                                                .,1prprprrrLLLLRPPPEEEEPPPPPPRPPRRRRRLLRRPE333EEEE3EE33333EPRPERLpppprp000prLp1:,..      
  153                                                                   .,20rrppLRPPEEEEEEEEEEEEPPRRRRLLLLLLLRRPPPPPRRRPPEE33333PREEEEEPRLppp0pplll0p0001:'.  
  154                                                                      .';20LPEEEEEEEEE3EEEEEPPRRLLLLLLLLLLRRLLLLLLLRPPEPPEEERLLLLLLLrrrpl0l;'..'',;;::,. 
  155                                                                          '0LPEEEEEEEEEEPRRPPPRRRRLLLLrrLLrrLrprLLLrrLLLrLLL010prrLLrpp00:.              
  156                                                                            ;rRPEE3EPPEERLLLLRPPLLLLLrrp0ll0p0l0p0l112:1lll2:1lll0l0pLLRp.               
  157                                                                             ':lREPPEPPPRLRPEERLLLLrprLLLr0ll01:1l1::12::::2::2::::1120L0.               
  158                                                                           .:0prLPPPPRLLRPPRRLLLrrrLLLLRRPLpll2:;::;,:12::::,,,;;;::;:200,               
  159                                                                         .:0LLRRRPRPEPLLLLRRLrrLRRRRRLLLLrpp00l2:2222112211:,,,'',;:,,2l0,               
  160                                                                          ...'',:1lpLRRLRLLLLLLLREEEEERrppppp0ppl11lp0pp0012:;;,,;;;,;2l1.               
  161                                                                                    .,1rRPPPPPPRRPEEEEPLrLLrrpprLLLLrrrLrrp1:;;,;::;;20l;                
  162                                                                                       .:LEEEPRrpppppppppprLLRPPPRRRRRLrrp0l2222::22101'                 
  163                                                                                         'rPPPLplll121llll0pprrrpppprLr0l12222221lll2'.                  
  164                                                                                          .;0PPRLLrpll11222:;;,,,,:10rrrrrrrp0ll1:;.                     
  165                                                                                            .1RLrRRLLr02:;,........,;:;;;;;,'..                          
  166                                                                                              2r22rLrpp1;.                                               
  167                                                                                              .lL2;1l12'                                                 
  168                                                                                               .0L;.2L0.                                                 
  169                                                                                          ,2:'. ,rp;,0L0.   .,2;..                                       
  170                                                                                          .:1l00pLLrprRPp2221ll,.                                        
  171                                                                                           .',,;;;,,;:10Lr1'.                                            
  172                                                                                                        '0l'                                             
  173                                                                                                         .ll'                                            
  174                                                                                                     ':::2pp1:,.....',.                                  
  175                                                                                                  ..'';2ll1;,;::21l111;..                                
  176                                                                                                  ..,'...       ...',;;...                               
  177 
  178 =end man
  179 
  180 =for man
  181 
  182 =begin docbook
  183 
  184     .;,..                                                                                                                                               
  185     .2prp02;'.                                                                                                                                          
  186       ,0LRRRLLp1;.                                                                                                                                      
  187       .,20LRPEEPRL02'.                                                                                                                                  
  188         .'2rREEEEPRRLp1:,.                                                                                                                              
  189            .1pLRPEEEPRRLLrl;.                                                                                                                           
  190             .;2lpLREEEEEPRRLpl2,.                                                                                                                       
  191              .':lrLPEEEPPPPPRRLLpl:,.                                                                                                                   
  192                 .'20LRPPPPPPPEEPRLLrpl:'.                                                                                                               
  193                     .2rLRPPRRPPPEEPRRLLrp1;'.                                                                                                           
  194                       .;lpLRRRRRPPPEEEPLLLrr0:'.                                                                                                        
  195                          .,1LRRRLLRPPPRRRRLLLrr01,.                                                                                                     
  196                             .,1pLRRRRLLRRRRRLLLLrrpl:'.                                                                                                 
  197                                 .:lrLRRLLRLLLLLLLrrrrp02,.                                                                                              
  198                                    ..:lpLRRRRLLLLLLLrppp002,.                                                                                           
  199                                        .';1pLLRRLLLrpprpp0ppl2,.                                                                                        
  200                                            .'1prLRRLLrpprLrrrLLL0:.                                                        ....                         
  201                                              ..;1pLLLLLLLLLLLLLLLLr0:.                                                   '0LLLLr01;..                   
  202                                                 .;20rrrLLLLLLLLrprLLLrl:'.                                              'rEEEEEEEEPRL1,.                
  203                                                    .':10pLLLLLLLLLrp0pprp02;..                                          ;LPPEPPEEPPPRLLp2.              
  204                                                        .';1rLLrrrrpppp0000pp0l1;'..            ...',;::2222222::;,'..    2REEPPPPPPRRLLrrp2.            
  205                                                            .,20rLLrrrrrpppppprrrrrrrpl2:221lppprLLRPPPPEEEEEEEEEEPERLL021LEEPPLrprrprrpppLL0.           
  206                                                                .,1prprprrrLLLLRPPPEEEEPPPPPPRPPRRRRRLLRRPE333EEEE3EE33333EPRPERLpppprp000prLp1:,..      
  207                                                                   .,20rrppLRPPEEEEEEEEEEEEPPRRRRLLLLLLLRRPPPPPRRRPPEE33333PREEEEEPRLppp0pplll0p0001:'.  
  208                                                                      .';20LPEEEEEEEEE3EEEEEPPRRLLLLLLLLLLRRLLLLLLLRPPEPPEEERLLLLLLLrrrpl0l;'..'',;;::,. 
  209                                                                          '0LPEEEEEEEEEEPRRPPPRRRRLLLLrrLLrrLrprLLLrrLLLrLLL010prrLLrpp00:.              
  210                                                                            ;rRPEE3EPPEERLLLLRPPLLLLLrrp0ll0p0l0p0l112:1lll2:1lll0l0pLLRp.               
  211                                                                             ':lREPPEPPPRLRPEERLLLLrprLLLr0ll01:1l1::12::::2::2::::1120L0.               
  212                                                                           .:0prLPPPPRLLRPPRRLLLrrrLLLLRRPLpll2:;::;,:12::::,,,;;;::;:200,               
  213                                                                         .:0LLRRRPRPEPLLLLRRLrrLRRRRRLLLLrpp00l2:2222112211:,,,'',;:,,2l0,               
  214                                                                          ...'',:1lpLRRLRLLLLLLLREEEEERrppppp0ppl11lp0pp0012:;;,,;;;,;2l1.               
  215                                                                                    .,1rRPPPPPPRRPEEEEPLrLLrrpprLLLLrrrLrrp1:;;,;::;;20l;                
  216                                                                                       .:LEEEPRrpppppppppprLLRPPPRRRRRLrrp0l2222::22101'                 
  217                                                                                         'rPPPLplll121llll0pprrrpppprLr0l12222221lll2'.                  
  218                                                                                          .;0PPRLLrpll11222:;;,,,,:10rrrrrrrp0ll1:;.                     
  219                                                                                            .1RLrRRLLr02:;,........,;:;;;;;,'..                          
  220                                                                                              2r22rLrpp1;.                                               
  221                                                                                              .lL2;1l12'                                                 
  222                                                                                               .0L;.2L0.                                                 
  223                                                                                          ,2:'. ,rp;,0L0.   .,2;..                                       
  224                                                                                          .:1l00pLLrprRPp2221ll,.                                        
  225                                                                                           .',,;;;,,;:10Lr1'.                                            
  226                                                                                                        '0l'                                             
  227                                                                                                         .ll'                                            
  228                                                                                                     ':::2pp1:,.....',.                                  
  229                                                                                                  ..'';2ll1;,;::21l111;..                                
  230                                                                                                  ..,'...       ...',;;...                               
  231 
  232 =end docbook
  233 
  234 =for html <img src="http://www.rperl.org/images/roadrunner_engraving.jpg" width="90%">
  235 
  236 =for html <u>
  237 
  238 B<Learning RPerl>
  239 
  240 =for html </u>
  241 
  242 ~ or ~
  243 
  244 =for html <u>
  245 
  246 B<Let's Write Fast Perl!>
  247 
  248 =for html </u>
  249 
  250 ~ affectionately known as ~
  251 
  252 =for html <u>
  253 
  254 B<The Roadrunner Book>
  255 
  256 =for html </u>
  257 
  258 .
  259 X<br>
  260 
  261 ...
  262 X<br>
  263 
  264 .....
  265 X<br>
  266 
  267 .......
  268 X<br>
  269 
  270 being
  271 X<br>
  272 
  273 .......
  274 X<br>
  275 
  276 .....
  277 X<br>
  278 
  279 ...
  280 X<br>
  281 
  282 .
  283 
  284 B<The Official Introductory-Level Reference, User Manual, and Educational Documentation>
  285 
  286 ~ for ~
  287 
  288 B<Restricted Perl, The Optimizing Perl 5 Compiler>
  289 
  290 X<br>
  291 
  292 
  293 =head1 DEDICATION
  294 
  295 For Anna.
  296 
  297 X<br>
  298 
  299 
  300 =head1 EDITION
  301 
  302 0th Edition, Pre-Release Copy
  303 
  304 X<br>
  305 
  306 
  307 =head1 TABLE OF CONTENTS: CHAPTERS AT-A-GLANCE
  308 
  309 =over
  310 
  311 =item * L</FOREWORD>
  312 
  313 =item * L</PREFACE>
  314 
  315 =item * L</CHAPTER 1: INTRODUCTION>
  316 
  317 =item * L</CHAPTER 2: SCALAR VALUES & VARIABLES (NUMBERS & TEXT)>
  318 
  319 =item * L</CHAPTER 3: ARRAY VALUES & VARIABLES>
  320 
  321 =item * L</CHAPTER 4: ORGANIZING BY SUBROUTINES>
  322 
  323 =item * L</CHAPTER 5: READING & WRITING FILES>
  324 
  325 =item * L</CHAPTER 6: HASH VALUES & VARIABLES>
  326 
  327 =item * L</CHAPTER 7: THE REGULAR EXPRESSION SUB-LANGUAGE>
  328 
  329 =item * L</CHAPTER 8: MATCHING BY REGULAR EXPRESSIONS>
  330 
  331 =item * L</CHAPTER 9: PROCESSING BY REGULAR EXPRESSIONS>
  332 
  333 =item * L</CHAPTER 10: ADDITIONAL CONTROL STRUCTURES>
  334 
  335 =item * L</CHAPTER 11: CLASSES, PACKAGES, MODULES, LIBRARIES>
  336 
  337 =item * L</CHAPTER 12: TESTING FILES & DIRECTORIES>
  338 
  339 =item * L</CHAPTER 13: MANIPULATING FILES & DIRECTORIES>
  340 
  341 =item * L</CHAPTER 14: SORTING TEXT VALUES>
  342 
  343 =item * L</CHAPTER 15: ADDITIONAL SPECIAL OPERATORS>
  344 
  345 =item * L</CHAPTER 16: MANAGING OPERATING SYSTEM PROCESSES>
  346 
  347 =item * L</CHAPTER 17: ADDITIONAL ADVANCED TECHNIQUES>
  348 
  349 =item * L</APPENDIX A: EXERCISE ANSWERS>
  350 
  351 =item * L</APPENDIX B: RPERL COMMAND-LINE ARGUMENTS>
  352 
  353 =item * L</APPENDIX C: RPERL CRITICS>
  354 
  355 =item * L</APPENDIX D: RPERL GRAMMAR>
  356 
  357 =item * L</APPENDIX E: BEYOND THE ROADRUNNER>
  358 
  359 =back
  360 
  361 X<br>
  362 
  363 
  364 =head1 FOREWORD
  365 
  366 [ INSERT FOREWORD CONTENT HERE ]
  367 
  368 X<br>
  369 
  370 
  371 =head1 PREFACE
  372 
  373 =head2 Section 0.1: Who I Am
  374 
  375 My name is William N. Braswell, Jr.; I am also known by a number of other names including Will the Chill, The Voice In The Wilderness, Skipper Brassie ("braz-ee"), and just Will.
  376 
  377 I have a degree in computer science and mathematics from Texas Tech University, I have worked as a Perl software developer for over 15 years, and I am the founder of the Auto-Parallel Technologies consulting company.
  378 
  379 L<LinkedIn Profile|https://www.linkedin.com/in/williambraswell>
  380 
  381 L<GitHub Profile|https://github.com/wbraswell>
  382 
  383 I am 1 of 3 co-founders of the Perl 11 movement.
  384 
  385 L<Perl11.org|http://perl11.org/>
  386 
  387 I am also the President of the Austin Perl Mongers.
  388 
  389 L<Austin.pm|http://austin.pm>
  390 
  391 Most importantly, I am the creator of the RPerl optimizing compiler for Perl 5, about which you are currently reading!
  392 
  393 L<RPerl.org|http://rperl.org>
  394 
  395 =head2 Section 0.2: Why I Wrote This Book
  396 
  397 Using RPerl is different enough from normal Perl 5 to necessitate the creation of in-depth user documentation.
  398 
  399 Manual pages and cookbooks and example source code alone are not enough, only a full textbook can provide the level of detail necessary to truly learn RPerl.
  400 
  401 This is that textbook.
  402 
  403 =head2 Section 0.3: History Of This Book
  404 
  405 RPerl v1.0 was released on US Independence Day, July 4th, 2015; 6 days later, work began on the source code solution to exercise 1 of chapter 1 of this book:
  406 
  407 L<First Learning RPerl Commit on GitHub|https://github.com/wbraswell/rperl/commit/8c3dec4448fbed6bba04f92f9f23759c5512f2e9>
  408 
  409 Significant GitHub commit dates may be viewed by forking the RPerl git repository and executing the following C<git> command:
  410 
  411 =for rperl X<noncode>
  412 
  413     $ git log --reverse --all --date=short --pretty='%cd: %s' | grep 'Learning RPerl'
  414     2015-07-10: Learning RPerl, Chapter 1, Exercise 1, Hello World
  415     ...
  416 
  417 =for rperl X</noncode>
  418 
  419 =head2 Section 0.4: TPF Grants
  420 
  421 This book was made possible in part by 2 generous grants from The Perl Foundation, as part of the September 2015 and January / February 2016 rounds of funding.
  422 
  423 Special thanks to TPF Grants Committee Secretary, Makoto Nozaki; TPF Grant Manager, Mark Jensen; TPF Grants Committee's various supporting members; and everyone who gave positive feedback on the grant proposals.
  424 
  425 A history of TPF grant #1 may be found at the following links:
  426 
  427 =over 16
  428 
  429 =item * L<Call For Grant Proposals|http://news.perlfoundation.org/2015/09/call-for-grant-proposals-sept.html>
  430 
  431 =item * L<Grant Proposal|http://news.perlfoundation.org/2015/09/grant-proposal-rperl-user-docu.html>
  432 
  433 =item * L<Grant Proposals|http://news.perlfoundation.org/2015/09/september-2015-grant-proposals-1.html>
  434 
  435 =item * L<Grant Proposal Votes|http://news.perlfoundation.org/2015/10/september-2015-grant-votes.html>
  436 
  437 =item * L<Grant Report 1|http://news.perlfoundation.org/2015/10/grant-report-rperl-user-docume.html>
  438 
  439 =item * L<Grant Report 2|http://news.perlfoundation.org/2015/12/grant-report-rperl-user-docume-1.html>
  440 
  441 =item * L<Grant Report 3|http://news.perlfoundation.org/2016/01/grant-report-rperl-user-docume-2.html>
  442 
  443 =back
  444 
  445 A history of TPF grant #2 may be found at the following links:
  446 
  447 =over 16
  448 
  449 =item * L<Grant Proposal: RPerl User Documentation, Part 2|http://news.perlfoundation.org/2016/02/grant-proposal-rperl-user-docu-1.html>
  450 
  451 =item * L<Jan E<sol> Feb 2016 Grant Votes|http://news.perlfoundation.org/2016/02/janfeb-2016-grant-votes.html>
  452 
  453 =back
  454 
  455 =head2 Section 0.5: Acknowledgements & Thanks
  456 
  457 Countless people have contributed to the development of RPerl; from source code to bug testing to financial donations to emotional support, it truly takes a village to build a compiler!
  458 
  459 Below are the contents of the official RPerl thank-you file, listing the handles (online nicknames) and names of the most important RPerl contributors.  If you don't already know who these people are, you will be pleasantly surprised by researching each of them.
  460 
  461 L<Latest THANKS File|https://github.com/wbraswell/rperl/blob/master/THANKS>
  462 
  463 =for rperl X<noncode>
  464 
  465     Many Thanks To irc.perl.org:
  466 
  467     #perl5 Founder timtoady
  468 
  469     #perl6 Founder timtoady (again)
  470 
  471     #perl11 Founders ingy & rurban & willthechill (yours truly)
  472 
  473     #perl11 Members bulk88 & mst
  474 
  475     #inline Founders ingy (again) & nwatkiss
  476 
  477     #inline Members davido & mohawk & sisyphus
  478 
  479 
  480     Additional Thanks To:
  481 
  482     Eyapp Creator Casiano Rodriguez-Leon, PhD
  483 
  484     Austin Perl Mongers
  485 
  486     All RPerl Contributors & Users & Supporters
  487 
  488 =for rperl X</noncode>
  489 
  490 =head2 Section 0.6: Defense / Apology
  491 
  492 I'm sure I will make errors while writing this book.
  493 
  494 I may even upset some people, particularly those who have an emotional or financial investment in slow Perl software.
  495 
  496 Despite my best efforts, I remain a fallible human being; thus, bad spelling and grammer and run-on sentences and parts that are hard to understand and parts that are not funny and formattiNg errors and bad spelling adn repetitions and other annoyances will doubtless plague this tome but we must not allow such trivialities as, improper punctuation to affect our willingness and ability to learn how to write super-fast RPerl software.
  497 
  498 If you find a mistake in this book (other than in the immediately preceding paragraph), please utilize the following link to create a new GitHub issue (bug report) using a title starting with the words "Learning RPerl":
  499 
  500 L<New GitHub Issue|https://github.com/wbraswell/rperl/issues/new>
  501 
  502 I will try my best to create an engaging and educational experience for you, the reader; however, in anticipation of the inevitable disappointment you may experience, I can only humbly offer...
  503 
  504 B<I'M SORRY!>
  505 
  506 =head2 Section 0.7: POD
  507 
  508 "The Pod format is not necessarily sufficient for writing a book."
  509 
  510 L<http://perldoc.perl.org/perlpod.html>
  511 
  512 ~ Saint Larry Wall & Sean M. Burke
  513 
  514 X<br>
  515 
  516 "Challenge accepted."
  517 
  518 L<https://github.com/wbraswell/rperl/blob/master/script/development/pod2rperlhtml.pl>
  519 
  520 ~ Will Braswell
  521 
  522 X<br>
  523 
  524 
  525 =head1 CHAPTER 1: INTRODUCTION
  526 
  527 =head2 Section 1.1: Welcome To The Roadrunner Book!
  528 
  529 You are about to learn the basic concepts of writing software using the RPerl optimizing compiler for the Perl computer programming language.  With the skills gained by reading this book, you will be empowered to create new super-fast RPerl programs which can be intermixed with the enormous amount of existing Perl software available on the Internet.
  530 
  531 This book is named and stylized for the animal mascot for RPerl, Roadie the Roadrunner.  RPerl, like Roadie, I<"runs really fast">.
  532 
  533 Throughout this text, the following 14 typography conventions are utilized:
  534 
  535 =over
  536 
  537 =item * "Literal Quotation"
  538 
  539 =item * I<"First Occurrence Of Key Concept">
  540 
  541 =item * I<Emphasis>
  542 
  543 =item * B<Stronger Emphasis>
  544 
  545 =item * F</path/to/program.pl>
  546 
  547 =item * B<I<Program Name>>
  548 
  549 =for html <u>
  550 
  551 =item * B<Book Or Document Title>
  552 
  553 =item * I<BEST PRACTICES>
  554 
  555 =for html </u>
  556 
  557 =item * L<Hyperlink|http://rperl.org>
  558 
  559 =item * C<$code_snippet = 'unhighlighted';>
  560 
  561 =item * C<`command_line_program.pl --with --arguments`>  (Only Include Characters Between `Backquotes` When Running Command; Discard Backquote Characters Themselves)
  562 
  563 =item * ...
  564 
  565     my string $code_block = 'highlighted on RPerl.org & MetaCPAN.org';  # with comments
  566     my integer $more_code = 17;  # http://www.catb.org/jargon/html/R/random-numbers.html
  567     return 'end of indented code block';
  568 
  569 =item * ...
  570 
  571 =for rperl X<noncode>
  572 
  573     $ command_line_program.pl --with --arguments
  574     Please provide input: foo bar
  575     Your output is:       howdy howdy howdy
  576 
  577 =for rperl X</noncode>
  578 
  579 =item * ...
  580 
  581 =for rperl X<noncode>
  582 
  583     Documentation referring to `command_line_program.pl --with --arguments` among other things.
  584     When executed, the above command accepts as input the string 'foo bar',
  585     and displays as output the string 'howdy howdy howdy'.
  586 
  587 =for rperl X</noncode>
  588 
  589 =back
  590 
  591 =head2 Section 1.2: Learning Perl
  592 
  593 =begin text
  594 
  595 This book is purposefully patterned after the popular educational text B<Learning Perl>, affectionately known as the Llama Book.  Both the Roadrunner Book and the Llama book are meant as introductory texts on Perl topics.  The Llama Book is focused on normal Perl, and the Roadrunner Book is focused on optimized Perl.
  596 
  597 This book copies the same chapter topics as B<Learning Perl>, but all content is re-written for RPerl.  B<Learning RPerl> also copies the same exercise concepts as B<Learning Perl>, but all solutions are re-written in RPerl.  Both books are canonical and may be used together in the classroom; the source code solutions are meant to be compared side-by-side as textbook examples of normal Perl versus optimized Perl.
  598 
  599 Please support the Perl community by purchasing a copy of B<Learning Perl, 7th Edition> from our friends at O'Reilly:
  600 
  601 =end text
  602 
  603 =begin html
  604 
  605 <p>This book is purposefully patterned after the popular educational text <u><b>Learning Perl</b></u>, affectionately known as the Llama Book.  Both the Roadrunner Book and the Llama book are meant as introductory texts on Perl topics.  The Llama Book is focused on normal Perl, and the Roadrunner Book is focused on optimized Perl.</p>
  606 
  607 <p>This book copies the same chapter topics as <u><b>Learning Perl</b></u>, but all content is re-written for RPerl.  <u><b>Learning RPerl</b></u> also copies the same exercise concepts as <u><b>Learning Perl</b></u>, but all solutions are re-written in RPerl.  Both books are canonical and may be used together in the classroom; the source code solutions are meant to be compared side-by-side as textbook examples of normal Perl versus optimized Perl.</p>
  608 
  609 <p>Please support the Perl community by purchasing a copy of <u><b>Learning Perl, 7th Edition</b></u> from our friends at O'Reilly:</p>
  610 
  611 =end html
  612 
  613 L<http://shop.oreilly.com/product/0636920049517.do>
  614 
  615 =head2 Section 1.3: Is This Book A Good Choice For You?
  616 
  617 =over
  618 
  619 =item * Are you totally new to computer programming, and you want to learn how to write your first program?
  620 
  621 =item * Do you already know Perl, and now you want to make your Perl code run faster?
  622 
  623 =item * Do you already know some other computer language, and Perl has always intrigued you?
  624 
  625 =item * Do you love learning about new languages and compilers?
  626 
  627 =item * Do you miss your favorite old language Perl, and you're looking for a legitimate reason to go back?
  628 
  629 =item * Are you a scientist and you just want your code to run really fast without the headaches of C or C++?
  630 
  631 =back
  632 
  633 If you answered "yes" to any of these questions, then the Roadrunner Book is definitely for you!
  634 
  635 If you answered "no" to all of these questions, then this book may still be for you, give it a try!
  636 
  637 If you hate Perl, or only love slow software, or wish all computers would explode, then we suggest some soul-searching and a L<few|https://www.youtube.com/watch?v=UScm9avQM1Y> L<Saint|https://www.youtube.com/watch?v=SKqBmAHwSkg> L<Larry|https://www.youtube.com/watch?v=G49RUPv5-NU> L<videos|https://www.youtube.com/watch?v=aNAtbYSxzuA>.  You'll thank us in the morning.
  638 
  639 =head2 Section 1.4: Why Aren't There More Footnotes?
  640 
  641 This is a purposefully simple book, in the same way RPerl is a purposefully simple subset of the full Perl 5 programming language.
  642 
  643 =head2 Section 1.5: What About Educational Programming Exercises?
  644 
  645 There are one or more programming exercises at the end of every chapter, and full answers to each problem are given near the end of the book in Appendix A.
  646 
  647 For maximum educational effect, we suggest you attempt to write each piece of code on your own before looking at our solutions.
  648 
  649 If you are using this as an official textbook for certification or academic credit, such as at LAMPuniversity.org or a traditional school, you are obviously expected to write all your own code without referring to our or anyone else's solutions whatsoever.  We suggest you enclose Appendix A with a paper clip or discard it altogether to avoid the potential for accidental academic dishonesty.
  650 
  651 =head2 Section 1.6: How Long Should Each Exercise Take To Complete?
  652 
  653 The numbers at the beginning of each exercise indicate the approximate number of minutes required for an average person to reach a full working solution.  If it takes you less time, good for you!  If it takes you more time, don't worry, it's no big deal; learning technical skills requires time and dedication.  All experts were once novices.
  654 
  655 =head2 Section 1.7: What If I Want To Teach RPerl?
  656 
  657 Thank you for helping spread the love of Perl and the speed of RPerl!
  658 
  659 As previously mentioned, this book may either be used solo or combined with the Llama Book.  For students who are not already familiar with Perl, you may wish to use this text alone in order to simplify and ease the learning experience.  For students who are already familiar with Perl or other dynamic programming languages like the snake or the red gemstone, you may wish to use both textbooks for a more in-depth compare-and-contrast approach.
  660 
  661 =head2 Section 1.8: What Does The Name RPerl Actually Mean?
  662 
  663 RPerl stands for I<"Restricted Perl">, in that we restrict our use of Perl to those parts which can be made to run fast.  RPerl also stands for I<"Revolutionary Perl">, in that we hope RPerl's speed will revolutionize the software development industry, or at least the Perl community.  RPerl might even stand for I<"Roadrunner Perl">, in that it I<runs really fast>.
  664 
  665 =head2 Section 1.9: Why Did Will Invent RPerl?
  666 
  667 Will loves Perl and the Perl community.
  668 
  669 Will is a scientist and needs his code to run really fast.
  670 
  671 Will doesn't like the hassle of writing code in C or C++ or XS or Inline::C or Inline::CPP.
  672 
  673 Will waited a decade or two before realizing he had to do it himself.
  674 
  675 =head2 Section 1.10: Why Didn't Will Just Use Normal Perl?
  676 
  677 Dynamic languages like Perl are fast at running some kinds of computational actions, such as regular expressions (text data pattern matching) and reading from a database.
  678 
  679 Unfortunately, dynamic languages are slow at running general-purpose computations, such as arithmetic and moving data around in memory.  Sometimes very slow.
  680 
  681 Dynamic languages like Perl are also flexible, powerful, and relatively easy to learn.  Sometimes too flexible.
  682 
  683 RPerl's goal is to keep all of Perl's power and ease-of-use, while removing the redundant parts of Perl's flexibility in order to gain a major runtime speed boost.
  684 
  685 The most complex and flexible parts of Perl are called I<"high magic">, so RPerl is focused on supporting the I<"low magic"> parts of Perl which can be made to run fast.
  686 
  687 =head2 Section 1.11: Is RPerl Simple Or Complicated?
  688 
  689 RPerl is specifically designed to remove the confusing and overly-complicated parts of Perl.
  690 
  691 RPerl also introduces a number of additional rules and templates which are not present in normal Perl, notably including the use of real data types.
  692 
  693 The net effect of removing Perl complexity and adding RPerl rules falls in favor of RPerl, due primarily to the exceedingly complex nature of Perl.
  694 
  695 In other words, RPerl is easier to learn and use than dynamic languages like normal Perl, and most any other language in general.
  696 
  697 =head2 Section 1.12: How Is RPerl Being Promoted?
  698 
  699 The RPerl team has been regularly promoting RPerl in a number of physical and digital venues, including but not limited to:
  700 
  701 =over
  702 
  703 =item * YAPC::NA  L<http://www.yapcna.org>
  704 
  705 =item * Austin Perl Mongers  L<http://www.austin.pm>
  706 
  707 =item * RPerl Website  L<http://www.rperl.org>
  708 
  709 =item * Github  L<https://github.com/wbraswell/rperl>
  710 
  711 =item * Facebook Page  L<https://www.facebook.com/rperlcompiler>
  712 
  713 =item * Facebook Groups  L<https://www.facebook.com/groups/perlprogrammers>  L<https://www.facebook.com/groups/perlmonger>
  714 
  715 =item * Twitter  L<https://twitter.com/rperlcompiler>
  716 
  717 =item * PerlMonks  L<http://perlmonks.org>
  718 
  719 =item * Perl Blogs  L<http://blogs.perl.org>
  720 
  721 =item * IRC #perl11  L<http://irc.lc/magnet/perl11/rperl_newbie@@@>
  722 
  723 =back
  724 
  725 =head2 Section 1.13: What Is The RPerl Community Up To?
  726 
  727 As of US Independence Day 2016, RPerl v2.0 (codename I<Pioneer>) has been publicly released and is in use by a number of early adopters around the world.
  728 
  729 RPerl development is proceeding with financial support from both Kickstarter crowdfunding and official grant monies from The Perl Foundation.
  730 
  731 The RPerl community is beginning to grow, and there are a number of exciting RPerl projects currently in the works.
  732 
  733 If you would like to create software libraries and applications (AKA "programs" or "apps") to be utilized by end-users, then please join the RPerl application developers group, also known as the "RPerl App Devs":
  734 
  735 L<RPerl App Devs Group On Facebook|https://www.facebook.com/groups/1551887621787018>
  736 
  737 L<RPerl App Devs Intake Board On Trello|https://trello.com/b/XmmPJQJj/austin-pm-rperl-app-devs-intake>
  738 
  739 =head2 Section 1.14: What Is RPerl Meant To Do?
  740 
  741 RPerl is a general-purpose programming language, which means you can use RPerl to efficiently and effectively implement virtually any kind of software you can imagine.
  742 
  743 RPerl is especially well-suited for building software which benefits from speed, such as scientific simulations and graphical video games.
  744 
  745 RPerl is also good for building software which utilizes Perl's strong-suit of string manipulation; RPerl currently supports basic string operators, with full regular expression support to be added in an upcoming version.
  746 
  747 =head2 Section 1.15: What Is RPerl Not Meant To Do?
  748 
  749 RPerl has purposefully disabled the most complex features of Perl, such as runtime code evaluation, secret operators, and punctuation variables.  If you have purposefully designed your Perl software to depend on these high-magic features, or you are unconditionally committed to continue using high-magic language features, then maybe RPerl isn't for you.
  750 
  751 =head2 Section 1.16: How Can I Download & Install RPerl?
  752 
  753 Installing RPerl ranges from easy to difficult, depending on how well your operating system supports Perl and C++.
  754 
  755 On modern operating systems with good Perl support, such as Debian or Ubuntu GNU/Linux, you should be able to install RPerl system-wide by running the following command at your terminal command prompt:
  756 
  757 =for rperl X<noncode>
  758 
  759     $ sudo cpan RPerl
  760 
  761 =for rperl X</noncode>
  762 
  763 You may also choose to use the C<`cpanm`> command for simplicity, or the C<local::lib> tool for single-user (not system-wide) installation, both of which are included in the INSTALL notes document linked below.
  764 
  765 If RPerl is properly installed, you should see a short text message displayed when you type the following command:
  766 
  767 =for rperl X<noncode>
  768 
  769     $ rperl -v
  770 
  771 =for rperl X</noncode>
  772 
  773 On operating systems with less Perl support, you may have to perform a number of steps to successfully install RPerl, with dry technical detail available in the INSTALL notes document:
  774 
  775 L<https://github.com/wbraswell/rperl/blob/master/INSTALL>
  776 
  777 Unless you are an experienced programmer or system administrator, it is B<strongly> recommended you use the Xubuntu operating system.  You can download the Xubuntu ISO file at the link below, then use it to create a bootable DVD disc or USB flash drive, install Xubuntu onto any computer, and issue the C<`sudo cpan RPerl`> command as described above.
  778 
  779 L<http://xubuntu.org/getxubuntu>
  780 
  781 If you are interested in viewing the source code of RPerl itself, you may find the latest major release of RPerl (stable) on CPAN:
  782 
  783 L<https://metacpan.org/author/WBRASWELL>
  784 
  785 You may find the latest development release of RPerl (possibly unstable) on Github:
  786 
  787 L<https://github.com/wbraswell/rperl>
  788 
  789 =head2 Section 1.17: Where Is Perl Software Stored Online?
  790 
  791 CPAN is the I<"Comprehensive Perl Archive Network">, the world's most successful and mature centralized software network.
  792 
  793 CPAN servers are where most public Perl software is stored, including RPerl.
  794 
  795 L<https://en.wikipedia.org/wiki/CPAN>
  796 
  797 L<http://www.cpan.org>
  798 
  799 Several other programming language communities have copied the success and implementation of CPAN, including JSAN for Javascript, CRAN for R, and CCAN for C.
  800 
  801 =head2 Section 1.18: How Can I Obtain Technical Support For RPerl?
  802 
  803 Official RPerl technical support is provided through Auto-Parallel Technologies, Inc.
  804 
  805 To request more information, please send an e-mail to the following address:
  806 
  807 william DOT braswell AT autoparallel DOT com
  808 
  809 =head2 Section 1.19: Are There Any Free Technical Support Options?
  810 
  811 Free technical support for non-commercial users is provided by the RPerl community through Internet Relay Chat.
  812 
  813 Server: irc.perl.org
  814 
  815 Channel: #perl11
  816 
  817 Easy Web Chat: L<http://irc.lc/magnet/perl11/rperl_newbie@@@>
  818 
  819 =head2 Section 1.20: Are There Any Bugs In RPerl?
  820 
  821 All software has small (or large) problems called I<"bugs">, and depending on who is marketing the software, they may even tell you some of the bugs are actually "features"!
  822 
  823 RPerl is a work in progress, and may contain a number of bugs, both known and unknown.  If you find a bug in RPerl, we would love to hear about it!
  824 
  825 The primary bug-tracking platform for RPerl is Github Issues, where you may file a new bug report ("new issue") if it is not already listed:
  826 
  827 L<https://github.com/wbraswell/rperl/issues>
  828 
  829 Please be sure to include all of the following information in your bug report:
  830 
  831 =over
  832 
  833 =item * Pertinent Problem Message Output, If Long Use L<https://gist.github.com/>
  834 
  835 =item * Operating System Version C<`cat /etc/issue`>
  836 
  837 =item * Perl Version C<`perl -v`>
  838 
  839 =item * RPerl Version C<`rperl -v`>
  840 
  841 =back
  842 
  843 Although Github Issues is strongly preferred, the RPerl development team also supports the legacy CPAN ticket system:
  844 
  845 L<https://rt.cpan.org/Public/Dist/Display.html?Name=RPerl>
  846 
  847 =head2 Section 1.21: How Can I Write A Program Using RPerl?
  848 
  849 Computer programs are written in a human-readable format called I<"source code">.  Source code is stored as plain text data inside normal computer files.  These are the same kind of text files which you may be already familiar with as ending in the F<.txt> file suffix.  The only difference is we simply choose a different file name suffix to identify these specific text files as containing source code.  Thus, programs written using the RPerl language are plain text files, which means you can use any text editor to create and modify your RPerl source code.  Examples of common text editors include Notepad, Pico, and Vi.
  850 
  851 L<http://www.vim.org>
  852 
  853 To avoid possible file format problems, do not edit your RPerl programs using a word processor such as Wordpad, Word, OpenOffice, or LibreOffice.
  854 
  855 Experienced RPerl developers may choose to utilize an I<"integrated development environment"> (IDE), which is a special text editor made for writing software.  Examples of common Perl IDE applications include Eclipse EPIC, Padre, and Komodo (non-free).
  856 
  857 L<http://www.epic-ide.org>
  858 
  859 L<http://padre.perlide.org>
  860 
  861 L<http://komodoide.com/perl>
  862 
  863 =head2 Section 1.22: A Sample RPerl Program
  864 
  865     #!/usr/bin/env perl
  866     
  867     # Foo Bar Arithmetic Example
  868     
  869     # [[[ HEADER ]]]
  870     use RPerl;
  871     use strict;
  872     use warnings;
  873     our $VERSION = 0.001_000;
  874     
  875     # [[[ CRITICS ]]]
  876     ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
  877     ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils
  878     
  879     # [[[ OPERATIONS ]]]
  880     my integer $foo = 21 + 12;
  881     my integer $bar = 23 * 42 * 2;
  882     my number  $baz = to_number($bar) / $foo;
  883     print 'have $foo = ', to_string($foo), "\n";
  884     print 'have $bar = ', to_string($bar), "\n";
  885     print 'have $baz = ', to_string($baz), "\n";
  886 
  887 =head2 Section 1.23: What Are The Parts Of That Sample RPerl Program?
  888 
  889 This program is separated by blank lines into 4 sections: shebang, header, critics, and operations.  
  890 
  891 Other than the shebang and critics, all lines beginning with C<#> are comments and can be safely ignored or discarded without affecting the program.
  892 
  893 The I<"shebang"> section is required, always contains exactly 1 line, and is short for I<"hash bang">; referring to the two leading characters C<#!> of this line.  The I<"octothorpe"> character C<#> (tic-tac-toe symbol) is called a I<"pound-sign"> when used on a telephone, and is called a I<"hash"> (or more recently and less accurately I<"hash-tag">) when used on a computer.  The exclamation-point character C<!> is called a I<"bang"> when used on a computer.  When appearing together as the first two characters in a plain text file, the hash and bang characters tell the operating system to run the immediately-following command (in this case the Perl interpreter invoked by C</usr/bin/env perl>) and pass the remaining contents of the text file as input to the command.  (Traditionally, the Perl interpreter has been located at F</usr/bin/perl>, however we must practice prudence by asking the operating system environment where our Perl interpreter is actually located, in order to support those cases where Perl may be installed in a non-standard directory, such as with Perlbrew or manually-built Perl interpreters.  Please see L</Section 1.24: How Do I Run The RPerl Compiler?> for more information.)  In other words, if the first line of a plain text file is C<#!/usr/bin/env perl> (or C<#!/usr/bin/perl> or something similar), then that file is a Perl program.
  894 
  895 The I<"header"> section is required and always contains 4 lines for an RPerl I<"program"> file ending in F<.pl>, or 5 lines for an RPerl I<"module"> ending in F<.pm> (covered later in Chapter 11).  C<use> is recognized by Perl as a special I<"keyword"> (also a Perl I<"function">) which has 2 primary purposes: to load additional RPerl modules, and to change RPerl settings called I<"pragma"> settings.  (Please see L</Section 4.6: C<use strict; use warnings;> Pragmas & Magic> for more information about I<"pragma"> system configuration modes.)  The C<use RPerl;> line is dual-purpose, it both loads the F<RPerl.pm> module and enables the special RPerl low-magic pragma.  (Please see L</Section 1.25.4: The Low-Magic Perl Commandments> for more information about low magic versus high magic.)  The C<use strict;> and C<use warnings;> lines enable basic Perl pragmas which require decent programming practices by the human programmers.  The C<our $VERSION = 0.001_000;> line sets the version number of this RPerl program.
  896 
  897 The I<"critics"> section aids in the proper detection of errors in your RPerl source code.  This section of source code is only included as necessary, and may contain 1 or more lines beginning with C<## no critic>, which disable the errors caused by the over-restrictive nature of some Perl::Critic policies.  There are currently 6 critics commands enabled for normal RPerl users, the first 2 of which are given in this example.  The "USER DEFAULT 1" C<no critic> command allows the use of numeric values such as C<21> and C<12>, as well as the common C<print> command.  The C<USER DEFAULT 2> critics command allows the printing of C<'have $foo = '>, where a single-quoted C<'> string literal value contains the the dollar-sign C<$> sigil (covered later in Chapter 2).
  898 
  899 The I<"operations"> section is required and contains 1 or more lines of general-purpose RPerl source code.  This is the main body of your program.  The 6 lines of source code in our example are used to perform some simple arithmetic and display the results.  The C<my integer $foo = 21 + 12;> line declares a new I<"variable"> named C<$foo>.  A variable is simply a place to store your individual pieces of data, identified by a name of your choice.  (Please see L</CHAPTER 2: SCALAR VALUES & VARIABLES (NUMBERS & TEXT)> for more information about variables.)  Every variable in RPerl must be defined as containing exactly one type of data, such as whole numbers or decimal numbers or characters or strings, etc.  (In normal Perl, there are no data types.)
  900 
  901 The variable C<$foo> is defined as containing the data type I<"integer">, which is another word for whole numbers, such as C<0> or C<1> or C<-5_126>.  C<$foo> is initialized to contain the arithmetic result of numeric literal values C<21> plus C<12>.
  902 
  903 The C<my integer $bar = 23 * 42 * 2;> line does much the same thing, creating a new numeric variable named C<$bar> and initialized with C<23> times C<42> times C<2>.
  904 
  905 The C<my number $baz = to_number($bar) / $foo;> line creates a new variable named C<$baz>.  This variable contains floating-point numeric data, which is simply another term for decimal numbers such as C<0.1> or C<1.0> or C<-5_126.34>.  The variable C<$baz> is initialized to contain the quotient of the C<$bar> and C<$foo> variables.  The C<to_number()> RPerl type conversion I<"subroutine"> converts a non-floating-point C<integer> value to a floating-point C<number> value.  (A subroutine is a user-defined operation, in this case pre-defined by the RPerl development team for your convenience; please see L</CHAPTER 4: ORGANIZING BY SUBROUTINES> for more information.)
  906 
  907 The C<print 'have $foo = ', $foo, "\n";> and following 2 lines will display on screen (not send to paper printer) the labeled values of C<$foo>, C<$bar>, and C<$baz> respectively.  The C<,> comma is used to separate multiple I<"arguments"> passed to the C<print> operator.  An I<"argument"> is simply a piece of data provided as input to an operation.  For example, the number C<23> and the variable C<$foo> are arguments to the addition operation in the source code C<23 + $foo>.  In the context of source code operations, the terms I<"operand"> and I<"parameter"> mean the same thing as I<"argument">.  (Please see L</Section 1.24: How Do I Run The RPerl Compiler?> for the similar-yet-different definition of I<"argument"> in the context of command-line programs.)
  908 
  909 The C<to_string()> RPerl type conversion subroutine converts the numeric values to underscore-formatted string values, suitable for use via the C<print> operator.  If the C<to_string()> subroutine is not used, then the displayed numeric values will still be human-readable, but will not contain the proper underscores to be accepted back into RPerl as valid numeric data.  The "n" in the C<"\n"> double-quoted strings stands for "newline", which places the next piece of printed data down on the following line.
  910 
  911 =head2 Section 1.24: How Do I Run The RPerl Compiler?
  912 
  913 Normal Perl source code is executed using a software mechanism known as I<"interpretation">, which is to say that Perl is an I<"interpreted"> language and the F</usr/bin/perl> command is called the I<"Perl interpreter">.  The primary alternative to interpretation is I<"compilation">.  An interpreted computer program is converted from human-readable source code into computer-readable binary code one line at a time, and each line of code is executed before the following line is converted.  On the other hand, a compiled computer program is converted from source code into binary code all at once, then the resulting executable binary file can be run as many times as you like without further conversion.  So, RPerl is a I<"compiled"> subset of the Perl language and the F</usr/bin/rperl> command is called the I<"RPerl compiler">.
  914 
  915 Like the Perl interpreter, the RPerl compiler accepts 2 different source code file types as input: Perl programs which end in F<.pl> and Perl modules which end in F<.pm>.  Perl program files actually run and execute actions, optionally receiving some functionality from 1 or more Perl module files if specified.  Perl modules do not run or execute actions themselves, they only provide functionality which must in turn be called from a Perl program, or from another Perl module which eventually gets called by a Perl program.
  916 
  917 When you run the RPerl compiler program via the F</usr/bin/rperl> command, you may optionally provide input arguments which specify the many possible configuration settings to be used by RPerl while it is running.  Similarly, you may provide input arguments to most other command-line programs, such as Perl via the F</usr/bin/perl> command, etc.  In the context of command-line programs, the terms I<"command-line option"> and I<"argument"> and I<"command-line argument"> mean the same thing as I<"option">.  (Please see L</Section 1.23: What Are The Parts Of That Sample RPerl Program?> for the similar-yet-different definition of I<"argument"> in the context of source code operations.)
  918 
  919 A list of all valid RPerl compiler options may be seen by issuing the following command:
  920 
  921 =for rperl X<noncode>
  922 
  923     $ rperl -?
  924 
  925 =for rperl X</noncode>
  926 
  927 You may find the same information by viewing the following links:
  928 
  929 L<rperl>
  930 
  931 L<https://metacpan.org/pod/distribution/RPerl/script/rperl>
  932 
  933 To compile-then-execute the preceding RPerl example program, you may copy and paste the entire program (from shebang to second C<print>) into a temporary file such as F</tmp/foobar.pl>, then execute the following command:
  934 
  935 =for rperl X<noncode>
  936 
  937     $ rperl /tmp/foobar.pl
  938 
  939 =for rperl X</noncode>
  940 
  941 The output of this example program should be:
  942 
  943 =for rperl X<noncode>
  944 
  945     have $foo = 33
  946     have $bar = 1_932
  947     have $baz = 58.545_454_545_454_5
  948 
  949 =for rperl X</noncode>
  950 
  951 If the compilation is successful, a new compiled executable file will be created in F</tmp/foobar>.  You may then directly execute the compiled program as many times as you like, without needing to recompile it using the C<`rperl`> command, and you should receive the exact same output as the non-compiled code:
  952 
  953 =for rperl X<noncode>
  954 
  955     $ /tmp/foobar
  956     have $foo = 33
  957     have $bar = 1_932
  958     have $baz = 58.545_454_545_454_5
  959 
  960 =for rperl X</noncode>
  961 
  962 Please see L</CHAPTER 11: CLASSES, PACKAGES, MODULES, LIBRARIES> for more information about compiling Perl modules.
  963 
  964 
  965 =head2 Section 1.25: A Quick Overview of RPerl
  966 
  967 =head3 Section 1.25.1: Creator Of RPerl, Will Braswell
  968 
  969 Will Braswell does more than just create Perl compiler software, he is also very active in several other areas of life, including but not limited to:
  970 
  971 =over
  972 
  973 =item * Church & Spirituality
  974 
  975 =item * Boy Scouts of America
  976 
  977 =item * Cane Juggling & Circus Performance
  978 
  979 =item * Linux Operating Systems
  980 
  981 =item * Charitable & Fraternal Organizations
  982 
  983 =item * Homeschooling & Higher Education
  984 
  985 =item * Astrophysics & Mathematics
  986 
  987 =item * Entrepreneurship & Business
  988 
  989 =item * High-Performance Computing
  990 
  991 =item * Professional Space Exploration
  992 
  993 =item * Family Life
  994 
  995 =back
  996 
  997 These areas of interest are reflected in the tone and intention of RPerl.
  998 
  999 =head3 Section 1.25.2: History Of RPerl
 1000 
 1001 The RPerl project officially began as a New Year's Resolution on January 1st, 2013.  Following the grand tradition of Perl creator I<"Saint" Larry Wall>, RPerl version releases are often timed to coincide with major holidays.
 1002 
 1003 After 1 year of work, RPerl v1.0beta1 was released on New Year's Day 2014, eventually followed by RPerl v1.0beta2 on Christmas 2014.
 1004 
 1005 The much-anticipated RPerl v1.0 full release was made on US Independence Day 2015, and RPerl v1.2 came on Halloween 2015.
 1006 
 1007 RPerl v1.3 was released on Thanksgiving 2015, followed by RPerl v1.4 on Christmas 2015, and so forth.
 1008 
 1009 RPerl v1.0 was funded through a Kickstarter campaign, then RPerl v1.2 and v1.3 were funded through a second Kickstarter campaign.  Work on the first 6 chapters of this book was funded, in part, by grants from The Perl Foundation.
 1010 
 1011 RPerl v2.0 was released on US Independence Day 2016, exactly 1 year after v1.0 was released, in order to establish a regular annual release cycle.
 1012 
 1013 =head3 Section 1.25.3: Performance Of RPerl
 1014 
 1015 The question of I<"How fast is RPerl?"> does not have one simple answer; instead there are several factors and configuration modes to be taken into consideration.  A relatively detailed description of the performance and modes may be found at the following link:
 1016 
 1017 L<http://rperl.org/performance_benchmarks.html>
 1018 
 1019 The most condensed answer is that I<"RPerl is really fast.">  Utilizing RPerl's fastest execution modes, we see performance very close to the highly-optimized I<C++> programming language, which means RPerl is now among the short list of "world's fastest languages" along with C, C++, and Fortran.
 1020 
 1021 =head3 Section 1.25.4: The Low-Magic Perl Commandments
 1022 
 1023 The high-magic features of Perl are primarily responsible for the slow speed at which Perl executes general-purpose computations.  The I<"R"> in RPerl stands for I<"Restricted">, in that we restrict ourselves to only use the low-magic features of Perl which can run really fast.
 1024 
 1025 The definitive list of do's and do-not's for high-magic vs low-magic Perl programming is called I<The Low Magic Perl Commandments> (LMPC).  There are 64 total commandments split into 5 groups of Ideals, Magic, Data, Operations, and Object-Orientation.  The "Thou Shalt" commandments appear in the left column, and the "Thou Shalt Nots" appear on the right.
 1026 
 1027 L<http://rperl.org/the_low_magic_perl_commandments.html>
 1028 
 1029 =for text The LMPC draw inspiration from, and (wherever possible) work together with Damian Conway's B<Perl Best Practices> and Jeffrey Thalhammer's Perl::Critic software.
 1030 
 1031 =for html <p>The LMPC draw inspiration from, and (wherever possible) work together with Damian Conway's <u><b>Perl Best Practices</b></u> and Jeffrey Thalhammer's Perl::Critic software.</p>
 1032 
 1033 L<http://shop.oreilly.com/product/9780596001735.do>
 1034 
 1035 L<http://search.cpan.org/~thaljef/Perl-Critic/lib/Perl/Critic/PolicySummary.pod>
 1036 
 1037 =head3 Section 1.25.5: Perlism & The Book Of RPerl
 1038 
 1039 I<Perlism> is the computer religion dedicated to the use, promotion, and development of the Perl family of programming languages.  (Not to be confused with a spiritual religion such as Christianity, a computer religion such as Perlism is an independent and complementary belief structure.)
 1040 
 1041 =for text A I<Perlite> is an adherent to the Perlism religion.  Perlism has a revered founder, Saint Larry (himself a devout Christian); a prophet, I<The Voice In The Wilderness> (Will); a monastery and shrine, I<Perl Monks>; commandments, The LMPC; proverbs from Saint Larry including I<TIMTOWTDI>, I<LMFB>, and I<HTAAOF>; and canonical scriptures, including Saint Larry's B<Apocalypses> and The Voice's B<The Book Of RPerl>.
 1042 
 1043 =for html <p>A <i>Perlite</i> is an adherent to the Perlism religion.  Perlism has a revered founder, Saint Larry (himself a devout Christian); a prophet, <i>The Voice In The Wilderness</i> (Will); a monastary and shrine, <i>Perl Monks</i>; commandments, The LMPC; proverbs from Saint Larry including <i>TIMTOWTDI</i>, <i>LMFB</i>, and <i>HTAAOF</i>; and canonical scriptures, including Saint Larry's <u><b>Apocalypses</b></u> and The Voice's <u><b>The Book Of RPerl</b></u>.</p>
 1044 
 1045 =for comment START HERE: INSERT MAN & DOCBOOK FORMATS
 1046 
 1047 =for comment START HERE: INSERT MAN & DOCBOOK FORMATS
 1048 
 1049 =for comment START HERE: INSERT MAN & DOCBOOK FORMATS
 1050 
 1051 The Book is a description of events surrounding the creation of RPerl and the future of the Internet.  It is intended to both educate and entertain.
 1052 
 1053 L<http://rperl.org/the_book_of_rperl.html>
 1054 
 1055 =head3 Section 1.25.6: Fun With Proverbs & Catch Phrases & Acronyms
 1056 
 1057 St. Larry has given us short and powerful proverbs, some of which are meant to have a purposefully tongue-in-cheek or sarcastic interpretation.
 1058 
 1059 Will has provided a corollary to each of St. Larry's official proverbs.
 1060 
 1061 =begin text
 1062 
 1063 my $z = q{<<< BEGIN TEXT EVAL >>>};
 1064 
 1065 use Text::ASCIITable;
 1066 
 1067 my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1});
 1068 
 1069 $table->setCols(splice @{[split /\s*\n\s*/, q{
 1070 
 1071 =end text
 1072 
 1073 =begin man
 1074 
 1075 .TS
 1076 allbox tab(@) ;
 1077 c c 
 1078 l l .
 1079 
 1080 =end man
 1081 
 1082 =for html <table class="rperl operators">
 1083 
 1084 =begin docbook
 1085 
 1086 <table id="learning_rperl-section_1.25.6-table_1" label="" frame="all" colsep="1" rowsep="1">
 1087 <title>Proverbs & Acronyms</title>
 1088 <tgroup cols="2">
 1089 
 1090 =end docbook
 1091 
 1092 =for man T{
 1093 
 1094 =for html <tr><th>
 1095 
 1096 =for docbook <thead>
 1097 
 1098 =for docbook <row><entry align="center">
 1099 
 1100 B<St. Larry's Original Proverb>
 1101 
 1102 =for man T}@T{
 1103 
 1104 =for html </th><th>
 1105 
 1106 =for docbook </entry><entry align="center">
 1107 
 1108 B<Will's Corollary Proverb>
 1109 
 1110 =for text }]}, 1);
 1111 
 1112 =for man T}
 1113 
 1114 =for html </td></tr>
 1115 
 1116 =for docbook </entry></row>
 1117 
 1118 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 1119 
 1120 =for man T{
 1121 
 1122 =for html <tr><td>
 1123 
 1124 =for docbook <row><entry align="left">
 1125 
 1126 3 Great Virtues Of A Programmer:
 1127 
 1128 LIH (Laziness, Impatience, Hubris)
 1129 
 1130 =for man T}@T{
 1131 
 1132 =for html </td><td>
 1133 
 1134 =for docbook </entry><entry align="left">
 1135 
 1136 3 Greater Virtues Of A Programmer:
 1137 
 1138 DPH (Diligence, Patience, Humility)
 1139 
 1140 =for text }]}, 1);
 1141 
 1142 =for man T}
 1143 
 1144 =for html </td></tr>
 1145 
 1146 =for docbook </entry></row>
 1147 
 1148 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 1149 
 1150 =for man T{
 1151 
 1152 =for html <tr><td>
 1153 
 1154 =for docbook <row><entry align="left">
 1155 
 1156 TIMTOWTDI (There Is More Than One Way To Do It)
 1157 
 1158 =for man T}@T{
 1159 
 1160 =for html </td><td>
 1161 
 1162 =for docbook </entry><entry align="left">
 1163 
 1164 TDNNTBMTOWTDI (There Does Not Need To Be More Than One Way To Do It)
 1165 
 1166 TIOFWTDI (There Is One Fastest Way To Do It)
 1167 
 1168 =for text }]}, 1);
 1169 
 1170 =for man T}
 1171 
 1172 =for html </th></tr>
 1173 
 1174 =for docbook </entry></row>
 1175 
 1176 =for docbook </thead>
 1177 
 1178 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 1179 
 1180 =for man T{
 1181 
 1182 =for html <tr><td>
 1183 
 1184 =for docbook <tbody>
 1185 
 1186 =for docbook <row><entry align="left">
 1187 
 1188 LMFB (Let Many Flowers Bloom)
 1189 
 1190 =for man T}@T{
 1191 
 1192 =for html </td><td>
 1193 
 1194 =for docbook </entry><entry align="left">
 1195 
 1196 PTBF (Pick The Best Flowers)
 1197 
 1198 =for text }]}, 1);
 1199 
 1200 =for man T}
 1201 
 1202 =for html </th></tr>
 1203 
 1204 =for docbook </entry></row>
 1205 
 1206 =for docbook </thead>
 1207 
 1208 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 1209 
 1210 =for man T{
 1211 
 1212 =for html <tr><td>
 1213 
 1214 =for docbook <tbody>
 1215 
 1216 =for docbook <row><entry align="left">
 1217 
 1218 HTAAOF (Have The Appropriate Amount Of Fun)
 1219 
 1220 =for man T}@T{
 1221 
 1222 =for html </td><td>
 1223 
 1224 =for docbook </entry><entry align="left">
 1225 
 1226 DTAAOW (Do The Appropriate Amount Of Work)
 1227 
 1228 =for text }]}, 1);
 1229 
 1230 =for man T}
 1231 
 1232 =for html </td></tr>
 1233 
 1234 =for docbook </entry></row>
 1235 
 1236 =begin text
 1237 
 1238 return $table->draw( ['.=','=.','=','='],   # .=============.
 1239 
 1240                      ['|','|','|'],         # | info | info |
 1241  
 1242                      ['|-','-|','=','='],   # |-===========-|
 1243 
 1244                      ['|','|','|'],         # | info | info |
 1245 
 1246                      ["'=","='",'=','='],   # '============='
 1247 
 1248                      ['|-','-|','-','+']    # rowseperator
 1249 
 1250                     );
 1251 
 1252 $z = q{<<< END TEXT EVAL >>>};
 1253 
 1254 =end text
 1255 
 1256 =for man .TE
 1257 
 1258 =for html </table>
 1259 
 1260 =for docbook </tbody></tgroup></table>
 1261 
 1262 In addition to St. Larry's official proverbs, there are a number of other commonly-used catch phrases and ideas in the Perl community.
 1263 
 1264 =begin text
 1265 
 1266 my $z = q{<<< BEGIN TEXT EVAL >>>};
 1267 
 1268 use Text::ASCIITable;
 1269 
 1270 my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1});
 1271 
 1272 $table->setCols(splice @{[split /\s*\n\s*/, q{
 1273 
 1274 =end text
 1275 
 1276 =begin man
 1277 
 1278 .TS
 1279 allbox tab(@) ;
 1280 c c 
 1281 l l .
 1282 
 1283 =end man
 1284 
 1285 =for html <table class="rperl operators">
 1286 
 1287 =begin docbook
 1288 
 1289 <table id="learning_rperl-section_1.25.6-table_2" label="" frame="all" colsep="1" rowsep="1">
 1290 <title>Catch Phrases & Acronyms</title>
 1291 <tgroup cols="2">
 1292 
 1293 =end docbook
 1294 
 1295 =for man T{
 1296 
 1297 =for html <tr><th>
 1298 
 1299 =for docbook <thead>
 1300 
 1301 =for docbook <row><entry align="center">
 1302 
 1303 B<Original Catch Phrase>
 1304 
 1305 =for man T}@T{
 1306 
 1307 =for html </th><th>
 1308 
 1309 =for docbook </entry><entry align="center">
 1310 
 1311 B<Will's Corollary Catch Phrase>
 1312 
 1313 =for text }]}, 1);
 1314 
 1315 =for man T}
 1316 
 1317 =for html </td></tr>
 1318 
 1319 =for docbook </entry></row>
 1320 
 1321 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 1322 
 1323 =for man T{
 1324 
 1325 =for html <tr><td>
 1326 
 1327 =for docbook <row><entry align="left">
 1328 
 1329 Perl 5 Is The Camel
 1330 
 1331 Perl 5 Is The Raptor
 1332 
 1333 Perl 6 Is The Butterfly
 1334 
 1335 =for man T}@T{
 1336 
 1337 =for html </td><td>
 1338 
 1339 =for docbook </entry><entry align="left">
 1340 
 1341 RPerl Is The Roadrunner
 1342 
 1343 =for text }]}, 1);
 1344 
 1345 =for man T}
 1346 
 1347 =for html </td></tr>
 1348 
 1349 =for docbook </entry></row>
 1350 
 1351 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 1352 
 1353 =for man T{
 1354 
 1355 =for html <tr><td>
 1356 
 1357 =for docbook <row><entry align="left">
 1358 
 1359 Perl Is The Onion
 1360 
 1361 =for man T}@T{
 1362 
 1363 =for html </td><td>
 1364 
 1365 =for docbook </entry><entry align="left">
 1366 
 1367 RPerl Is The Scallion
 1368 
 1369 =for text }]}, 1);
 1370 
 1371 =for man T}
 1372 
 1373 =for html </th></tr>
 1374 
 1375 =for docbook </entry></row>
 1376 
 1377 =for docbook </thead>
 1378 
 1379 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 1380 
 1381 =for man T{
 1382 
 1383 =for html <tr><td>
 1384 
 1385 =for docbook <tbody>
 1386 
 1387 =for docbook <row><entry align="left">
 1388 
 1389 Perl Is The Swiss Army Chainsaw
 1390 
 1391 =for man T}@T{
 1392 
 1393 =for html </td><td>
 1394 
 1395 =for docbook </entry><entry align="left">
 1396 
 1397 RPerl Is The Sword
 1398 
 1399 =for text }]}, 1);
 1400 
 1401 =for man T}
 1402 
 1403 =for html </th></tr>
 1404 
 1405 =for docbook </entry></row>
 1406 
 1407 =for docbook </thead>
 1408 
 1409 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 1410 
 1411 =for man T{
 1412 
 1413 =for html <tr><td>
 1414 
 1415 =for docbook <tbody>
 1416 
 1417 =for docbook <row><entry align="left">
 1418 
 1419 Perl Is Line-Noise
 1420 
 1421 Perl Is A Write-Only Language
 1422 
 1423 =for man T}@T{
 1424 
 1425 =for html </td><td>
 1426 
 1427 =for docbook </entry><entry align="left">
 1428 
 1429 RPerl Is Best Practices
 1430 
 1431 =for text }]}, 1);
 1432 
 1433 =for man T}
 1434 
 1435 =for html </td></tr>
 1436 
 1437 =for docbook </entry></row>
 1438 
 1439 =begin text
 1440 
 1441 return $table->draw( ['.=','=.','=','='],   # .=============.
 1442 
 1443                      ['|','|','|'],         # | info | info |
 1444  
 1445                      ['|-','-|','=','='],   # |-===========-|
 1446 
 1447                      ['|','|','|'],         # | info | info |
 1448 
 1449                      ["'=","='",'=','='],   # '============='
 1450 
 1451                      ['|-','-|','-','+']    # rowseperator
 1452 
 1453                     );
 1454 
 1455 $z = q{<<< END TEXT EVAL >>>};
 1456 
 1457 =end text
 1458 
 1459 =for man .TE
 1460 
 1461 =for html </table>
 1462 
 1463 =for docbook </tbody></tgroup></table>
 1464 
 1465 =head2 Section 1.26: What's New In RPerl v2.0?
 1466 
 1467 The single most significant new feature included in RPerl v2.0 is automatic parallelization.  This long-awaited software feature was promised from the very beginning of RPerl's initial development, with RPerl v2.0 being the originally-designated target for release of auto-parallel capabilities.  We stuck to the plan and delivered on time: the 4th of July, 2016.
 1468 
 1469 Automatic parallelization is now enabled on 4 parallel CPU cores by default, because quad-core CPUs are common at this time.  You may utilize the C<--num_cores=8> command-line argument to double the default number of parallel cores, for example.  (Please see L</B.18: Modes, Parallelize> and L</B.19: Modes, Parallelize, Number Of Cores> for more information about auto-parallelization arguments.)
 1470 
 1471 Currently, shared memory parallel hardware platforms are supported, such as multi-core CPUs and supercomputers, by utilizing the L<OpenMP|https://en.wikipedia.org/wiki/OpenMP> parallelization software.  In the near future we will add support for distributed memory platforms, such as clusters and the cloud, by utilizing the L<MPI|https://en.wikipedia.org/wiki/Message_Passing_Interface> parallelization software, as well as GPUs and other specialty hardware by utilizing the L<OpenCL|https://en.wikipedia.org/wiki/OpenCL> parallelization software. 
 1472 
 1473 RPerl triggers auto-parallelization by simply including the word 'PARALLEL' in a loop label; everything inside that loop will be automatically parallelized, including multiply-nested loops.  RPerl implements the L<polytope model|https://en.wikipedia.org/wiki/Polytope_model> (AKA L<polyhedral model|http://polyhedral.info>) for loop parallelization, by utilizing the L<Pluto PolyCC|http://pluto-compiler.sourceforge.net> polytope software.
 1474 
 1475 In addition to auto-parallelization, a number of other new features were released after RPerl v1.0 and by-or-before v2.0, including but not limited to:
 1476 
 1477 =over
 1478 
 1479 =item * Generate Stand-Alone Binary Executable Files & Shared Object Files
 1480 
 1481 =item * Control Native C++ Types Used For Integer & Number Values
 1482 
 1483 =item * Support SSE Data Types & Operations
 1484 
 1485 =item * Support GMP Data Types & Operations
 1486 
 1487 =item * Monolithic Modules
 1488 
 1489 =item * Uncompile (Delete) Unwanted Compiled Files
 1490 
 1491 =item * Two-Dimensional Data Structures
 1492 
 1493 =back
 1494 
 1495 =head2 Section 1.27: Exercises
 1496 
 1497 =head3 1.  Hello World  [ 15 mins ]
 1498 
 1499 On a computer with RPerl already installed, create a directory named F<LearningRPerl> containing a sub-directory named F<Chapter1>.  Using the B<I<Foo Bar>> example program as a template, manually type a new RPerl program into a file named F<exercise_1-hello_world.pl> inside the F<LearningRPerl/Chapter1> sub-directory.  The sole purpose of your first program is to use the C<print> operator and simply display the following one line of text output, followed by one newline character:
 1500 
 1501 =for rperl X<noncode>
 1502 
 1503     Hello, World!
 1504 
 1505 =for rperl X</noncode>
 1506 
 1507 Run your new program by issuing the following command at your terminal command prompt:
 1508 
 1509 =for rperl X<noncode>
 1510 
 1511     $ rperl -t LearningRPerl/Chapter1/exercise_1-hello_world.pl
 1512 
 1513 =for rperl X</noncode>
 1514 
 1515 I<HINT: You only need the "USER DEFAULT 1" C<no critic> command, so your resulting program should be 7 lines long, not counting comments or blank lines.>
 1516 
 1517 =head3 2.  RPerl Commands  [ 15 mins ]
 1518 
 1519 First, run the following RPerl command, and observe the output for use in 2a and 2b below:
 1520 
 1521 =for rperl X<noncode>
 1522 
 1523     $ rperl -?
 1524 
 1525 =for rperl X</noncode>
 1526 
 1527 2a.  What are some RPerl command-line options with which you are already familiar?
 1528 
 1529 2b.  With which options are you unfamiliar?
 1530 
 1531 Next, run the following 3 RPerl commands, for 2c and 2d below:
 1532 
 1533 =for rperl X<noncode>
 1534 
 1535     $ rperl -t -V LearningRPerl/Chapter1/exercise_1-hello_world.pl
 1536     $ rperl -t -D LearningRPerl/Chapter1/exercise_1-hello_world.pl
 1537     $ rperl -t -V -D LearningRPerl/Chapter1/exercise_1-hello_world.pl
 1538 
 1539 =for rperl X</noncode>
 1540 
 1541 2c.  How do the outputs of these 3 commands differ from the output of Exercise 1?
 1542 
 1543 2d.  How do the outputs differ from one another?
 1544 
 1545 =head3 3.  Foo Bar Arithmetic  [ 15 mins ]
 1546 
 1547 Manually type the entire B<I<Foo Bar Arithmetic>> example program into a file named F<exercise_3-foo_bar_arithmetic.pl> inside the F<LearningPerl/Chapter1> sub-directory.  (Even if you have already used copy-and-paste on the B<I<Foo Bar Arithmetic>> example program, you should still use this as an opportunity to build some RPerl muscle memory and type it in by hand.)
 1548 
 1549 Modify your program by adding a new floating-point numeric variable named C<$zab>, set its value to C<$foo> divided by C<$bar> (don't forget C<to_number()>), change the starting value of C<$bar>, and use C<print> to generate the following output:
 1550 
 1551 =for rperl X<noncode>
 1552 
 1553     have $foo = 33
 1554     have $bar = 966
 1555     have $baz = 29.272_727_272_727_3
 1556     have $zab = 0.034_161_490_683_229_8
 1557 
 1558 =for rperl X</noncode>
 1559 
 1560 Run your program thusly:
 1561 
 1562 =for rperl X<noncode>
 1563 
 1564     $ rperl -t LearningRPerl/Chapter1/exercise_3-foo_bar_arithmetic.pl
 1565 
 1566 =for rperl X</noncode>
 1567 
 1568 X<br>
 1569 
 1570 
 1571 =head1 CHAPTER 2: SCALAR VALUES & VARIABLES (NUMBERS & TEXT)
 1572 
 1573 Most programming languages include the basic principle of using named I<"variables"> to store data values such as numbers, text strings, and lists of multiple numbers or strings.  As stated in L</Section 1.23: What Are The Parts Of That Sample RPerl Program?> above, a "variable is simply a place to store your individual pieces of data, identified by a name of your choice".  The term I<"variable"> is a reference to the fact that the value stored inside a variable may I<"vary"> according to the needs of the programmer.  If a stored value will never change, then you should use a I<"constant"> instead of a variable.  (Please see section L</Section 2.5: Constant Data> for more information about constants.)
 1574 
 1575 Multiple variables may be created in a computer program, each with a different name such as C<$foo> or C<$bar> or C<$baz>, and each potentially containing a different value.  You can choose whatever name you want for each variable you create, such as the following three variables:
 1576 
 1577     my integer $some_whole_number   = 23;
 1578     my number  $some_decimal_number = 21.12;
 1579     my string  $some_funny_word     = 'howdy';
 1580 
 1581 A single piece of data, such as one number or one string, is called a I<"scalar">.  Multiple pieces of data combined into a single aggregate structure may be either an I<"array"> or a I<"hash">, described in chapters 3 and 6, respectively.  (Although sharing the same terminology, the I<hash> data structure is not related to the I<hash> C<#> tic-tac-toe character.)  In normal Perl, only scalar variable names begin with the dollar-sign C<$> I<"sigil">, while aggregate data structures are stored in variables starting with different sigils like at-sign C<@> or percent-sign C<%>.  A sigil is simply a special character prefixed to a word, in order to help us quickly identify different source code components.  In RPerl, all variable names begin the C<$> sigil, both scalar types and aggregate structures alike.
 1582 
 1583 =for comment DEV NOTE, CORRELATION #rp400: all POD changes must be made in both RPerl.pm & RPerl/Learning.pm
 1584 
 1585 RPerl provides 7 scalar data types:
 1586 
 1587 =over
 1588 
 1589 =item * C<boolean>
 1590 
 1591 =item * C<unsigned_integer>
 1592 
 1593 =item * C<integer> (core)
 1594 
 1595 =item * C<gmp_integer>
 1596 
 1597 =item * C<number> (core)
 1598 
 1599 =item * C<character>
 1600 
 1601 =item * C<string> (core)
 1602 
 1603 =back
 1604 
 1605 Of the 7 RPerl scalar data types, 3 are directly (natively) supported by the Perl 5 core: C<integer>, C<number>, and C<string>.  This means the Perl 5 core is capable of directly identifying and storing those 3 core types.  The remaining 4 non-core types are indirectly supported by the Perl 5 interpreter: C<boolean> and C<unsigned_integer> can be stored within either an C<integer> or C<number>; C<character> can be stored within a C<string>; and C<gmp_integer> is supported by the C<use bigint;> wrapper around the C<Math::BigInt::GMP> module.
 1606 
 1607 When RPerl application source code is compiled from RPerl into C++, all 7 data types are natively supported by C++ for high-speed execution.
 1608 
 1609 A single group of actual numeric digit(s) or quoted string character(s) is called a I<"literal">, such as:
 1610 
 1611     -21         # integer or gmp_integer or number
 1612 
 1613     'howdy'     # string
 1614 
 1615     -23.421_12  # number
 1616 
 1617     1_234_567   # unsigned_integer or integer or gmp_integer or number
 1618 
 1619     1_234_567_890_123_456_789_012_345_678_901_234_567_890_123_456_789_012_345  # gmp_integer
 1620 
 1621     'One million, two-hundred-thirty-four thousand, five-hundred-sixty-seven'  # string
 1622 
 1623     '1'         # character or string
 1624 
 1625     'a'         # character or string
 1626 
 1627     "\n"        # newline character or string
 1628 
 1629     q{}         # empty character or string
 1630 
 1631     0           # boolean or unsigned_integer or integer or gmp_integer or number
 1632 
 1633 =head2 Section 2.1: Numeric Data & Operators
 1634 
 1635 RPerl provides 5 numeric data types:
 1636 
 1637 =over
 1638 
 1639 =item * C<boolean>
 1640 
 1641 S< >S< >S< >S< >a boolean logic value, either 0 or 1
 1642 
 1643 =item * C<unsigned_integer>
 1644 
 1645 S< >S< >S< >S< >a positive whole number value, greater-than or equal to 0
 1646 
 1647 =item * C<integer>
 1648 
 1649 S< >S< >S< >S< >a whole number value, either negative, 0, or positive
 1650 
 1651 =item * C<gmp_integer>
 1652 
 1653 S< >S< >S< >S< >a possibly-very-large whole number value, either negative, 0, or positive; may safely exceed your computer's data type limits
 1654 
 1655 =item * C<number>
 1656 
 1657 S< >S< >S< >S< >a floating-point decimal number value, either negative, 0, or positive
 1658 
 1659 =back
 1660 
 1661 Perl 5 provides several I<"built-in operators"> designed for use with numeric data, which can be organized into 6 general categories:
 1662 
 1663 =over
 1664 
 1665 =item * Arithmetic
 1666 
 1667 =item * Trigonometry
 1668 
 1669 =item * Comparison (Relational & Equality)
 1670 
 1671 =item * Logic
 1672 
 1673 =item * Bitwise
 1674 
 1675 =item * Miscellaneous
 1676 
 1677 =back
 1678 
 1679 Most of the operators which have names consisting of normal letters (a - z) are classified as I<"functions"> in Perl 5 terminology.  Notable exceptions are the logic operators, which are simply classified as "operators" in Perl, along with most of the operators which have names consisting of special characters.  For the sake of simplicity, we will only use the term "operator" throughout this textbook.
 1680 
 1681 L<http://perldoc.perl.org/perlop.html>
 1682 
 1683 L<http://perldoc.perl.org/perlfunc.html>
 1684 
 1685 Each operator in Perl 5 (and thus RPerl) is assigned 4 important characteristics: I<"arity"> (a number), I<"fixity"> (a placement location), I<"precedence"> (a number) and I<"associativity"> (a chirality or "handedness").  Operators of unary arity accept exactly 1 input operand, binary operators accept exactly 2 operands, etc.  Prefix operators appear before their respective operands, postfix appear after, infix appear between, and closed operators appear both before and after their operands.  Operators with a lower numeric precedence are executed before operators with a higher precedence; in the absence of parentheses, multiplication executes before addition because multiplication has a lower precedence number.  Operators with equal precedence number are grouped by (and executed in order of) associativity; in the absence of parentheses, multiple subtraction operators will execute from left to right because subtraction is left-associative, whereas multiple exponent operators will execute from right to left because exponentiation is right-associative.  For more information, see the Appendix:
 1686 
 1687 L</D.3: Syntax Arity, Fixity, Precedence, Associativity>
 1688 
 1689 Beyond the built-in math operators in Perl 5, more advanced operators and functions are available via the MathPerl software suite, which is (perhaps unsurprisingly) optimized using the RPerl compiler.
 1690 
 1691 L<MathPerl on CPAN|https://metacpan.org/release/MathPerl>
 1692 
 1693 =head3 Section 2.1.1: Boolean Literals
 1694 
 1695 The most memory-efficient numeric literal is C<boolean>, which represents a single I<"bit"> (binary digit) of information.  A C<boolean> literal may only give the values of exactly 0 or 1.
 1696 
 1697     0     # boolean
 1698     1     # boolean
 1699     -1    # not a boolean
 1700     1.5   # not a boolean
 1701     -1.5  # not a boolean
 1702 
 1703 =head3 Section 2.1.2: Unsigned Integer Literals
 1704 
 1705 The second most efficient numeric literal is C<unsigned_integer>, which represents a single whole (non-decimal) number greater-than or equal to 0.  An C<unsigned_integer> literal may describe any positive whole number, within the data size limits of the data types supported by your operating system software and computer hardware.  An C<unsigned_integer> may not describe a negative number or a non-whole number.
 1706 
 1707     23      # unsigned_integer
 1708     0       # unsigned_integer
 1709     42_230  # unsigned_integer
 1710     -23     # not an unsigned_integer
 1711     42.1    # not an unsigned_integer
 1712     999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999  # bad unsigned_integer, outside data type limits
 1713 
 1714 =head3 Section 2.1.3: Integer Literals
 1715 
 1716 The third most efficient numeric literal is C<integer>, which represents a single whole (non-decimal) number.  An C<integer> literal may describe any positive or negative whole number, within your operating system and hardware data type limits.
 1717 
 1718     -23     # integer
 1719     0       # integer
 1720     42_230  # integer
 1721     42.1    # not an integer
 1722     -999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999  # bad integer, outside data type limits
 1723 
 1724 =head3 Section 2.1.4: GMP Integer Literals
 1725 
 1726 The GNU Multi-Precision (GMP) software library is utilized to provide the C<gmp_integer> numeric literal, representing a single whole (non-decimal) number which may safely exceed the data type limits of your operating system and hardware.  A C<gmp_integer> literal may describe any positive or negative whole number, within the limits of the memory (real or virtual) available to your RPerl code.
 1727 
 1728     -23     # gmp_integer
 1729     0       # gmp_integer
 1730     42_230  # gmp_integer
 1731     42.1    # not a gmp_integer
 1732     -999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999  # gmp_integer
 1733 
 1734 =head3 Section 2.1.5: Number Literals
 1735 
 1736 The C<number> numeric literal represents a single floating-point (decimal) number, and may express any real number within your computer's data type limits.
 1737 
 1738     -23.42     # number
 1739     0.000_001  # number
 1740     42.23      # number
 1741     42         # number
 1742     -4_123.456_789_123_456_789_123_456_789_123_456_789_123_456_789_123_456_789_123_456  # bad number, outside data type limits
 1743 
 1744 =head3 Section 2.1.6: Underscore Digit Separators
 1745 
 1746 For C<unsigned_integer>, C<integer>, C<gmp_integer>, and C<number> literals, an I<"underscore"> C<_> character must be inserted after every third digit away from the decimal point, where the underscore is used in a similar manner as a comma when writing long numbers by hand.
 1747 
 1748     1_234_567  # integer, same as "1,234,567" in American notation
 1749     -32_123    # integer, same as "-32,123" in American notation
 1750     -32123     # bad integer, missing underscore
 1751 
 1752     1.234_567           # number, same as "1.234567" in American notation
 1753     -32_123.456_789_01  # number, same as "-32,123.45678901" in American notation
 1754     -32_123.456_78901   # bad number, missing underscore
 1755 
 1756 =head3 Section 2.1.7: Optional Positive Sign
 1757 
 1758 For C<unsigned_integer>, C<integer>, C<gmp_integer>, and C<number> literals, an optional C<+> plus sign may be prepended to explicitly indicate a numeric literal is positive (greater-than zero).
 1759 
 1760     1   # positive one
 1761     +1  # also positive one
 1762 
 1763 =for html <u>
 1764 
 1765 I<BEST PRACTICES>
 1766 
 1767 =over
 1768 
 1769 =item * I<When only positive numeric literals are used in one area of code, omit positive signs.>
 1770 
 1771 =item * I<When both positive and negative literals are used in one code area, use signs for all applicable literals.>
 1772 
 1773 =back
 1774 
 1775 =for html </u>
 1776 
 1777     +23    # NOT BEST PRACTICE: not aligned with other unsigned literal below
 1778     +55.6  # NOT BEST PRACTICE: not aligned with other unsigned literal below
 1779     42
 1780 
 1781     23     #     BEST PRACTICE:     aligned with other unsigned literal below, best for all-positive literals
 1782     55.6   #     BEST PRACTICE:     aligned with other unsigned literal below, best for all-positive literals
 1783     42
 1784 
 1785 X<break_code_blocks>
 1786 
 1787 
 1788     23     # NOT BEST PRACTICE:      not aligned with other signed literals below
 1789     55.6   # NOT BEST PRACTICE:      not aligned with other signed literals below
 1790     -21
 1791     -66.5
 1792 
 1793      23    # NOT BEST PRACTICE: manually aligned with other signed literals below, but will not automatically align via Perl::Tidy
 1794      55.6  # NOT BEST PRACTICE: manually aligned with other signed literals below, but will not automatically align via Perl::Tidy
 1795     -21
 1796     -66.5
 1797 
 1798     +23    #     BEST PRACTICE:          aligned with other signed literals below, best for mixed-sign literals
 1799     +55.6  #     BEST PRACTICE:          aligned with other signed literals below, best for mixed-sign literals
 1800     -21
 1801     -66.5
 1802 
 1803 =head3 Section 2.1.8: Scientific Notation
 1804 
 1805 For C<unsigned_integer>, C<integer>, and C<number> literals, very large or very small numbers may be approximated using I<"scientific notation">, where each number is normalized to have exactly one digit to the left of the decimal point, then a lower-case C<e> character and an appropriate integer power-of-ten is appended to the resulting normalized floating-point number.  The C<e> character stands for "exponent", as in "exponent of ten", and the Perl style of scientific notation is sometimes more accurately referred to as I<"scientific e notation">.
 1806 
 1807 As with normal integers, negative exponents must be prefixed with a C<-> minus sign and positive exponents may be optionally prefixed with a C<+> plus sign.
 1808 
 1809     1_234_567_000     # good integer
 1810     1.234_567_000e09  # good number, same as "1_234_567_000" in scientific notation
 1811 
 1812     0.001_234_567_000  # good number
 1813     1.234_567_000e-03  # good number, same as "0.001_234_567_000" in scientific notation
 1814 
 1815     -0.000_000_000_000_000_000_000_001_234_567  # bad number, outside data type limits
 1816     -1.234_567e-24  # good number, same as "-0.000_000_000_000_000_000_000_001_234_567" in scientific notation
 1817 
 1818 =for html <u>
 1819 
 1820 I<BEST PRACTICES>
 1821 
 1822 =over
 1823 
 1824 =item * I<Use 2 digits to represent all exponents.>
 1825 
 1826 =item * I<When only positive exponents are used, omit exponent signs.>
 1827 
 1828 =item * I<When both positive and negative exponents are used, use signs for all exponents.>
 1829 
 1830 =back
 1831 
 1832 =for html </u>
 1833 
 1834     1_234_567_000      # NOT BEST PRACTICE: no exponent
 1835     1.234_567_000e9    # NOT BEST PRACTICE: not aligned with two-digit exponents below
 1836     1.234_567_000e+09  # NOT BEST PRACTICE: not aligned with two-digit exponents below
 1837     1.234_567_000e09   #     BEST PRACTICE:     aligned with two-digit exponents below, best for all-positive exponents
 1838     1.234_567_000e19
 1839     2.111_000_333e04
 1840 
 1841     1.234_567_000e09   # NOT BEST PRACTICE: not aligned with signed exponents below
 1842     1.234_567_000e+09  #     BEST PRACTICE:     aligned with signed exponents below, best for mixed-sign exponents
 1843     1.234_567_000e-09
 1844     2.111_000_333e-04
 1845 
 1846     # accuracy of following numbers may be reduced on computers with lower precision data types
 1847     +1.537_969_711_485_091_65e+21  # BEST PRACTICE: best for mixed-sign exponents
 1848     -2.591_931_460_998_796_41e+01  # BEST PRACTICE: best for mixed-sign exponents
 1849     +1.792_587_729_503_711_81e-01  # BEST PRACTICE: best for mixed-sign exponents
 1850     +2.680_677_724_903_893_22e-03  # BEST PRACTICE: best for mixed-sign exponents
 1851     +1.628_241_700_382_422_95e-03  # BEST PRACTICE: best for mixed-sign exponents
 1852     -9.515_922_545_197_158_70e-15  # BEST PRACTICE: best for mixed-sign exponents
 1853 
 1854 =head3 Section 2.1.9: Truth Values
 1855 
 1856 In the most simple case, a I<"truth value"> may be represented by a boolean literal where the numeric value of C<0> represents the truth value of I<"false">, and numeric C<1> represents I<"true">.  In general, a truth value is any data which may be recognized by Perl (and thus RPerl) as being either true or false; there is no third option.
 1857 
 1858 Perl recognizes relatively few values as false, of which only 4 are accepted by RPerl:
 1859 
 1860       0   # false, number zero
 1861      '0'  # false, text   zero
 1862     q{0}  # false, text   zero
 1863     q{}   # false, text   empty
 1864 
 1865 All other values which RPerl accepts are recognized to hold a truth value of true.
 1866 
 1867 All numeric operators in the comparison and logic sub-categories, as well as all string operators in the comparison sub-category, will generate truth values as output.
 1868 
 1869 Perl attaches magic to the truth value of false, allowing it be utilized as either a normal truth value, or a numeric value of C<0>, or an empty string value of C<q{}>.  This magic behavior is not supported by C++, and thus not supported by RPerl.
 1870 
 1871 In C and C++, only numeric C<0> is universally recognized as false, while the text 0 and empty text are recognized as true, which is different than Perl.  To achieve compatibility, RPerl automatically inserts additional C++ logic in all compiled output code to check for the 2 remaining RPerl false values of text character zero C<'0'> or C<q{0}>, and empty text C<q{}>.  This ensures the compiled C++ output code will behave identically to the original RPerl input source code, with regard to truth values.
 1872 
 1873 B<WARNING FOR ALL COMPARISON & LOGIC OPERATORS:>
 1874 
 1875 B<Due to Perl's magic attached to truth values of false, as well as the difference between Perl and C++ recognized truth values, you may experience unexpected or undefined behavior if a truth value is utilized anywhere except true-or-false conditions in loops and conditional statements.>
 1876 
 1877 B<Only utilize the truth values returned by comparison and logic operators within the condition enclosed by parentheses in C<if ()>, C<elsif ()>, C<for ()>, or C<while ()>.>
 1878 
 1879     if    (1 > 2)     { print 'I think not', "\n"; }  # good use of greater-than operator
 1880     elsif ($x and $y) { print 'Maybe',       "\n"; }  # good use of          and operator
 1881 
 1882     for   (my integer $i = 0; $i < 23; $i++) { print 'finite loop',   "\n"; }  # good use of less-than operator
 1883     while (                    1 != 2      ) { print 'infinite loop', "\n"; }  # good use of not-equal operator
 1884 
 1885     my integer $foo = 3 + (1 >= 2);   # UNEXPECTED BEHAVIOR: bad use of greater-than-or-equal operator
 1886     my integer $bar = 3 * (1 <= 2);   # UNEXPECTED BEHAVIOR: bad use of    less-than-or-equal operator
 1887     my integer $bat = sin (1 == 2);   # UNEXPECTED BEHAVIOR: bad use of                 equal operator
 1888 
 1889 =head3 Section 2.1.10: Floating-Point Error
 1890 
 1891 A I<"floating-point number"> is any number which includes a decimal point C<.> as part of the numeric representation, as opposed to an integer which does not include a decimal point.  In RPerl, all floating-point values are stored in variables of the data type C<number>.
 1892 
 1893        0  # integer
 1894        1  # integer
 1895     -123  # integer
 1896     
 1897        0.1    # floating-point
 1898        1.654  # floating-point
 1899     -123.4    # floating-point
 1900     
 1901     my integer $some_int   = 23;     # integer variable
 1902     my number  $some_float = 23.42;  # floating-point variable
 1903 
 1904 All computer languages which perform calculations on floating-point numbers are susceptible to I<"floating-point error">, which is any inaccuracy due to incorrect rounding or lack of available precision.
 1905 
 1906 For example, suppose you have a floating-point number C<0.105>, which seems normal enough.  Let us further suppose you want to divide C<0.105> by some other number, say C<1_000>, and by the simple rules of arithmetic you would expect to arrive at an answer of C<0.000_105>.  Unfortunately, due to the way floating-point numbers are stored in computer memory, the actual result is closer to C<0.000_104_999>, so C<0.000_105> happens to be one of many possible floating-point errors.
 1907 
 1908            (0.105 / 1_000) == 0.000_105    # UNEXPECTED BEHAVIOR: false
 1909     print ((0.105 / 1_000) -  0.000_105);  # UNEXPECTED BEHAVIOR: -1.355_252_715_606_88e-20
 1910 
 1911 It will usually not be possible to easily predict when and where floating-point error will occur.  In general, you may experience the effects of floating-point error whenever your code relies upon one or more of the following:
 1912 
 1913 =over
 1914 
 1915 =item * A floating-point operator which must return a specific, exact result
 1916 
 1917 =item * A floating-point variable which must contain a specific, exact value
 1918 
 1919 =item * A floating-point value which must exactly equal another floating-point value
 1920 
 1921 =back
 1922 
 1923 To compensate for unpredictable floating-point error, you should use the I<"floating-point epsilon"> value stored in the constant C<RPerl::EPSILON()>, which is a very small number used to help detect inaccuracies.  Whenever you want of directly compare two floating-point values, instead use the subtraction C<-> and absolute value C<abs> operators to take the positive difference, then use the less-than C<E<lt>> operator to compare the difference to the floating-point epsilon value.  If the difference is less-than the floating-point epsilon, then the two input floating-point values can be considered to be numerically equal.
 1924 
 1925                                          RPerl::EPSILON()  # A VERY SMALL NUMBER: 0.000_000_000_000_000_2
 1926          (0.105 / 1_000) == 0.000_105                      # UNEXPECTED BEHAVIOR: false
 1927     abs ((0.105 / 1_000) -  0.000_105) < RPerl::EPSILON()  #   EXPECTED BEHAVIOR: true
 1928 
 1929 X<break_code_blocks>
 1930 
 1931 
 1932     my number $foo = 0.105 / 1_000;
 1933     my number $faa = 0.105 / 1_000;
 1934     my number $bar = 0.000_105;
 1935     my number $bat = 0.000_105;
 1936          if (0.000_105 == 0.000_105)             { print 'true'; } else { print 'false'; }  #   EXPECTED BEHAVIOR: true
 1937          if ((0.105 / 1_000) == (0.105 / 1_000)) { print 'true'; } else { print 'false'; }  #   EXPECTED BEHAVIOR: true
 1938          if ($bar == $bat)                       { print 'true'; } else { print 'false'; }  #   EXPECTED BEHAVIOR: true
 1939          if ($foo == $faa)                       { print 'true'; } else { print 'false'; }  #   EXPECTED BEHAVIOR: true
 1940          if ($foo == $bar)                       { print 'true'; } else { print 'false'; }  # UNEXPECTED BEHAVIOR: false
 1941     if (abs ($foo -  $bar) < RPerl::EPSILON())   { print 'true'; } else { print 'false'; }  #   EXPECTED BEHAVIOR: true
 1942 
 1943 B<WARNING FOR ALL FLOATING-POINT NUMERIC OPERATORS:>
 1944 
 1945 B<Due to floating-point error, unexpected behavior may be experienced if a floating-point value is tested for exact equality with any other value.>
 1946 
 1947 B<Always use the floating-point epsilon value C<RPerl::EPSILON()> to check for approximate equality instead of exact equality.>
 1948 
 1949 =head3 Section 2.1.11: Arithmetic Operators
 1950 
 1951 =begin text
 1952 
 1953 my $z = q{<<< BEGIN TEXT EVAL >>>};
 1954 
 1955 use Text::ASCIITable;
 1956 
 1957 my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1});
 1958 
 1959 $table->setCols(splice @{[split /\s*\n\s*/, q{
 1960 
 1961 =end text
 1962 
 1963 =begin man
 1964 
 1965 .TS
 1966 allbox tab(@) ;
 1967 c c c c c c c
 1968 l l l l r l l .
 1969 
 1970 =end man
 1971 
 1972 =for html <table class="rperl operators">
 1973 
 1974 =begin docbook
 1975 
 1976 <table id="learning_rperl-section_2.1.11-table_1" label="" frame="all" colsep="1" rowsep="1">
 1977 <title>Arithmetic Operators</title>
 1978 <tgroup cols="6">
 1979 
 1980 =end docbook
 1981 
 1982 =for man T{
 1983 
 1984 =for html <tr><th>
 1985 
 1986 =for docbook <thead>
 1987 
 1988 =for docbook <row><entry align="center">
 1989 
 1990 B<Name>
 1991 
 1992 =for man T}@T{
 1993 
 1994 =for html </th><th>
 1995 
 1996 =for docbook </entry><entry align="center">
 1997 
 1998 B<Symbol>
 1999 
 2000 =for man T}@T{
 2001 
 2002 =for html </th><th>
 2003 
 2004 =for docbook </entry><entry align="center">
 2005 
 2006 B<Arity>
 2007 
 2008 =for man T}@T{
 2009 
 2010 =for html </th><th>
 2011 
 2012 =for docbook </entry><entry align="center">
 2013 
 2014 B<Fixity>
 2015 
 2016 =for man T}@T{
 2017 
 2018 =for html </th><th>
 2019 
 2020 =for docbook </entry><entry align="center">
 2021 
 2022 B<Precedence>
 2023 
 2024 =for man T}@T{
 2025 
 2026 =for html </th><th>
 2027 
 2028 =for docbook </entry><entry align="center">
 2029 
 2030 B<Associativity>
 2031 
 2032 =for man T}@T{
 2033 
 2034 =for html </th><th>
 2035 
 2036 =for docbook </entry><entry align="center">
 2037 
 2038 B<Supported>
 2039 
 2040 =for text }]}, 1);
 2041 
 2042 =for man T}
 2043 
 2044 =for html </th></tr>
 2045 
 2046 =for docbook </entry></row>
 2047 
 2048 =for docbook </thead>
 2049 
 2050 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2051 
 2052 =for man T{
 2053 
 2054 =for html <tr><td>
 2055 
 2056 =for docbook <tbody>
 2057 
 2058 =for docbook <row><entry align="left">
 2059 
 2060 Absolute Value
 2061 
 2062 =for man T}@T{
 2063 
 2064 =for html </td><td>
 2065 
 2066 =for docbook </entry><entry align="left">
 2067 
 2068 abs
 2069 
 2070 =for man T}@T{
 2071 
 2072 =for html </td><td>
 2073 
 2074 =for docbook </entry><entry align="left">
 2075 
 2076 Unary
 2077 
 2078 =for man T}@T{
 2079 
 2080 =for html </td><td>
 2081 
 2082 =for docbook </entry><entry align="left">
 2083 
 2084 Prefix
 2085 
 2086 =for man T}@T{
 2087 
 2088 =for html </td><td>
 2089 
 2090 =for docbook </entry><entry align="right">
 2091 
 2092 01
 2093 
 2094 =for man T}@T{
 2095 
 2096 =for html </td><td>
 2097 
 2098 =for docbook </entry><entry align="left">
 2099 
 2100 Left
 2101 
 2102 =for man T}@T{
 2103 
 2104 =for html </td><td>
 2105 
 2106 =for docbook </entry><entry align="left">
 2107 
 2108 Coming Soon
 2109 
 2110 =for text }]}, 1);
 2111 
 2112 =for man T}
 2113 
 2114 =for html </td></tr>
 2115 
 2116 =for docbook </entry></row>
 2117 
 2118 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2119 
 2120 =for man T{
 2121 
 2122 =for html <tr><td>
 2123 
 2124 =for docbook <row><entry align="left">
 2125 
 2126 Natural Exponential Function
 2127 
 2128 =for man T}@T{
 2129 
 2130 =for html </td><td>
 2131 
 2132 =for docbook </entry><entry align="left">
 2133 
 2134 exp
 2135 
 2136 =for man T}@T{
 2137 
 2138 =for html </td><td>
 2139 
 2140 =for docbook </entry><entry align="left">
 2141 
 2142 Unary
 2143 
 2144 =for man T}@T{
 2145 
 2146 =for html </td><td>
 2147 
 2148 =for docbook </entry><entry align="left">
 2149 
 2150 Prefix
 2151 
 2152 =for man T}@T{
 2153 
 2154 =for html </td><td>
 2155 
 2156 =for docbook </entry><entry align="right">
 2157 
 2158 01
 2159 
 2160 =for man T}@T{
 2161 
 2162 =for html </td><td>
 2163 
 2164 =for docbook </entry><entry align="left">
 2165 
 2166 Non
 2167 
 2168 =for man T}@T{
 2169 
 2170 =for html </td><td>
 2171 
 2172 =for docbook </entry><entry align="left">
 2173 
 2174 Coming Soon
 2175 
 2176 =for text }]}, 1);
 2177 
 2178 =for man T}
 2179 
 2180 =for html </td></tr>
 2181 
 2182 =for docbook </entry></row>
 2183 
 2184 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2185 
 2186 =for man T{
 2187 
 2188 =for html <tr><td>
 2189 
 2190 =for docbook <row><entry align="left">
 2191 
 2192 Exponent AKA Power
 2193 
 2194 =for man T}@T{
 2195 
 2196 =for html </td><td>
 2197 
 2198 =for docbook </entry><entry align="left">
 2199 
 2200 **
 2201 
 2202 =for man T}@T{
 2203 
 2204 =for html </td><td>
 2205 
 2206 =for docbook </entry><entry align="left">
 2207 
 2208 Binary
 2209 
 2210 =for man T}@T{
 2211 
 2212 =for html </td><td>
 2213 
 2214 =for docbook </entry><entry align="left">
 2215 
 2216 Infix
 2217 
 2218 =for man T}@T{
 2219 
 2220 =for html </td><td>
 2221 
 2222 =for docbook </entry><entry align="right">
 2223 
 2224 04
 2225 
 2226 =for man T}@T{
 2227 
 2228 =for html </td><td>
 2229 
 2230 =for docbook </entry><entry align="left">
 2231 
 2232 Right
 2233 
 2234 =for man T}@T{
 2235 
 2236 =for html </td><td>
 2237 
 2238 =for docbook </entry><entry align="left">
 2239 
 2240 Yes
 2241 
 2242 =for text }]}, 1);
 2243 
 2244 =for man T}
 2245 
 2246 =for html </td></tr>
 2247 
 2248 =for docbook </entry></row>
 2249 
 2250 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2251 
 2252 =for man T{
 2253 
 2254 =for html <tr><td>
 2255 
 2256 =for docbook <row><entry align="left">
 2257 
 2258 Negative with Parentheses
 2259 
 2260 =for man T}@T{
 2261 
 2262 =for html </td><td>
 2263 
 2264 =for docbook </entry><entry align="left">
 2265 
 2266 -( )
 2267 
 2268 =for man T}@T{
 2269 
 2270 =for html </td><td>
 2271 
 2272 =for docbook </entry><entry align="left">
 2273 
 2274 Unary
 2275 
 2276 =for man T}@T{
 2277 
 2278 =for html </td><td>
 2279 
 2280 =for docbook </entry><entry align="left">
 2281 
 2282 Closed
 2283 
 2284 =for man T}@T{
 2285 
 2286 =for html </td><td>
 2287 
 2288 =for docbook </entry><entry align="right">
 2289 
 2290 05
 2291 
 2292 =for man T}@T{
 2293 
 2294 =for html </td><td>
 2295 
 2296 =for docbook </entry><entry align="left">
 2297 
 2298 Right
 2299 
 2300 =for man T}@T{
 2301 
 2302 =for html </td><td>
 2303 
 2304 =for docbook </entry><entry align="left">
 2305 
 2306 Yes
 2307 
 2308 =for text }]}, 1);
 2309 
 2310 =for man T}
 2311 
 2312 =for html </td></tr>
 2313 
 2314 =for docbook </entry></row>
 2315 
 2316 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2317 
 2318 =for man T{
 2319 
 2320 =for html <tr><td>
 2321 
 2322 =for docbook <row><entry align="left">
 2323 
 2324 Multiply
 2325 
 2326 =for man T}@T{
 2327 
 2328 =for html </td><td>
 2329 
 2330 =for docbook </entry><entry align="left">
 2331 
 2332 *
 2333 
 2334 =for man T}@T{
 2335 
 2336 =for html </td><td>
 2337 
 2338 =for docbook </entry><entry align="left">
 2339 
 2340 Binary
 2341 
 2342 =for man T}@T{
 2343 
 2344 =for html </td><td>
 2345 
 2346 =for docbook </entry><entry align="left">
 2347 
 2348 Infix
 2349 
 2350 =for man T}@T{
 2351 
 2352 =for html </td><td>
 2353 
 2354 =for docbook </entry><entry align="right">
 2355 
 2356 07
 2357 
 2358 =for man T}@T{
 2359 
 2360 =for html </td><td>
 2361 
 2362 =for docbook </entry><entry align="left">
 2363 
 2364 Left
 2365 
 2366 =for man T}@T{
 2367 
 2368 =for html </td><td>
 2369 
 2370 =for docbook </entry><entry align="left">
 2371 
 2372 Yes
 2373 
 2374 =for text }]}, 1);
 2375 
 2376 =for man T}
 2377 
 2378 =for html </td></tr>
 2379 
 2380 =for docbook </entry></row>
 2381 
 2382 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2383 
 2384 =for man T{
 2385 
 2386 =for html <tr><td>
 2387 
 2388 =for docbook <row><entry align="left">
 2389 
 2390 Divide
 2391 
 2392 =for man T}@T{
 2393 
 2394 =for html </td><td>
 2395 
 2396 =for docbook </entry><entry align="left">
 2397 
 2398 /
 2399 
 2400 =for man T}@T{
 2401 
 2402 =for html </td><td>
 2403 
 2404 =for docbook </entry><entry align="left">
 2405 
 2406 Binary
 2407 
 2408 =for man T}@T{
 2409 
 2410 =for html </td><td>
 2411 
 2412 =for docbook </entry><entry align="left">
 2413 
 2414 Infix
 2415 
 2416 =for man T}@T{
 2417 
 2418 =for html </td><td>
 2419 
 2420 =for docbook </entry><entry align="right">
 2421 
 2422 07
 2423 
 2424 =for man T}@T{
 2425 
 2426 =for html </td><td>
 2427 
 2428 =for docbook </entry><entry align="left">
 2429 
 2430 Left
 2431 
 2432 =for man T}@T{
 2433 
 2434 =for html </td><td>
 2435 
 2436 =for docbook </entry><entry align="left">
 2437 
 2438 Yes
 2439 
 2440 =for text }]}, 1);
 2441 
 2442 =for man T}
 2443 
 2444 =for html </td></tr>
 2445 
 2446 =for docbook </entry></row>
 2447 
 2448 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2449 
 2450 =for man T{
 2451 
 2452 =for html <tr><td>
 2453 
 2454 =for docbook <row><entry align="left">
 2455 
 2456 Modulo AKA Modulus
 2457 
 2458 =for man T}@T{
 2459 
 2460 =for html </td><td>
 2461 
 2462 =for docbook </entry><entry align="left">
 2463 
 2464 %
 2465 
 2466 =for man T}@T{
 2467 
 2468 =for html </td><td>
 2469 
 2470 =for docbook </entry><entry align="left">
 2471 
 2472 Binary
 2473 
 2474 =for man T}@T{
 2475 
 2476 =for html </td><td>
 2477 
 2478 =for docbook </entry><entry align="left">
 2479 
 2480 Infix
 2481 
 2482 =for man T}@T{
 2483 
 2484 =for html </td><td>
 2485 
 2486 =for docbook </entry><entry align="right">
 2487 
 2488 07
 2489 
 2490 =for man T}@T{
 2491 
 2492 =for html </td><td>
 2493 
 2494 =for docbook </entry><entry align="left">
 2495 
 2496 Left
 2497 
 2498 =for man T}@T{
 2499 
 2500 =for html </td><td>
 2501 
 2502 =for docbook </entry><entry align="left">
 2503 
 2504 Yes
 2505 
 2506 =for text }]}, 1);
 2507 
 2508 =for man T}
 2509 
 2510 =for html </td></tr>
 2511 
 2512 =for docbook </entry></row>
 2513 
 2514 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2515 
 2516 =for man T{
 2517 
 2518 =for html <tr><td>
 2519 
 2520 =for docbook <row><entry align="left">
 2521 
 2522 Add
 2523 
 2524 =for man T}@T{
 2525 
 2526 =for html </td><td>
 2527 
 2528 =for docbook </entry><entry align="left">
 2529 
 2530 +
 2531 
 2532 =for man T}@T{
 2533 
 2534 =for html </td><td>
 2535 
 2536 =for docbook </entry><entry align="left">
 2537 
 2538 Binary
 2539 
 2540 =for man T}@T{
 2541 
 2542 =for html </td><td>
 2543 
 2544 =for docbook </entry><entry align="left">
 2545 
 2546 Infix
 2547 
 2548 =for man T}@T{
 2549 
 2550 =for html </td><td>
 2551 
 2552 =for docbook </entry><entry align="right">
 2553 
 2554 08
 2555 
 2556 =for man T}@T{
 2557 
 2558 =for html </td><td>
 2559 
 2560 =for docbook </entry><entry align="left">
 2561 
 2562 Left
 2563 
 2564 =for man T}@T{
 2565 
 2566 =for html </td><td>
 2567 
 2568 =for docbook </entry><entry align="left">
 2569 
 2570 Yes
 2571 
 2572 =for text }]}, 1);
 2573 
 2574 =for man T}
 2575 
 2576 =for html </td></tr>
 2577 
 2578 =for docbook </entry></row>
 2579 
 2580 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2581 
 2582 =for man T{
 2583 
 2584 =for html <tr><td>
 2585 
 2586 =for docbook <row><entry align="left">
 2587 
 2588 Subtract
 2589 
 2590 =for man T}@T{
 2591 
 2592 =for html </td><td>
 2593 
 2594 =for docbook </entry><entry align="left">
 2595 
 2596 -
 2597 
 2598 =for man T}@T{
 2599 
 2600 =for html </td><td>
 2601 
 2602 =for docbook </entry><entry align="left">
 2603 
 2604 Binary
 2605 
 2606 =for man T}@T{
 2607 
 2608 =for html </td><td>
 2609 
 2610 =for docbook </entry><entry align="left">
 2611 
 2612 Infix
 2613 
 2614 =for man T}@T{
 2615 
 2616 =for html </td><td>
 2617 
 2618 =for docbook </entry><entry align="right">
 2619 
 2620 08
 2621 
 2622 =for man T}@T{
 2623 
 2624 =for html </td><td>
 2625 
 2626 =for docbook </entry><entry align="left">
 2627 
 2628 Left
 2629 
 2630 =for man T}@T{
 2631 
 2632 =for html </td><td>
 2633 
 2634 =for docbook </entry><entry align="left">
 2635 
 2636 Yes
 2637 
 2638 =for text }]}, 1);
 2639 
 2640 =for man T}
 2641 
 2642 =for html </td></tr>
 2643 
 2644 =for docbook </entry></row>
 2645 
 2646 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2647 
 2648 =for man T{
 2649 
 2650 =for html <tr><td>
 2651 
 2652 =for docbook <row><entry align="left">
 2653 
 2654 Natural Logarithm
 2655 
 2656 =for man T}@T{
 2657 
 2658 =for html </td><td>
 2659 
 2660 =for docbook </entry><entry align="left">
 2661 
 2662 log
 2663 
 2664 =for man T}@T{
 2665 
 2666 =for html </td><td>
 2667 
 2668 =for docbook </entry><entry align="left">
 2669 
 2670 Unary
 2671 
 2672 =for man T}@T{
 2673 
 2674 =for html </td><td>
 2675 
 2676 =for docbook </entry><entry align="left">
 2677 
 2678 Prefix
 2679 
 2680 =for man T}@T{
 2681 
 2682 =for html </td><td>
 2683 
 2684 =for docbook </entry><entry align="right">
 2685 
 2686 10
 2687 
 2688 =for man T}@T{
 2689 
 2690 =for html </td><td>
 2691 
 2692 =for docbook </entry><entry align="left">
 2693 
 2694 Non
 2695 
 2696 =for man T}@T{
 2697 
 2698 =for html </td><td>
 2699 
 2700 =for docbook </entry><entry align="left">
 2701 
 2702 Coming Soon
 2703 
 2704 =for text }]}, 1);
 2705 
 2706 =for man T}
 2707 
 2708 =for html </td></tr>
 2709 
 2710 =for docbook </entry></row>
 2711 
 2712 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 2713 
 2714 =for man T{
 2715 
 2716 =for html <tr><td>
 2717 
 2718 =for docbook <row><entry align="left">
 2719 
 2720 Square Root
 2721 
 2722 =for man T}@T{
 2723 
 2724 =for html </td><td>
 2725 
 2726 =for docbook </entry><entry align="left">
 2727 
 2728 sqrt
 2729 
 2730 =for man T}@T{
 2731 
 2732 =for html </td><td>
 2733 
 2734 =for docbook </entry><entry align="left">
 2735 
 2736 Unary
 2737 
 2738 =for man T}@T{
 2739 
 2740 =for html </td><td>
 2741 
 2742 =for docbook </entry><entry align="left">
 2743 
 2744 Prefix
 2745 
 2746 =for man T}@T{
 2747 
 2748 =for html </td><td>
 2749 
 2750 =for docbook </entry><entry align="right">
 2751 
 2752 10
 2753 
 2754 =for man T}@T{
 2755 
 2756 =for html </td><td>
 2757 
 2758 =for docbook </entry><entry align="left">
 2759 
 2760 Non
 2761 
 2762 =for man T}@T{
 2763 
 2764 =for html </td><td>
 2765 
 2766 =for docbook </entry><entry align="left">
 2767 
 2768 Coming Soon
 2769 
 2770 =for text }]}, 1);
 2771 
 2772 =for man T}
 2773 
 2774 =for html </td></tr>
 2775 
 2776 =for docbook </entry></row>
 2777 
 2778 =begin text
 2779 
 2780 return $table->draw( ['.=','=.','=','='],   # .=============.
 2781 
 2782                      ['|','|','|'],         # | info | info |
 2783  
 2784                      ['|-','-|','=','='],   # |-===========-|
 2785 
 2786                      ['|','|','|'],         # | info | info |
 2787 
 2788                      ["'=","='",'=','='],   # '============='
 2789 
 2790                      ['|-','-|','-','+']    # rowseperator
 2791 
 2792                     );
 2793 
 2794 $z = q{<<< END TEXT EVAL >>>};
 2795 
 2796 =end text
 2797 
 2798 =for man .TE
 2799 
 2800 =for html </table>
 2801 
 2802 =for docbook </tbody></tgroup></table>
 2803 
 2804 =over
 2805 
 2806 =item * B<Absolute Value>
 2807 
 2808     abs VALUE
 2809 
 2810 VALUE is numeric value;
 2811 
 2812 If operand VALUE is 0 or positive (greater-than 0), return unchanged;
 2813 
 2814 If VALUE is negative (less-than 0), return positive number with equal magnitude (distance from 0)
 2815 
 2816     abs  0         # 0
 2817     abs  1         # 1
 2818     abs -1         # 1
 2819     abs  2_112.23  # 2_112.23
 2820     abs -2_112.23  # 2_112.23
 2821 
 2822 =back
 2823 
 2824 =over
 2825 
 2826 =item * B<Natural Exponential Function>
 2827 
 2828     exp VALUE
 2829 
 2830 VALUE is numeric value;
 2831 
 2832 Raise C<e> (base of natural logarithm) to the power of operand VALUE, return result
 2833 
 2834     exp  0  # 1
 2835     exp  1  # 2.718_281_828_459_05
 2836     exp -1  # 0.367_879_441_171_442
 2837 
 2838 =back
 2839 
 2840 =over
 2841 
 2842 =item * B<Exponent AKA Power>
 2843 
 2844     VALUE1 ** VALUE2
 2845 
 2846 VALUE1 and VALUE2 are numeric values;
 2847 
 2848 Raise first operand VALUE1 to the power of second operand VALUE2, return result
 2849 
 2850     0 ** 0  # 1
 2851     0 ** 1  # 0
 2852     0 ** 2  # 0
 2853     0 ** 3  # 0
 2854     1 ** 0  # 1
 2855     1 ** 1  # 1
 2856     1 ** 2  # 1
 2857     1 ** 3  # 1
 2858     2 ** 0  # 1
 2859     2 ** 1  # 2
 2860     2 ** 2  # 4
 2861     2 ** 3  # 8
 2862 
 2863     (-1) ** 0  #  1
 2864     (-1) ** 1  # -1
 2865     (-1) ** 2  #  1
 2866     (-1) ** 3  # -1
 2867     (-2) ** 0  #  1
 2868     (-2) ** 1  # -2
 2869     (-2) ** 2  #  4
 2870     (-2) ** 3  # -8
 2871 
 2872     0 ** -1  # inf
 2873     0 ** -2  # inf
 2874     0 ** -3  # inf
 2875     1 ** -1  # 1
 2876     1 ** -2  # 1
 2877     1 ** -3  # 1
 2878     2 ** -1  # 0.5
 2879     2 ** -2  # 0.25
 2880     2 ** -3  # 0.125
 2881 
 2882     (-1) ** -1  # -1
 2883     (-1) ** -2  #  1
 2884     (-1) ** -3  # -1
 2885     (-2) ** -1  # -0.5
 2886     (-2) ** -2  #  0.25
 2887     (-2) ** -3  # -0.125
 2888 
 2889 =back
 2890 
 2891 =over
 2892 
 2893 =item * B<Negative with Parentheses>
 2894 
 2895     -( VALUE )
 2896 
 2897 VALUE is numeric value;
 2898 
 2899 Change sign of operand VALUE, return result;
 2900 
 2901 Negative VALUE becomes positive, and positive VALUE becomes negative;
 2902 
 2903 Parentheses must be used, due to ambiguity of hyphen C<-> character as negative operator, subtraction operator, or negative number literal
 2904 
 2905     -( 0)         #  0
 2906     -( 1)         # -1
 2907     -(-1)         #  1
 2908     -( 0.25)      # -0.25
 2909     -(-0.25)      #  0.25
 2910     -( 2_112.23)  # -2_112.23
 2911     -(-2_112.23)  #  2_112.23
 2912 
 2913 =back
 2914 
 2915 =over
 2916 
 2917 =item * B<Multiply>
 2918 
 2919     VALUE1 * VALUE2
 2920 
 2921 VALUE1 and VALUE2 are numeric values;
 2922 
 2923 Multiply first operand VALUE1 by second operand VALUE2, return product
 2924 
 2925      0 *  0  #  0
 2926      0 *  1  #  0
 2927      0 * -1  #  0
 2928      1 *  0  #  0
 2929      1 *  1  #  1
 2930      1 * -1  # -1
 2931     -1 *  0  #  0
 2932     -1 *  1  # -1
 2933     -1 * -1  #  1
 2934 
 2935     0.5 *  0    #  0
 2936     0.5 *  0.5  #  0.25
 2937     0.5 * -0.5  # -0.25
 2938     0.5 *  1    #  0.5
 2939     0.5 * -1    # -0.5
 2940     0.5 *  2    #  1.0
 2941     0.5 * -2    # -1.0
 2942 
 2943 =back
 2944 
 2945 =over
 2946 
 2947 =item * B<Divide>
 2948 
 2949     VALUE1 / VALUE2
 2950 
 2951 VALUE1 and VALUE2 are numeric values;
 2952 
 2953 Divide first operand VALUE1 by second operand VALUE2, return quotient;
 2954 
 2955 Error if attempt to divide by 0
 2956 
 2957      0 /  0  #  ERROR
 2958      0 /  1  #  0
 2959      0 / -1  #  0
 2960      1 /  0  #  ERROR
 2961      1 /  1  #  1
 2962      1 / -1  # -1
 2963     -1 /  0  #  ERROR
 2964     -1 /  1  # -1
 2965     -1 / -1  #  1
 2966 
 2967     0.5 /  0    #  ERROR
 2968     0.5 /  0.5  #  1
 2969     0.5 / -0.5  # -1
 2970     0.5 /  1    #  0.5
 2971     0.5 / -1    # -0.5
 2972     0.5 /  2    #  0.25
 2973     0.5 / -2    # -0.25
 2974 
 2975 =back
 2976 
 2977 =over
 2978 
 2979 =item * B<Modulo AKA Modulus>
 2980 
 2981     VALUE1 % VALUE2
 2982 
 2983 VALUE1 and VALUE2 are numeric values;
 2984 
 2985 Divide integer part of first operand VALUE1 by integer part of second operand VALUE2, return remainder;
 2986 
 2987 Error if attempt to modulus by VALUE2 with absolute value less-than 1
 2988 
 2989      0 %  0  # ERROR
 2990      0 %  1  # 0
 2991      0 % -1  # 0
 2992      1 %  0  # ERROR
 2993      1 %  1  # 0
 2994      1 % -1  # 0
 2995     -1 %  0  # ERROR
 2996     -1 %  1  # 0
 2997     -1 % -1  # 0
 2998 
 2999     0.5 %  0    # ERROR
 3000     0.5 %  0.5  # ERROR
 3001     0.5 % -0.5  # ERROR
 3002     0.5 %  1    # 0
 3003     0.5 % -1    # 0
 3004     0.5 %  2    # 0
 3005     0.5 % -2    # 0
 3006 
 3007 =back
 3008 
 3009 =over
 3010 
 3011 =item * B<Add>
 3012 
 3013     VALUE1 + VALUE2
 3014 
 3015 VALUE1 and VALUE2 are numeric values;
 3016 
 3017 Add first operand VALUE1 to second operand VALUE2, return sum
 3018 
 3019      0 +  0  #  0
 3020      0 +  1  #  1
 3021      0 + -1  # -1
 3022      1 +  0  #  1
 3023      1 +  1  #  2
 3024      1 + -1  #  0
 3025     -1 +  0  # -1
 3026     -1 +  1  #  0
 3027     -1 + -1  # -2
 3028 
 3029     0.5 +  0    #  0.5
 3030     0.5 +  0.5  #  1.0
 3031     0.5 + -0.5  #  0
 3032     0.5 +  1    #  1.5
 3033     0.5 + -1    # -0.5
 3034     0.5 +  2    #  2.5
 3035     0.5 + -2    # -1.5
 3036 
 3037 =back
 3038 
 3039 =over
 3040 
 3041 =item * B<Subtract>
 3042 
 3043     VALUE1 - VALUE2
 3044 
 3045 VALUE1 and VALUE2 are numeric values;
 3046 
 3047 Subtract second operand VALUE2 from first operand VALUE1, return difference
 3048 
 3049      0 -  0  #  0
 3050      0 -  1  # -1
 3051      0 - -1  #  1
 3052      1 -  0  #  1
 3053      1 -  1  #  0
 3054      1 - -1  #  2
 3055     -1 -  0  # -1
 3056     -1 -  1  # -2
 3057     -1 - -1  #  0
 3058 
 3059     0.5 -  0    #  0.5
 3060     0.5 -  0.5  #  0
 3061     0.5 - -0.5  #  1.0
 3062     0.5 -  1    # -0.5
 3063     0.5 - -1    #  1.5
 3064     0.5 -  2    # -1.5
 3065     0.5 - -2    #  2.5
 3066 
 3067 =back
 3068 
 3069 =over
 3070 
 3071 =item * B<Natural Logarithm>
 3072 
 3073     log VALUE
 3074 
 3075 VALUE is numeric value;
 3076 
 3077 Take logarithm base C<e> of operand VALUE, return result;
 3078 
 3079 Constant C<e> is known as Euler's Number and is defined as the limit of C<(1 + 1/$n)**$n> as C<$n> grows to infinity;
 3080 
 3081 To instead calculate logarithm using a base other than C<e>, utilize ratio C<(log $operand)/(log $base)>;
 3082 
 3083 Error if attempt to take logarithm of VALUE less-than or equal to 0
 3084 
 3085     log  0                    # ERROR
 3086     log  1                    # 0
 3087     log -1                    # ERROR
 3088     log 2.718_281_828_459_05  # 1
 3089 
 3090 =back
 3091 
 3092 =over
 3093 
 3094 =item * B<Square Root>
 3095 
 3096     sqrt VALUE
 3097 
 3098 VALUE is numeric value;
 3099 
 3100 Take square root of operand VALUE, return result;
 3101 
 3102 Error if attempt to take square root of VALUE less-than 0
 3103 
 3104     sqrt  0  # 0
 3105     sqrt  1  # 1
 3106     sqrt -1  # ERROR
 3107     sqrt  2  # 1.414_213_562_373_1
 3108 
 3109 =back
 3110 
 3111 =head3 Section 2.1.12: Trigonometry Operators
 3112 
 3113 =begin text
 3114 
 3115 my $z = q{<<< BEGIN TEXT EVAL >>>};
 3116 
 3117 use Text::ASCIITable;
 3118 
 3119 my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1});
 3120 
 3121 $table->setCols(splice @{[split /\s*\n\s*/, q{
 3122 
 3123 =end text
 3124 
 3125 =begin man
 3126 
 3127 .TS
 3128 allbox tab(@) ;
 3129 c c c c c c c
 3130 l l l l r l l .
 3131 
 3132 =end man
 3133 
 3134 =for html <table class="rperl operators">
 3135 
 3136 =begin docbook
 3137 
 3138 <table id="learning_rperl-section_2.1.12-table_1" label="" frame="all" colsep="1" rowsep="1">
 3139 <title>Trigonometry Operators</title>
 3140 <tgroup cols="6">
 3141 
 3142 =end docbook
 3143 
 3144 =for man T{
 3145 
 3146 =for html <tr><th>
 3147 
 3148 =for docbook <thead>
 3149 
 3150 =for docbook <row><entry align="center">
 3151 
 3152 B<Name>
 3153 
 3154 =for man T}@T{
 3155 
 3156 =for html </th><th>
 3157 
 3158 =for docbook </entry><entry align="center">
 3159 
 3160 B<Symbol>
 3161 
 3162 =for man T}@T{
 3163 
 3164 =for html </th><th>
 3165 
 3166 =for docbook </entry><entry align="center">
 3167 
 3168 B<Arity>
 3169 
 3170 =for man T}@T{
 3171 
 3172 =for html </th><th>
 3173 
 3174 =for docbook </entry><entry align="center">
 3175 
 3176 B<Fixity>
 3177 
 3178 =for man T}@T{
 3179 
 3180 =for html </th><th>
 3181 
 3182 =for docbook </entry><entry align="center">
 3183 
 3184 B<Precedence>
 3185 
 3186 =for man T}@T{
 3187 
 3188 =for html </th><th>
 3189 
 3190 =for docbook </entry><entry align="center">
 3191 
 3192 B<Associativity>
 3193 
 3194 =for man T}@T{
 3195 
 3196 =for html </th><th>
 3197 
 3198 =for docbook </entry><entry align="center">
 3199 
 3200 B<Supported>
 3201 
 3202 =for text }]}, 1);
 3203 
 3204 =for man T}
 3205 
 3206 =for html </td></tr>
 3207 
 3208 =for docbook </entry></row>
 3209 
 3210 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 3211 
 3212 =for man T{
 3213 
 3214 =for html <tr><td>
 3215 
 3216 =for docbook <row><entry align="left">
 3217 
 3218 Arctangent-Divide
 3219 
 3220 =for man T}@T{
 3221 
 3222 =for html </td><td>
 3223 
 3224 =for docbook </entry><entry align="left">
 3225 
 3226 atan2
 3227 
 3228 =for man T}@T{
 3229 
 3230 =for html </td><td>
 3231 
 3232 =for docbook </entry><entry align="left">
 3233 
 3234 Binary
 3235 
 3236 =for man T}@T{
 3237 
 3238 =for html </td><td>
 3239 
 3240 =for docbook </entry><entry align="left">
 3241 
 3242 Prefix
 3243 
 3244 =for man T}@T{
 3245 
 3246 =for html </td><td>
 3247 
 3248 =for docbook </entry><entry align="right">
 3249 
 3250 01
 3251 
 3252 =for man T}@T{
 3253 
 3254 =for html </td><td>
 3255 
 3256 =for docbook </entry><entry align="left">
 3257 
 3258 Left
 3259 
 3260 =for man T}@T{
 3261 
 3262 =for html </td><td>
 3263 
 3264 =for docbook </entry><entry align="left">
 3265 
 3266 Coming Soon
 3267 
 3268 =for text }]}, 1);
 3269 
 3270 =for man T}
 3271 
 3272 =for html </td></tr>
 3273 
 3274 =for docbook </entry></row>
 3275 
 3276 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 3277 
 3278 =for man T{
 3279 
 3280 =for html <tr><td>
 3281 
 3282 =for docbook <row><entry align="left">
 3283 
 3284 Sine
 3285 
 3286 =for man T}@T{
 3287 
 3288 =for html </td><td>
 3289 
 3290 =for docbook </entry><entry align="left">
 3291 
 3292 sin
 3293 
 3294 =for man T}@T{
 3295 
 3296 =for html </td><td>
 3297 
 3298 =for docbook </entry><entry align="left">
 3299 
 3300 Unary
 3301 
 3302 =for man T}@T{
 3303 
 3304 =for html </td><td>
 3305 
 3306 =for docbook </entry><entry align="left">
 3307 
 3308 Prefix
 3309 
 3310 =for man T}@T{
 3311 
 3312 =for html </td><td>
 3313 
 3314 =for docbook </entry><entry align="right">
 3315 
 3316 10
 3317 
 3318 =for man T}@T{
 3319 
 3320 =for html </td><td>
 3321 
 3322 =for docbook </entry><entry align="left">
 3323 
 3324 Non
 3325 
 3326 =for man T}@T{
 3327 
 3328 =for html </td><td>
 3329 
 3330 =for docbook </entry><entry align="left">
 3331 
 3332 Coming Soon
 3333 
 3334 =for text }]}, 1);
 3335 
 3336 =for man T}
 3337 
 3338 =for html </th></tr>
 3339 
 3340 =for docbook </entry></row>
 3341 
 3342 =for docbook </thead>
 3343 
 3344 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 3345 
 3346 =for man T{
 3347 
 3348 =for html <tr><td>
 3349 
 3350 =for docbook <tbody>
 3351 
 3352 =for docbook <row><entry align="left">
 3353 
 3354 Cosine
 3355 
 3356 =for man T}@T{
 3357 
 3358 =for html </td><td>
 3359 
 3360 =for docbook </entry><entry align="left">
 3361 
 3362 cos
 3363 
 3364 =for man T}@T{
 3365 
 3366 =for html </td><td>
 3367 
 3368 =for docbook </entry><entry align="left">
 3369 
 3370 Unary
 3371 
 3372 =for man T}@T{
 3373 
 3374 =for html </td><td>
 3375 
 3376 =for docbook </entry><entry align="left">
 3377 
 3378 Prefix
 3379 
 3380 =for man T}@T{
 3381 
 3382 =for html </td><td>
 3383 
 3384 =for docbook </entry><entry align="right">
 3385 
 3386 10
 3387 
 3388 =for man T}@T{
 3389 
 3390 =for html </td><td>
 3391 
 3392 =for docbook </entry><entry align="left">
 3393 
 3394 Non
 3395 
 3396 =for man T}@T{
 3397 
 3398 =for html </td><td>
 3399 
 3400 =for docbook </entry><entry align="left">
 3401 
 3402 Coming Soon
 3403 
 3404 =for text }]}, 1);
 3405 
 3406 =for man T}
 3407 
 3408 =for html </td></tr>
 3409 
 3410 =for docbook </entry></row>
 3411 
 3412 =begin text
 3413 
 3414 return $table->draw( ['.=','=.','=','='],   # .=============.
 3415 
 3416                      ['|','|','|'],         # | info | info |
 3417  
 3418                      ['|-','-|','=','='],   # |-===========-|
 3419 
 3420                      ['|','|','|'],         # | info | info |
 3421 
 3422                      ["'=","='",'=','='],   # '============='
 3423 
 3424                      ['|-','-|','-','+']    # rowseperator
 3425 
 3426                     );
 3427 
 3428 $z = q{<<< END TEXT EVAL >>>};
 3429 
 3430 =end text
 3431 
 3432 =for man .TE
 3433 
 3434 =for html </table>
 3435 
 3436 =for docbook </tbody></tgroup></table>
 3437 
 3438 =over
 3439 
 3440 =item * B<Arctangent-Divide>
 3441 
 3442     atan2 VALUE1, VALUE2
 3443 
 3444 VALUE1 and VALUE2 are numeric values;
 3445 
 3446 Divide first operand VALUE1 by second operand VALUE2, take arctangent of quotient, return result;
 3447 
 3448 Attempts to conform to Open Group / IEEE standards:
 3449 
 3450 L<http://perldoc.perl.org/perlport.html#atan2>
 3451 
 3452 L<http://pubs.opengroup.org/onlinepubs/9699919799/functions/atan2.html>
 3453 
 3454 To instead calculate tangent of 1 operand (not arctangent of 2 operands), utilize trigonometry identity ratio C<(sin $operand)/(cos $operand)>
 3455 
 3456     atan2  0,  0  #  0, MAY BE DIFFERENT ON YOUR SYSTEM
 3457     atan2  0,  1  #  0
 3458     atan2  0, -1  #  3.141_592_653_589_79, DEFINED AS PI
 3459     atan2  1,  0  #  1.570_796_326_794_9
 3460     atan2  1,  1  #  0.785_398_163_397_448
 3461     atan2  1, -1  #  2.356_194_490_192_34
 3462     atan2 -1,  0  # -1.570_796_326_794_9
 3463     atan2 -1,  1  # -0.785_398_163_397_448
 3464     atan2 -1, -1  # -2.356_194_490_192_34
 3465 
 3466 =back
 3467 
 3468 =over
 3469 
 3470 =item * B<Sine>
 3471 
 3472     sin VALUE
 3473 
 3474 VALUE is numeric value;
 3475 
 3476 Take sine of operand VALUE, return result
 3477 
 3478     sin  0                     #  0
 3479     sin  1                     #  0.841_470_984_807_897
 3480     sin -1                     # -0.841_470_984_807_897
 3481     sin  3.141_592_653_589_79  #  0, MAY BE SLIGHTLY OFF DUE TO FLOATING POINT ERROR
 3482 
 3483 =back
 3484 
 3485 =over
 3486 
 3487 =item * B<Cosine>
 3488 
 3489     cos VALUE
 3490 
 3491 VALUE is numeric value;
 3492 
 3493 Take cosine of operand VALUE, return result
 3494 
 3495     cos  0                     #  1
 3496     cos  1                     #  0.540_302_305_868_14
 3497     cos -1                     #  0.540_302_305_868_14
 3498     cos  3.141_592_653_589_79  # -1
 3499 
 3500 =back
 3501 
 3502 =head3 Section 2.1.13: Comparison (Relational & Equality) Operators
 3503 
 3504 =begin text
 3505 
 3506 my $z = q{<<< BEGIN TEXT EVAL >>>};
 3507 
 3508 use Text::ASCIITable;
 3509 
 3510 my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1});
 3511 
 3512 $table->setCols(splice @{[split /\s*\n\s*/, q{
 3513 
 3514 =end text
 3515 
 3516 =begin man
 3517 
 3518 .TS
 3519 allbox tab(@) ;
 3520 c c c c c c c
 3521 l l l l r l l .
 3522 
 3523 =end man
 3524 
 3525 =for html <table class="rperl operators">
 3526 
 3527 =begin docbook
 3528 
 3529 <table id="learning_rperl-section_2.1.13-table_1" label="" frame="all" colsep="1" rowsep="1">
 3530 <title>Comparison (Relational & Equality) Operators</title>
 3531 <tgroup cols="6">
 3532 
 3533 =end docbook
 3534 
 3535 =for man T{
 3536 
 3537 =for html <tr><th>
 3538 
 3539 =for docbook <thead>
 3540 
 3541 =for docbook <row><entry align="center">
 3542 
 3543 B<Name>
 3544 
 3545 =for man T}@T{
 3546 
 3547 =for html </th><th>
 3548 
 3549 =for docbook </entry><entry align="center">
 3550 
 3551 B<Symbol>
 3552 
 3553 =for man T}@T{
 3554 
 3555 =for html </th><th>
 3556 
 3557 =for docbook </entry><entry align="center">
 3558 
 3559 B<Arity>
 3560 
 3561 =for man T}@T{
 3562 
 3563 =for html </th><th>
 3564 
 3565 =for docbook </entry><entry align="center">
 3566 
 3567 B<Fixity>
 3568 
 3569 =for man T}@T{
 3570 
 3571 =for html </th><th>
 3572 
 3573 =for docbook </entry><entry align="center">
 3574 
 3575 B<Precedence>
 3576 
 3577 =for man T}@T{
 3578 
 3579 =for html </th><th>
 3580 
 3581 =for docbook </entry><entry align="center">
 3582 
 3583 B<Associativity>
 3584 
 3585 =for man T}@T{
 3586 
 3587 =for html </th><th>
 3588 
 3589 =for docbook </entry><entry align="center">
 3590 
 3591 B<Supported>
 3592 
 3593 =for text }]}, 1);
 3594 
 3595 =for man T}
 3596 
 3597 =for html </td></tr>
 3598 
 3599 =for docbook </entry></row>
 3600 
 3601 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 3602 
 3603 =for man T{
 3604 
 3605 =for html <tr><td>
 3606 
 3607 =for docbook <row><entry align="left">
 3608 
 3609 Less-Than
 3610 
 3611 =for man T}@T{
 3612 
 3613 =for html </td><td>
 3614 
 3615 =for docbook </entry><entry align="left">
 3616 
 3617 <
 3618 
 3619 =for man T}@T{
 3620 
 3621 =for html </td><td>
 3622 
 3623 =for docbook </entry><entry align="left">
 3624 
 3625 Binary
 3626 
 3627 =for man T}@T{
 3628 
 3629 =for html </td><td>
 3630 
 3631 =for docbook </entry><entry align="left">
 3632 
 3633 Infix
 3634 
 3635 =for man T}@T{
 3636 
 3637 =for html </td><td>
 3638 
 3639 =for docbook </entry><entry align="right">
 3640 
 3641 11
 3642 
 3643 =for man T}@T{
 3644 
 3645 =for html </td><td>
 3646 
 3647 =for docbook </entry><entry align="left">
 3648 
 3649 Non
 3650 
 3651 =for man T}@T{
 3652 
 3653 =for html </td><td>
 3654 
 3655 =for docbook </entry><entry align="left">
 3656 
 3657 Yes
 3658 
 3659 =for text }]}, 1);
 3660 
 3661 =for man T}
 3662 
 3663 =for html </td></tr>
 3664 
 3665 =for docbook </entry></row>
 3666 
 3667 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 3668 
 3669 =for man T{
 3670 
 3671 =for html <tr><td>
 3672 
 3673 =for docbook <row><entry align="left">
 3674 
 3675 Greater-Than
 3676 
 3677 =for man T}@T{
 3678 
 3679 =for html </td><td>
 3680 
 3681 =for docbook </entry><entry align="left">
 3682 
 3683 >
 3684 
 3685 =for man T}@T{
 3686 
 3687 =for html </td><td>
 3688 
 3689 =for docbook </entry><entry align="left">
 3690 
 3691 Binary
 3692 
 3693 =for man T}@T{
 3694 
 3695 =for html </td><td>
 3696 
 3697 =for docbook </entry><entry align="left">
 3698 
 3699 Infix
 3700 
 3701 =for man T}@T{
 3702 
 3703 =for html </td><td>
 3704 
 3705 =for docbook </entry><entry align="right">
 3706 
 3707 11
 3708 
 3709 =for man T}@T{
 3710 
 3711 =for html </td><td>
 3712 
 3713 =for docbook </entry><entry align="left">
 3714 
 3715 Non
 3716 
 3717 =for man T}@T{
 3718 
 3719 =for html </td><td>
 3720 
 3721 =for docbook </entry><entry align="left">
 3722 
 3723 Yes
 3724 
 3725 =for text }]}, 1);
 3726 
 3727 =for man T}
 3728 
 3729 =for html </th></tr>
 3730 
 3731 =for docbook </entry></row>
 3732 
 3733 =for docbook </thead>
 3734 
 3735 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 3736 
 3737 =for man T{
 3738 
 3739 =for html <tr><td>
 3740 
 3741 =for docbook <tbody>
 3742 
 3743 =for docbook <row><entry align="left">
 3744 
 3745 Less-Than-Or-Equal
 3746 
 3747 =for man T}@T{
 3748 
 3749 =for html </td><td>
 3750 
 3751 =for docbook </entry><entry align="left">
 3752 
 3753 <=
 3754 
 3755 =for man T}@T{
 3756 
 3757 =for html </td><td>
 3758 
 3759 =for docbook </entry><entry align="left">
 3760 
 3761 Binary
 3762 
 3763 =for man T}@T{
 3764 
 3765 =for html </td><td>
 3766 
 3767 =for docbook </entry><entry align="left">
 3768 
 3769 Infix
 3770 
 3771 =for man T}@T{
 3772 
 3773 =for html </td><td>
 3774 
 3775 =for docbook </entry><entry align="right">
 3776 
 3777 11
 3778 
 3779 =for man T}@T{
 3780 
 3781 =for html </td><td>
 3782 
 3783 =for docbook </entry><entry align="left">
 3784 
 3785 Non
 3786 
 3787 =for man T}@T{
 3788 
 3789 =for html </td><td>
 3790 
 3791 =for docbook </entry><entry align="left">
 3792 
 3793 Yes
 3794 
 3795 =for text }]}, 1);
 3796 
 3797 =for man T}
 3798 
 3799 =for html </td></tr>
 3800 
 3801 =for docbook </entry></row>
 3802 
 3803 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 3804 
 3805 =for man T{
 3806 
 3807 =for html <tr><td>
 3808 
 3809 =for docbook <row><entry align="left">
 3810 
 3811 Greater-Than-Or-Equal
 3812 
 3813 =for man T}@T{
 3814 
 3815 =for html </td><td>
 3816 
 3817 =for docbook </entry><entry align="left">
 3818 
 3819 >=
 3820 
 3821 =for man T}@T{
 3822 
 3823 =for html </td><td>
 3824 
 3825 =for docbook </entry><entry align="left">
 3826 
 3827 Binary
 3828 
 3829 =for man T}@T{
 3830 
 3831 =for html </td><td>
 3832 
 3833 =for docbook </entry><entry align="left">
 3834 
 3835 Infix
 3836 
 3837 =for man T}@T{
 3838 
 3839 =for html </td><td>
 3840 
 3841 =for docbook </entry><entry align="right">
 3842 
 3843 11
 3844 
 3845 =for man T}@T{
 3846 
 3847 =for html </td><td>
 3848 
 3849 =for docbook </entry><entry align="left">
 3850 
 3851 Non
 3852 
 3853 =for man T}@T{
 3854 
 3855 =for html </td><td>
 3856 
 3857 =for docbook </entry><entry align="left">
 3858 
 3859 Yes
 3860 
 3861 =for text }]}, 1);
 3862 
 3863 =for man T}
 3864 
 3865 =for html </td></tr>
 3866 
 3867 =for docbook </entry></row>
 3868 
 3869 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 3870 
 3871 =for man T{
 3872 
 3873 =for html <tr><td>
 3874 
 3875 =for docbook <row><entry align="left">
 3876 
 3877 Equal
 3878 
 3879 =for man T}@T{
 3880 
 3881 =for html </td><td>
 3882 
 3883 =for docbook </entry><entry align="left">
 3884 
 3885 E<61>E<61>
 3886 
 3887 =for man T}@T{
 3888 
 3889 =for html </td><td>
 3890 
 3891 =for docbook </entry><entry align="left">
 3892 
 3893 Binary
 3894 
 3895 =for man T}@T{
 3896 
 3897 =for html </td><td>
 3898 
 3899 =for docbook </entry><entry align="left">
 3900 
 3901 Infix
 3902 
 3903 =for man T}@T{
 3904 
 3905 =for html </td><td>
 3906 
 3907 =for docbook </entry><entry align="right">
 3908 
 3909 12
 3910 
 3911 =for man T}@T{
 3912 
 3913 =for html </td><td>
 3914 
 3915 =for docbook </entry><entry align="left">
 3916 
 3917 Non
 3918 
 3919 =for man T}@T{
 3920 
 3921 =for html </td><td>
 3922 
 3923 =for docbook </entry><entry align="left">
 3924 
 3925 Yes
 3926 
 3927 =for text }]}, 1);
 3928 
 3929 =for man T}
 3930 
 3931 =for html </td></tr>
 3932 
 3933 =for docbook </entry></row>
 3934 
 3935 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 3936 
 3937 =for man T{
 3938 
 3939 =for html <tr><td>
 3940 
 3941 =for docbook <row><entry align="left">
 3942 
 3943 Not-Equal
 3944 
 3945 =for man T}@T{
 3946 
 3947 =for html </td><td>
 3948 
 3949 =for docbook </entry><entry align="left">
 3950 
 3951 !=
 3952 
 3953 =for man T}@T{
 3954 
 3955 =for html </td><td>
 3956 
 3957 =for docbook </entry><entry align="left">
 3958 
 3959 Binary
 3960 
 3961 =for man T}@T{
 3962 
 3963 =for html </td><td>
 3964 
 3965 =for docbook </entry><entry align="left">
 3966 
 3967 Infix
 3968 
 3969 =for man T}@T{
 3970 
 3971 =for html </td><td>
 3972 
 3973 =for docbook </entry><entry align="right">
 3974 
 3975 12
 3976 
 3977 =for man T}@T{
 3978 
 3979 =for html </td><td>
 3980 
 3981 =for docbook </entry><entry align="left">
 3982 
 3983 Non
 3984 
 3985 =for man T}@T{
 3986 
 3987 =for html </td><td>
 3988 
 3989 =for docbook </entry><entry align="left">
 3990 
 3991 Yes
 3992 
 3993 =for text }]}, 1);
 3994 
 3995 =for man T}
 3996 
 3997 =for html </td></tr>
 3998 
 3999 =for docbook </entry></row>
 4000 
 4001 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 4002 
 4003 =for man T{
 4004 
 4005 =for html <tr><td>
 4006 
 4007 =for docbook <row><entry align="left">
 4008 
 4009 Three-Way Comparison AKA Spaceship
 4010 
 4011 =for man T}@T{
 4012 
 4013 =for html </td><td>
 4014 
 4015 =for docbook </entry><entry align="left">
 4016 
 4017 <=>
 4018 
 4019 =for man T}@T{
 4020 
 4021 =for html </td><td>
 4022 
 4023 =for docbook </entry><entry align="left">
 4024 
 4025 Binary
 4026 
 4027 =for man T}@T{
 4028 
 4029 =for html </td><td>
 4030 
 4031 =for docbook </entry><entry align="left">
 4032 
 4033 Infix
 4034 
 4035 =for man T}@T{
 4036 
 4037 =for html </td><td>
 4038 
 4039 =for docbook </entry><entry align="right">
 4040 
 4041 12
 4042 
 4043 =for man T}@T{
 4044 
 4045 =for html </td><td>
 4046 
 4047 =for docbook </entry><entry align="left">
 4048 
 4049 Non
 4050 
 4051 =for man T}@T{
 4052 
 4053 =for html </td><td>
 4054 
 4055 =for docbook </entry><entry align="left">
 4056 
 4057 Coming Soon
 4058 
 4059 =for text }]}, 1);
 4060 
 4061 =for man T}
 4062 
 4063 =for html </td></tr>
 4064 
 4065 =for docbook </entry></row>
 4066 
 4067 =begin text
 4068 
 4069 return $table->draw( ['.=','=.','=','='],   # .=============.
 4070 
 4071                      ['|','|','|'],         # | info | info |
 4072  
 4073                      ['|-','-|','=','='],   # |-===========-|
 4074 
 4075                      ['|','|','|'],         # | info | info |
 4076 
 4077                      ["'=","='",'=','='],   # '============='
 4078 
 4079                      ['|-','-|','-','+']    # rowseperator
 4080 
 4081                     );
 4082 
 4083 $z = q{<<< END TEXT EVAL >>>};
 4084 
 4085 =end text
 4086 
 4087 =for man .TE
 4088 
 4089 =for html </table>
 4090 
 4091 =for docbook </tbody></tgroup></table>
 4092 
 4093 =over
 4094 
 4095 =item * B<Less-Than>
 4096 
 4097     VALUE1 < VALUE2
 4098 
 4099 VALUE1 and VALUE2 are numeric values;
 4100 
 4101 Compare to determine relation of operands, return true if first operand VALUE1 is less-than second operand VALUE2, otherwise return false
 4102 
 4103      0 <  0  # false
 4104      0 <  1  # true
 4105      0 < -1  # false
 4106      1 <  0  # false
 4107      1 <  1  # false
 4108      1 < -1  # false
 4109     -1 <  0  # true
 4110     -1 <  1  # true
 4111     -1 < -1  # false
 4112 
 4113 =back
 4114 
 4115 =over
 4116 
 4117 =item * B<Greater-Than>
 4118 
 4119     VALUE1 > VALUE2
 4120 
 4121 VALUE1 and VALUE2 are numeric values;
 4122 
 4123 Compare to determine relation of operands, return true if first operand VALUE1 is greater-than second operand VALUE2, otherwise return false
 4124 
 4125      0 >  0  # false
 4126      0 >  1  # false
 4127      0 > -1  # true
 4128      1 >  0  # true
 4129      1 >  1  # false
 4130      1 > -1  # true
 4131     -1 >  0  # false
 4132     -1 >  1  # false
 4133     -1 > -1  # false
 4134 
 4135 =back
 4136 
 4137 =over
 4138 
 4139 =item * B<Less-Than-Or-Equal>
 4140 
 4141     VALUE1 <= VALUE2
 4142 
 4143 VALUE1 and VALUE2 are numeric values;
 4144 
 4145 Compare to determine relation of operands, return true if first operand VALUE1 is less-than or equal to second operand VALUE2, otherwise return false
 4146 
 4147      0 <=  0  # true
 4148      0 <=  1  # true
 4149      0 <= -1  # false
 4150      1 <=  0  # false
 4151      1 <=  1  # true
 4152      1 <= -1  # false
 4153     -1 <=  0  # true
 4154     -1 <=  1  # true
 4155     -1 <= -1  # true
 4156 
 4157 =back
 4158 
 4159 =over
 4160 
 4161 =item * B<Greater-Than-Or-Equal>
 4162 
 4163     VALUE1 >= VALUE2
 4164 
 4165 VALUE1 and VALUE2 are numeric values;
 4166 
 4167 Compare to determine relation of operands, return true if first operand VALUE1 is greater-than or equal to second operand VALUE2, otherwise return false
 4168 
 4169      0 >=  0  # true
 4170      0 >=  1  # false
 4171      0 >= -1  # true
 4172      1 >=  0  # true
 4173      1 >=  1  # true
 4174      1 >= -1  # true
 4175     -1 >=  0  # false
 4176     -1 >=  1  # false
 4177     -1 >= -1  # true
 4178 
 4179 =back
 4180 
 4181 =over
 4182 
 4183 =item * B<Equal>
 4184 
 4185     VALUE1 == VALUE2
 4186 
 4187 VALUE1 and VALUE2 are numeric values;
 4188 
 4189 Compare to determine equality of operands, return true if first operand VALUE1 is equal to second operand VALUE2, otherwise return false
 4190 
 4191      0 ==  0  # true
 4192      0 ==  1  # false
 4193      0 == -1  # false
 4194      1 ==  0  # false
 4195      1 ==  1  # true
 4196      1 == -1  # false
 4197     -1 ==  0  # false
 4198     -1 ==  1  # false
 4199     -1 == -1  # true
 4200 
 4201 =back
 4202 
 4203 =over
 4204 
 4205 =item * B<Not-Equal>
 4206 
 4207     VALUE1 != VALUE2
 4208 
 4209 VALUE1 and VALUE2 are numeric values;
 4210 
 4211 Compare to determine equality of operands, return true if first operand VALUE1 is not equal to second operand VALUE2, otherwise return false
 4212 
 4213      0 !=  0  # false
 4214      0 !=  1  # true
 4215      0 != -1  # true
 4216      1 !=  0  # true
 4217      1 !=  1  # false
 4218      1 != -1  # true
 4219     -1 !=  0  # true
 4220     -1 !=  1  # true
 4221     -1 != -1  # false
 4222 
 4223 =back
 4224 
 4225 =over
 4226 
 4227 =item * B<Three-Way Comparison AKA Spaceship>
 4228 
 4229     VALUE1 <=> VALUE2
 4230 
 4231 VALUE1 and VALUE2 are numeric values;
 4232 
 4233 Perform three-way comparison of operands; 
 4234 
 4235 Return -1 if first operand VALUE1 is less-than second operand VALUE2, return 0 if operands are equal, or return 1 if VALUE1 is greater-than VALUE2;
 4236 
 4237 Randal L. Schwartz coined the operator's nickname based on visual similarity to Darth Vader's TIE Advanced x1 (TIE fighter) personal spacecraft
 4238 
 4239 (Thankfully, C<E<lt>oE<gt>> and C<[=O=]> are not yet valid Perl 5 syntax)
 4240 
 4241      0 <=>  0  #  0
 4242      0 <=>  1  # -1
 4243      0 <=> -1  #  1
 4244      1 <=>  0  #  1
 4245      1 <=>  1  #  0
 4246      1 <=> -1  #  1
 4247     -1 <=>  0  # -1
 4248     -1 <=>  1  # -1
 4249     -1 <=> -1  #  0
 4250 
 4251 =back
 4252 
 4253 =head3 Section 2.1.14: Logic Operators
 4254 
 4255 =begin text
 4256 
 4257 my $z = q{<<< BEGIN TEXT EVAL >>>};
 4258 
 4259 use Text::ASCIITable;
 4260 
 4261 my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1});
 4262 
 4263 $table->setCols(splice @{[split /\s*\n\s*/, q{
 4264 
 4265 =end text
 4266 
 4267 =begin man
 4268 
 4269 .TS
 4270 allbox tab(@) ;
 4271 c c c c c c c
 4272 l l l l r l l .
 4273 
 4274 =end man
 4275 
 4276 =for html <table class="rperl operators">
 4277 
 4278 =begin docbook
 4279 
 4280 <table id="learning_rperl-section_2.1.14-table_1" label="" frame="all" colsep="1" rowsep="1">
 4281 <title>Logic Operators</title>
 4282 <tgroup cols="6">
 4283 
 4284 =end docbook
 4285 
 4286 =for man T{
 4287 
 4288 =for html <tr><th>
 4289 
 4290 =for docbook <thead>
 4291 
 4292 =for docbook <row><entry align="center">
 4293 
 4294 B<Name>
 4295 
 4296 =for man T}@T{
 4297 
 4298 =for html </th><th>
 4299 
 4300 =for docbook </entry><entry align="center">
 4301 
 4302 B<Symbol>
 4303 
 4304 =for man T}@T{
 4305 
 4306 =for html </th><th>
 4307 
 4308 =for docbook </entry><entry align="center">
 4309 
 4310 B<Arity>
 4311 
 4312 =for man T}@T{
 4313 
 4314 =for html </th><th>
 4315 
 4316 =for docbook </entry><entry align="center">
 4317 
 4318 B<Fixity>
 4319 
 4320 =for man T}@T{
 4321 
 4322 =for html </th><th>
 4323 
 4324 =for docbook </entry><entry align="center">
 4325 
 4326 B<Precedence>
 4327 
 4328 =for man T}@T{
 4329 
 4330 =for html </th><th>
 4331 
 4332 =for docbook </entry><entry align="center">
 4333 
 4334 B<Associativity>
 4335 
 4336 =for man T}@T{
 4337 
 4338 =for html </th><th>
 4339 
 4340 =for docbook </entry><entry align="center">
 4341 
 4342 B<Supported>
 4343 
 4344 =for text }]}, 1);
 4345 
 4346 =for man T}
 4347 
 4348 =for html </td></tr>
 4349 
 4350 =for docbook </entry></row>
 4351 
 4352 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 4353 
 4354 =for man T{
 4355 
 4356 =for html <tr><td>
 4357 
 4358 =for docbook <row><entry align="left">
 4359 
 4360 Logical Negation
 4361 
 4362 =for man T}@T{
 4363 
 4364 =for html </td><td>
 4365 
 4366 =for docbook </entry><entry align="left">
 4367 
 4368 !
 4369 
 4370 =for man T}@T{
 4371 
 4372 =for html </td><td>
 4373 
 4374 =for docbook </entry><entry align="left">
 4375 
 4376 Unary
 4377 
 4378 =for man T}@T{
 4379 
 4380 =for html </td><td>
 4381 
 4382 =for docbook </entry><entry align="left">
 4383 
 4384 Prefix
 4385 
 4386 =for man T}@T{
 4387 
 4388 =for html </td><td>
 4389 
 4390 =for docbook </entry><entry align="right">
 4391 
 4392 05
 4393 
 4394 =for man T}@T{
 4395 
 4396 =for html </td><td>
 4397 
 4398 =for docbook </entry><entry align="left">
 4399 
 4400 Right
 4401 
 4402 =for man T}@T{
 4403 
 4404 =for html </td><td>
 4405 
 4406 =for docbook </entry><entry align="left">
 4407 
 4408 Yes
 4409 
 4410 =for text }]}, 1);
 4411 
 4412 =for man T}
 4413 
 4414 =for html </td></tr>
 4415 
 4416 =for docbook </entry></row>
 4417 
 4418 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 4419 
 4420 =for man T{
 4421 
 4422 =for html <tr><td>
 4423 
 4424 =for docbook <row><entry align="left">
 4425 
 4426 Logical And
 4427 
 4428 =for man T}@T{
 4429 
 4430 =for html </td><td>
 4431 
 4432 =for docbook </entry><entry align="left">
 4433 
 4434 &&
 4435 
 4436 =for man T}@T{
 4437 
 4438 =for html </td><td>
 4439 
 4440 =for docbook </entry><entry align="left">
 4441 
 4442 Binary
 4443 
 4444 =for man T}@T{
 4445 
 4446 =for html </td><td>
 4447 
 4448 =for docbook </entry><entry align="left">
 4449 
 4450 Infix
 4451 
 4452 =for man T}@T{
 4453 
 4454 =for html </td><td>
 4455 
 4456 =for docbook </entry><entry align="right">
 4457 
 4458 15
 4459 
 4460 =for man T}@T{
 4461 
 4462 =for html </td><td>
 4463 
 4464 =for docbook </entry><entry align="left">
 4465 
 4466 Left
 4467 
 4468 =for man T}@T{
 4469 
 4470 =for html </td><td>
 4471 
 4472 =for docbook </entry><entry align="left">
 4473 
 4474 Yes
 4475 
 4476 =for text }]}, 1);
 4477 
 4478 =for man T}
 4479 
 4480 =for html </th></tr>
 4481 
 4482 =for docbook </entry></row>
 4483 
 4484 =for docbook </thead>
 4485 
 4486 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 4487 
 4488 =for man T{
 4489 
 4490 =for html <tr><td>
 4491 
 4492 =for docbook <tbody>
 4493 
 4494 =for docbook <row><entry align="left">
 4495 
 4496 Logical Or
 4497 
 4498 =for man T}@T{
 4499 
 4500 =for html </td><td>
 4501 
 4502 =for docbook </entry><entry align="left">
 4503 
 4504 ||
 4505 
 4506 =for man T}@T{
 4507 
 4508 =for html </td><td>
 4509 
 4510 =for docbook </entry><entry align="left">
 4511 
 4512 Binary
 4513 
 4514 =for man T}@T{
 4515 
 4516 =for html </td><td>
 4517 
 4518 =for docbook </entry><entry align="left">
 4519 
 4520 Infix
 4521 
 4522 =for man T}@T{
 4523 
 4524 =for html </td><td>
 4525 
 4526 =for docbook </entry><entry align="right">
 4527 
 4528 16
 4529 
 4530 =for man T}@T{
 4531 
 4532 =for html </td><td>
 4533 
 4534 =for docbook </entry><entry align="left">
 4535 
 4536 Left
 4537 
 4538 =for man T}@T{
 4539 
 4540 =for html </td><td>
 4541 
 4542 =for docbook </entry><entry align="left">
 4543 
 4544 Yes
 4545 
 4546 =for text }]}, 1);
 4547 
 4548 =for man T}
 4549 
 4550 =for html </th></tr>
 4551 
 4552 =for docbook </entry></row>
 4553 
 4554 =for docbook </thead>
 4555 
 4556 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 4557 
 4558 =for man T{
 4559 
 4560 =for html <tr><td>
 4561 
 4562 =for docbook <tbody>
 4563 
 4564 =for docbook <row><entry align="left">
 4565 
 4566 Logical Negation
 4567 
 4568 =for man T}@T{
 4569 
 4570 =for html </td><td>
 4571 
 4572 =for docbook </entry><entry align="left">
 4573 
 4574 not
 4575 
 4576 =for man T}@T{
 4577 
 4578 =for html </td><td>
 4579 
 4580 =for docbook </entry><entry align="left">
 4581 
 4582 Unary
 4583 
 4584 =for man T}@T{
 4585 
 4586 =for html </td><td>
 4587 
 4588 =for docbook </entry><entry align="left">
 4589 
 4590 Prefix
 4591 
 4592 =for man T}@T{
 4593 
 4594 =for html </td><td>
 4595 
 4596 =for docbook </entry><entry align="right">
 4597 
 4598 22
 4599 
 4600 =for man T}@T{
 4601 
 4602 =for html </td><td>
 4603 
 4604 =for docbook </entry><entry align="left">
 4605 
 4606 Right
 4607 
 4608 =for man T}@T{
 4609 
 4610 =for html </td><td>
 4611 
 4612 =for docbook </entry><entry align="left">
 4613 
 4614 Yes
 4615 
 4616 =for text }]}, 1);
 4617 
 4618 =for man T}
 4619 
 4620 =for html </th></tr>
 4621 
 4622 =for docbook </entry></row>
 4623 
 4624 =for docbook </thead>
 4625 
 4626 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 4627 
 4628 =for man T{
 4629 
 4630 =for html <tr><td>
 4631 
 4632 =for docbook <tbody>
 4633 
 4634 =for docbook <row><entry align="left">
 4635 
 4636 Logical And 
 4637 
 4638 =for man T}@T{
 4639 
 4640 =for html </td><td>
 4641 
 4642 =for docbook </entry><entry align="left">
 4643 
 4644 and
 4645 
 4646 =for man T}@T{
 4647 
 4648 =for html </td><td>
 4649 
 4650 =for docbook </entry><entry align="left">
 4651 
 4652 Binary
 4653 
 4654 =for man T}@T{
 4655 
 4656 =for html </td><td>
 4657 
 4658 =for docbook </entry><entry align="left">
 4659 
 4660 Infix
 4661 
 4662 =for man T}@T{
 4663 
 4664 =for html </td><td>
 4665 
 4666 =for docbook </entry><entry align="right">
 4667 
 4668 23
 4669 
 4670 =for man T}@T{
 4671 
 4672 =for html </td><td>
 4673 
 4674 =for docbook </entry><entry align="left">
 4675 
 4676 Left
 4677 
 4678 =for man T}@T{
 4679 
 4680 =for html </td><td>
 4681 
 4682 =for docbook </entry><entry align="left">
 4683 
 4684 Yes
 4685 
 4686 =for text }]}, 1);
 4687 
 4688 =for man T}
 4689 
 4690 =for html </th></tr>
 4691 
 4692 =for docbook </entry></row>
 4693 
 4694 =for docbook </thead>
 4695 
 4696 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 4697 
 4698 =for man T{
 4699 
 4700 =for html <tr><td>
 4701 
 4702 =for docbook <tbody>
 4703 
 4704 =for docbook <row><entry align="left">
 4705 
 4706 Logical Or
 4707 
 4708 =for man T}@T{
 4709 
 4710 =for html </td><td>
 4711 
 4712 =for docbook </entry><entry align="left">
 4713 
 4714 or
 4715 
 4716 =for man T}@T{
 4717 
 4718 =for html </td><td>
 4719 
 4720 =for docbook </entry><entry align="left">
 4721 
 4722 Binary
 4723 
 4724 =for man T}@T{
 4725 
 4726 =for html </td><td>
 4727 
 4728 =for docbook </entry><entry align="left">
 4729 
 4730 Infix
 4731 
 4732 =for man T}@T{
 4733 
 4734 =for html </td><td>
 4735 
 4736 =for docbook </entry><entry align="right">
 4737 
 4738 24
 4739 
 4740 =for man T}@T{
 4741 
 4742 =for html </td><td>
 4743 
 4744 =for docbook </entry><entry align="left">
 4745 
 4746 Left
 4747 
 4748 =for man T}@T{
 4749 
 4750 =for html </td><td>
 4751 
 4752 =for docbook </entry><entry align="left">
 4753 
 4754 Yes
 4755 
 4756 =for text }]}, 1);
 4757 
 4758 =for man T}
 4759 
 4760 =for html </th></tr>
 4761 
 4762 =for docbook </entry></row>
 4763 
 4764 =for docbook </thead>
 4765 
 4766 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 4767 
 4768 =for man T{
 4769 
 4770 =for html <tr><td>
 4771 
 4772 =for docbook <tbody>
 4773 
 4774 =for docbook <row><entry align="left">
 4775 
 4776 Logical Xor
 4777 
 4778 =for man T}@T{
 4779 
 4780 =for html </td><td>
 4781 
 4782 =for docbook </entry><entry align="left">
 4783 
 4784 xor
 4785 
 4786 =for man T}@T{
 4787 
 4788 =for html </td><td>
 4789 
 4790 =for docbook </entry><entry align="left">
 4791 
 4792 Binary
 4793 
 4794 =for man T}@T{
 4795 
 4796 =for html </td><td>
 4797 
 4798 =for docbook </entry><entry align="left">
 4799 
 4800 Infix
 4801 
 4802 =for man T}@T{
 4803 
 4804 =for html </td><td>
 4805 
 4806 =for docbook </entry><entry align="right">
 4807 
 4808 24
 4809 
 4810 =for man T}@T{
 4811 
 4812 =for html </td><td>
 4813 
 4814 =for docbook </entry><entry align="left">
 4815 
 4816 Left
 4817 
 4818 =for man T}@T{
 4819 
 4820 =for html </td><td>
 4821 
 4822 =for docbook </entry><entry align="left">
 4823 
 4824 Yes
 4825 
 4826 =for text }]}, 1);
 4827 
 4828 =for man T}
 4829 
 4830 =for html </td></tr>
 4831 
 4832 =for docbook </entry></row>
 4833 
 4834 =begin text
 4835 
 4836 return $table->draw( ['.=','=.','=','='],   # .=============.
 4837 
 4838                      ['|','|','|'],         # | info | info |
 4839  
 4840                      ['|-','-|','=','='],   # |-===========-|
 4841 
 4842                      ['|','|','|'],         # | info | info |
 4843 
 4844                      ["'=","='",'=','='],   # '============='
 4845 
 4846                      ['|-','-|','-','+']    # rowseperator
 4847 
 4848                     );
 4849 
 4850 $z = q{<<< END TEXT EVAL >>>};
 4851 
 4852 =end text
 4853 
 4854 =for man .TE
 4855 
 4856 =for html </table>
 4857 
 4858 =for docbook </tbody></tgroup></table>
 4859 
 4860 =over
 4861 
 4862 =item * B<Logical Negation>
 4863 
 4864     ! VALUE
 4865     not VALUE
 4866 
 4867 VALUE is numeric value;
 4868 
 4869 Take logical negation of operand VALUE, return result;
 4870 
 4871 Logical negation operators C<!> and C<not> return the same results, and differ only by precedence
 4872 
 4873     !    0  # true
 4874     !    1  # false
 4875     !   -1  # false
 4876 
 4877     not  0  # true
 4878     not  1  # false
 4879     not -1  # false
 4880 
 4881 =back
 4882 
 4883 =over
 4884 
 4885 =item * B<Logical And>
 4886 
 4887     VALUE1 && VALUE2
 4888     VALUE1 and VALUE2
 4889 
 4890 VALUE1 and VALUE2 are numeric values;
 4891 
 4892 Take logical conjunction of operands VALUE1 and VALUE2, return result;
 4893 
 4894 Logical and operators C<&&> and C<and> return the same results, and differ only by precedence
 4895 
 4896      0 &&   0  # false
 4897      0 &&   1  # false
 4898      0 &&  -1  # false
 4899      1 &&   0  # false
 4900      1 &&   1  # true
 4901      1 &&  -1  # true
 4902     -1 &&   0  # false
 4903     -1 &&   1  # true
 4904     -1 &&  -1  # true
 4905 
 4906      0 and  0  # false
 4907      0 and  1  # false
 4908      0 and -1  # false
 4909      1 and  0  # false
 4910      1 and  1  # true
 4911      1 and -1  # true
 4912     -1 and  0  # false
 4913     -1 and  1  # true
 4914     -1 and -1  # true
 4915 
 4916 =back
 4917 
 4918 =over
 4919 
 4920 =item * B<Logical Or>
 4921 
 4922     VALUE1 || VALUE2
 4923     VALUE1 or VALUE2
 4924 
 4925 VALUE1 and VALUE2 are numeric values;
 4926 
 4927 Take logical disjunction of operands VALUE1 and VALUE2, return result;
 4928 
 4929 Logical or operators C<||> and C<or> return the same results, and differ only by precedence
 4930 
 4931      0 ||  0  # false
 4932      0 ||  1  # true
 4933      0 || -1  # true
 4934      1 ||  0  # true
 4935      1 ||  1  # true
 4936      1 || -1  # true
 4937     -1 ||  0  # true
 4938     -1 ||  1  # true
 4939     -1 || -1  # true
 4940 
 4941      0 or  0  # false
 4942      0 or  1  # true
 4943      0 or -1  # true
 4944      1 or  0  # true
 4945      1 or  1  # true
 4946      1 or -1  # true
 4947     -1 or  0  # true
 4948     -1 or  1  # true
 4949     -1 or -1  # true
 4950 
 4951 =back
 4952 
 4953 =over
 4954 
 4955 =item * B<Logical Xor>
 4956 
 4957     VALUE1 xor VALUE2
 4958 
 4959 VALUE1 and VALUE2 are numeric values;
 4960 
 4961 Take logical exclusive disjunction of operands VALUE1 and VALUE2, return result
 4962 
 4963      0 xor  0  # false
 4964      0 xor  1  # true
 4965      0 xor -1  # true
 4966      1 xor  0  # true
 4967      1 xor  1  # false
 4968      1 xor -1  # false
 4969     -1 xor  0  # true
 4970     -1 xor  1  # false
 4971     -1 xor -1  # false
 4972 
 4973 =back
 4974 
 4975 =head3 Section 2.1.15: Bitwise Operators
 4976 
 4977 =begin text
 4978 
 4979 my $z = q{<<< BEGIN TEXT EVAL >>>};
 4980 
 4981 use Text::ASCIITable;
 4982 
 4983 my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1});
 4984 
 4985 $table->setCols(splice @{[split /\s*\n\s*/, q{
 4986 
 4987 =end text
 4988 
 4989 =begin man
 4990 
 4991 .TS
 4992 allbox tab(@) ;
 4993 c c c c c c c
 4994 l l l l r l l .
 4995 
 4996 =end man
 4997 
 4998 =for html <table class="rperl operators">
 4999 
 5000 =begin docbook
 5001 
 5002 <table id="learning_rperl-section_2.1.15-table_1" label="" frame="all" colsep="1" rowsep="1">
 5003 <title>Bitwise Operators</title>
 5004 <tgroup cols="6">
 5005 
 5006 =end docbook
 5007 
 5008 =for man T{
 5009 
 5010 =for html <tr><th>
 5011 
 5012 =for docbook <thead>
 5013 
 5014 =for docbook <row><entry align="center">
 5015 
 5016 B<Name>
 5017 
 5018 =for man T}@T{
 5019 
 5020 =for html </th><th>
 5021 
 5022 =for docbook </entry><entry align="center">
 5023 
 5024 B<Symbol>
 5025 
 5026 =for man T}@T{
 5027 
 5028 =for html </th><th>
 5029 
 5030 =for docbook </entry><entry align="center">
 5031 
 5032 B<Arity>
 5033 
 5034 =for man T}@T{
 5035 
 5036 =for html </th><th>
 5037 
 5038 =for docbook </entry><entry align="center">
 5039 
 5040 B<Fixity>
 5041 
 5042 =for man T}@T{
 5043 
 5044 =for html </th><th>
 5045 
 5046 =for docbook </entry><entry align="center">
 5047 
 5048 B<Precedence>
 5049 
 5050 =for man T}@T{
 5051 
 5052 =for html </th><th>
 5053 
 5054 =for docbook </entry><entry align="center">
 5055 
 5056 B<Associativity>
 5057 
 5058 =for man T}@T{
 5059 
 5060 =for html </th><th>
 5061 
 5062 =for docbook </entry><entry align="center">
 5063 
 5064 B<Supported>
 5065 
 5066 =for text }]}, 1);
 5067 
 5068 =for man T}
 5069 
 5070 =for html </td></tr>
 5071 
 5072 =for docbook </entry></row>
 5073 
 5074 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 5075 
 5076 =for man T{
 5077 
 5078 =for html <tr><td>
 5079 
 5080 =for docbook <row><entry align="left">
 5081 
 5082 Bitwise Negation with Parentheses
 5083 
 5084 =for man T}@T{
 5085 
 5086 =for html </td><td>
 5087 
 5088 =for docbook </entry><entry align="left">
 5089 
 5090 ~( )
 5091 
 5092 =for man T}@T{
 5093 
 5094 =for html </td><td>
 5095 
 5096 =for docbook </entry><entry align="left">
 5097 
 5098 Unary
 5099 
 5100 =for man T}@T{
 5101 
 5102 =for html </td><td>
 5103 
 5104 =for docbook </entry><entry align="left">
 5105 
 5106 Closed
 5107 
 5108 =for man T}@T{
 5109 
 5110 =for html </td><td>
 5111 
 5112 =for docbook </entry><entry align="right">
 5113 
 5114 05
 5115 
 5116 =for man T}@T{
 5117 
 5118 =for html </td><td>
 5119 
 5120 =for docbook </entry><entry align="left">
 5121 
 5122 Right
 5123 
 5124 =for man T}@T{
 5125 
 5126 =for html </td><td>
 5127 
 5128 =for docbook </entry><entry align="left">
 5129 
 5130 Yes
 5131 
 5132 =for text }]}, 1);
 5133 
 5134 =for man T}
 5135 
 5136 =for html </th></tr>
 5137 
 5138 =for docbook </entry></row>
 5139 
 5140 =for docbook </thead>
 5141 
 5142 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 5143 
 5144 =for man T{
 5145 
 5146 =for html <tr><td>
 5147 
 5148 =for docbook <tbody>
 5149 
 5150 =for docbook <row><entry align="left">
 5151 
 5152 Bitwise Shift Left 
 5153 
 5154 =for man T}@T{
 5155 
 5156 =for html </td><td>
 5157 
 5158 =for docbook </entry><entry align="left">
 5159 
 5160 <<
 5161 
 5162 =for man T}@T{
 5163 
 5164 =for html </td><td>
 5165 
 5166 =for docbook </entry><entry align="left">
 5167 
 5168 Binary
 5169 
 5170 =for man T}@T{
 5171 
 5172 =for html </td><td>
 5173 
 5174 =for docbook </entry><entry align="left">
 5175 
 5176 Infix
 5177 
 5178 =for man T}@T{
 5179 
 5180 =for html </td><td>
 5181 
 5182 =for docbook </entry><entry align="right">
 5183 
 5184 09
 5185 
 5186 =for man T}@T{
 5187 
 5188 =for html </td><td>
 5189 
 5190 =for docbook </entry><entry align="left">
 5191 
 5192 Left
 5193 
 5194 =for man T}@T{
 5195 
 5196 =for html </td><td>
 5197 
 5198 =for docbook </entry><entry align="left">
 5199 
 5200 Coming Soon
 5201 
 5202 =for text }]}, 1);
 5203 
 5204 =for man T}
 5205 
 5206 =for html </th></tr>
 5207 
 5208 =for docbook </entry></row>
 5209 
 5210 =for docbook </thead>
 5211 
 5212 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 5213 
 5214 =for man T{
 5215 
 5216 =for html <tr><td>
 5217 
 5218 =for docbook <tbody>
 5219 
 5220 =for docbook <row><entry align="left">
 5221 
 5222 Bitwise Shift Right
 5223 
 5224 =for man T}@T{
 5225 
 5226 =for html </td><td>
 5227 
 5228 =for docbook </entry><entry align="left">
 5229 
 5230 >>
 5231 
 5232 =for man T}@T{
 5233 
 5234 =for html </td><td>
 5235 
 5236 =for docbook </entry><entry align="left">
 5237 
 5238 Binary
 5239 
 5240 =for man T}@T{
 5241 
 5242 =for html </td><td>
 5243 
 5244 =for docbook </entry><entry align="left">
 5245 
 5246 Infix
 5247 
 5248 =for man T}@T{
 5249 
 5250 =for html </td><td>
 5251 
 5252 =for docbook </entry><entry align="right">
 5253 
 5254 09
 5255 
 5256 =for man T}@T{
 5257 
 5258 =for html </td><td>
 5259 
 5260 =for docbook </entry><entry align="left">
 5261 
 5262 Left
 5263 
 5264 =for man T}@T{
 5265 
 5266 =for html </td><td>
 5267 
 5268 =for docbook </entry><entry align="left">
 5269 
 5270 Coming Soon
 5271 
 5272 =for text }]}, 1);
 5273 
 5274 =for man T}
 5275 
 5276 =for html </td></tr>
 5277 
 5278 =for docbook </entry></row>
 5279 
 5280 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 5281 
 5282 =for man T{
 5283 
 5284 =for html <tr><td>
 5285 
 5286 =for docbook <row><entry align="left">
 5287 
 5288 Bitwise And
 5289 
 5290 =for man T}@T{
 5291 
 5292 =for html </td><td>
 5293 
 5294 =for docbook </entry><entry align="left">
 5295 
 5296 &
 5297 
 5298 =for man T}@T{
 5299 
 5300 =for html </td><td>
 5301 
 5302 =for docbook </entry><entry align="left">
 5303 
 5304 Binary
 5305 
 5306 =for man T}@T{
 5307 
 5308 =for html </td><td>
 5309 
 5310 =for docbook </entry><entry align="left">
 5311 
 5312 Infix
 5313 
 5314 =for man T}@T{
 5315 
 5316 =for html </td><td>
 5317 
 5318 =for docbook </entry><entry align="right">
 5319 
 5320 13
 5321 
 5322 =for man T}@T{
 5323 
 5324 =for html </td><td>
 5325 
 5326 =for docbook </entry><entry align="left">
 5327 
 5328 Left
 5329 
 5330 =for man T}@T{
 5331 
 5332 =for html </td><td>
 5333 
 5334 =for docbook </entry><entry align="left">
 5335 
 5336 Coming Soon
 5337 
 5338 =for text }]}, 1);
 5339 
 5340 =for man T}
 5341 
 5342 =for html </td></tr>
 5343 
 5344 =for docbook </entry></row>
 5345 
 5346 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 5347 
 5348 =for man T{
 5349 
 5350 =for html <tr><td>
 5351 
 5352 =for docbook <row><entry align="left">
 5353 
 5354 Bitwise Or
 5355 
 5356 =for man T}@T{
 5357 
 5358 =for html </td><td>
 5359 
 5360 =for docbook </entry><entry align="left">
 5361 
 5362 |
 5363 
 5364 =for man T}@T{
 5365 
 5366 =for html </td><td>
 5367 
 5368 =for docbook </entry><entry align="left">
 5369 
 5370 Binary
 5371 
 5372 =for man T}@T{
 5373 
 5374 =for html </td><td>
 5375 
 5376 =for docbook </entry><entry align="left">
 5377 
 5378 Infix
 5379 
 5380 =for man T}@T{
 5381 
 5382 =for html </td><td>
 5383 
 5384 =for docbook </entry><entry align="right">
 5385 
 5386 14
 5387 
 5388 =for man T}@T{
 5389 
 5390 =for html </td><td>
 5391 
 5392 =for docbook </entry><entry align="left">
 5393 
 5394 Left
 5395 
 5396 =for man T}@T{
 5397 
 5398 =for html </td><td>
 5399 
 5400 =for docbook </entry><entry align="left">
 5401 
 5402 Coming Soon
 5403 
 5404 =for text }]}, 1);
 5405 
 5406 =for man T}
 5407 
 5408 =for html </td></tr>
 5409 
 5410 =for docbook </entry></row>
 5411 
 5412 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 5413 
 5414 =for man T{
 5415 
 5416 =for html <tr><td>
 5417 
 5418 =for docbook <row><entry align="left">
 5419 
 5420 Bitwise Xor
 5421 
 5422 =for man T}@T{
 5423 
 5424 =for html </td><td>
 5425 
 5426 =for docbook </entry><entry align="left">
 5427 
 5428 ^
 5429 
 5430 =for man T}@T{
 5431 
 5432 =for html </td><td>
 5433 
 5434 =for docbook </entry><entry align="left">
 5435 
 5436 Binary
 5437 
 5438 =for man T}@T{
 5439 
 5440 =for html </td><td>
 5441 
 5442 =for docbook </entry><entry align="left">
 5443 
 5444 Infix
 5445 
 5446 =for man T}@T{
 5447 
 5448 =for html </td><td>
 5449 
 5450 =for docbook </entry><entry align="right">
 5451 
 5452 14
 5453 
 5454 =for man T}@T{
 5455 
 5456 =for html </td><td>
 5457 
 5458 =for docbook </entry><entry align="left">
 5459 
 5460 Left
 5461 
 5462 =for man T}@T{
 5463 
 5464 =for html </td><td>
 5465 
 5466 =for docbook </entry><entry align="left">
 5467 
 5468 Coming Soon
 5469 
 5470 =for text }]}, 1);
 5471 
 5472 =for man T}
 5473 
 5474 =for html </td></tr>
 5475 
 5476 =for docbook </entry></row>
 5477 
 5478 =begin text
 5479 
 5480 return $table->draw( ['.=','=.','=','='],   # .=============.
 5481 
 5482                      ['|','|','|'],         # | info | info |
 5483  
 5484                      ['|-','-|','=','='],   # |-===========-|
 5485 
 5486                      ['|','|','|'],         # | info | info |
 5487 
 5488                      ["'=","='",'=','='],   # '============='
 5489 
 5490                      ['|-','-|','-','+']    # rowseperator
 5491 
 5492                     );
 5493 
 5494 $z = q{<<< END TEXT EVAL >>>};
 5495 
 5496 =end text
 5497 
 5498 =for man .TE
 5499 
 5500 =for html </table>
 5501 
 5502 =for docbook </tbody></tgroup></table>
 5503 
 5504 All code examples are shown using 64-bit integers; your results may vary depending upon your C++ compiler and hardware platform.
 5505 
 5506 B<WARNING FOR ALL BITWISE OPERATORS:>
 5507 
 5508 B<Due to the difference between how integer and non-integer scalar values are stored in memory, you may experience unexpected or undefined behavior if a bitwise operator is passed any non-integer operands as input.>
 5509 
 5510 B<Only utilize bitwise operators with integer, unsigned_integer, or boolean operands.>
 5511 
 5512     ~(1)      # good use of bitwise negation    operator
 5513     12 << 2   # good use of bitwise shift left  operator
 5514     13 >> 3   # good use of bitwise shift right operator
 5515 
 5516     my unsigned_integer $foo = 14;
 5517     $foo & 4  # good use of bitwise and operator
 5518     $foo | 5  # good use of bitwise  or operator
 5519     $foo ^ 6  # good use of bitwise xor operator
 5520 
 5521     my number $bar = 21.12;
 5522     ~($bar)         # UNEXPECTED BEHAVIOR: bad use of bitwise negation    operator
 5523       $bar <<    7  # UNEXPECTED BEHAVIOR: bad use of bitwise shift left  operator
 5524          8 >> $bar  # UNEXPECTED BEHAVIOR: bad use of bitwise shift right operator
 5525 
 5526     23.42 &   9   # UNEXPECTED BEHAVIOR: bad use of bitwise and operator
 5527     23    ^ 1.1   # UNEXPECTED BEHAVIOR: bad use of bitwise xor operator
 5528 
 5529 B<Also, due to the difference between how signed and unsigned integer values are stored in memory, both Perl's C<use integer;> pragma configuration command as well as RPerl's C<integer> and C<unsigned_integer> data types must be utilized in correct combination, as described below.  Perl relies on the C<use integer;> pragma to determine numeric data types, while C++ relies on the actual data types provided by the software developers as part of each variable declaration.  You may experience unexpected behavior if a bitwise operator is utilized with mismatching pragma and data types.>
 5530 
 5531 B<Each call to Perl's C<use integer;> pragma applies to 1 entire RPerl source code file at a time, either 1 full *.pl program file or 1 full *.pm module file.  If the C<use integer;> pragma is in effect for a specific RPerl file, then all bitwise operators in said file must be provided with input operands which are signed (positive or negative) integers only, not unsigned integers or floating-point numbers or other data types.  If C<use integer;> is not in effect for an RPerl file, then all bitwise operators in said file must be provided with operands which are unsigned (non-negative) integers or booleans only, not signed integers or other data types.>
 5532 
 5533 B<The C<use integer;> pragma also affects the results of all arithmetic and comparison operators by discarding the non-integer (fractional) portion of input operands, as if the C<floor> operator were called to convert each floating-point number into an integer.  Because of this, floating-point operators and signed integer bitwise operators must not be included in the same single RPerl source code file; to compensate, simply move all signed bitwise operators into their own separate RPerl *.pm module file which calls C<use integer;>.>
 5534 
 5535 B<Please see the Perl documentation for more information about the C<use integer;> pragma:>
 5536 
 5537 L<http://perldoc.perl.org/integer.html>
 5538 
 5539     # good combination: no 'use integer;' pragma, 
 5540     # unsigned_integer data types for bitwise negation operator, number data type for multiplication operation
 5541     my unsigned_integer $foo = 5;
 5542     my unsigned_integer $bar = ~($foo);  # $bar  = 18_446_744_073_709_551_610
 5543     my number $quux = 21.12 * 42.23;     # $quux = 891.897_6
 5544 
 5545 X<break_code_blocks>
 5546 
 5547 
 5548     # good combination: 'use integer;' pragma,
 5549     # integer data types for both bitwise negation operator and multiplication operator
 5550     use integer;
 5551     my integer $foo = 5;
 5552     my integer $bar = ~($foo);   # $bar  = -6
 5553     my integer $quux = 21 * 42;  # $quux =  882
 5554 
 5555 X<break_code_blocks>
 5556 
 5557 
 5558     # bad combination: no 'use integer;' pragma, 
 5559     # integer data types for bitwise negation operator
 5560     my integer $foo = 5;
 5561     my integer $bar = ~($foo);   # UNEXPECTED BEHAVIOR: ($bar = 18_446_744_073_709_551_610) in Perl, but ($bar = -6) in C++
 5562 
 5563 X<break_code_blocks>
 5564 
 5565 
 5566     # bad combination: 'use integer;' pragma,
 5567     # unsigned_integer data types for bitwise negation operator, number data type for multiplication operator
 5568     use integer;
 5569     my unsigned_integer $foo = 5;
 5570     my unsigned_integer $bar = ~($foo);  # UNEXPECTED BEHAVIOR: ($bar = -6) in Perl, but ($bar = 18_446_744_073_709_551_610) in C++
 5571     my number $quux = 21.12 * 42.23;     # UNEXPECTED BEHAVIOR: ($quux = 882) in Perl, but ($quux = 891.897_6) in C++
 5572 
 5573 =over
 5574 
 5575 =item * B<Bitwise Negation with Parentheses>
 5576 
 5577     ~( VALUE )
 5578 
 5579 VALUE is numeric value;
 5580 
 5581 Negate each bit of operand VALUE, return result;
 5582 
 5583 May be used to take one's complement of VALUE;
 5584 
 5585 Parentheses must be used, due to ambiguity of tilde C<~> character as used for bitwise negation operator, smartmatch operator C<~~>, or regular expression C<=~>
 5586 
 5587     ~(-8)  #                          7
 5588     ~(-2)  #                          1
 5589     ~(-1)  #                          0
 5590     ~( 0)  # 18_446_744_073_709_551_615
 5591     ~( 1)  # 18_446_744_073_709_551_614
 5592     ~( 2)  # 18_446_744_073_709_551_613
 5593     ~( 8)  # 18_446_744_073_709_551_607
 5594 
 5595 X<break_code_blocks>
 5596 
 5597 
 5598     use integer;
 5599     ~(-8)  #  7
 5600     ~(-2)  #  1
 5601     ~(-1)  #  0
 5602     ~( 0)  # -1
 5603     ~( 1)  # -2
 5604     ~( 2)  # -3
 5605     ~( 8)  # -9
 5606 
 5607 =back
 5608 
 5609 =over
 5610 
 5611 =item * B<Bitwise Shift Left>
 5612 
 5613     VALUE1 << VALUE2
 5614 
 5615 VALUE1 and VALUE2 are numeric values;
 5616 
 5617 Shift left the value of first operand VALUE1 by number of bits specified by second operand VALUE2, return result;
 5618 
 5619 May be used to multiply VALUE1 by 2 raised to the power of VALUE2
 5620 
 5621     1 << 0  #  1
 5622     1 << 1  #  2
 5623     1 << 2  #  4
 5624     1 << 3  #  8
 5625     2 << 0  #  2
 5626     2 << 1  #  4
 5627     2 << 2  #  8
 5628     2 << 3  # 16
 5629     2 << 4  # 32
 5630     2 << 5  # 64
 5631 
 5632 X<break_code_blocks>
 5633 
 5634 
 5635     -1 << -8  # 18_374_686_479_671_623_680
 5636     -1 << -1  #  9_223_372_036_854_775_808
 5637     -1 <<  0  # 18_446_744_073_709_551_615
 5638     -1 <<  1  # 18_446_744_073_709_551_614
 5639     -1 <<  8  # 18_446_744_073_709_551_360
 5640      0 << -8  #                          0
 5641      0 << -1  #                          0
 5642      0 <<  0  #                          0
 5643      0 <<  1  #                          0
 5644      0 <<  8  #                          0
 5645      1 << -8  #     72_057_594_037_927_936
 5646      1 << -1  #  9_223_372_036_854_775_808
 5647      1 <<  0  #                          1
 5648      1 <<  1  #                          2
 5649      1 <<  8  #                        256
 5650 
 5651 X<break_code_blocks>
 5652 
 5653 
 5654     use integer;
 5655     -1 << -8  #    -72_057_594_037_927_936
 5656     -1 << -1  # -9_223_372_036_854_775_808
 5657     -1 <<  0  #                         -1
 5658     -1 <<  1  #                         -2
 5659     -1 <<  8  #                       -256
 5660      0 << -8  #                          0
 5661      0 << -1  #                          0
 5662      0 <<  0  #                          0
 5663      0 <<  1  #                          0
 5664      0 <<  8  #                          0
 5665      1 << -8  #     72_057_594_037_927_936
 5666      1 << -1  # -9_223_372_036_854_775_808
 5667      1 <<  0  #                          1
 5668      1 <<  1  #                          2
 5669      1 <<  8  #                        256
 5670 
 5671 =back
 5672 
 5673 =over
 5674 
 5675 =item * B<Bitwise Shift Right>
 5676 
 5677     VALUE1 >> VALUE2
 5678 
 5679 VALUE1 and VALUE2 are numeric values;
 5680 
 5681 Shift right the value of first operand VALUE1 by number of bits specified by second operand VALUE2, return result;
 5682 
 5683 May be used to divide VALUE1 by 2 raised to the power of VALUE2
 5684 
 5685      8 >>  0  #  8
 5686      8 >>  1  #  4
 5687      8 >>  2  #  2
 5688      8 >>  3  #  1
 5689     64 >>  0  # 64
 5690     64 >>  1  # 32
 5691     64 >>  2  # 16
 5692     64 >>  3  #  8
 5693     64 >>  4  #  4
 5694     64 >>  5  #  2
 5695     64 >>  8  #  1
 5696 
 5697 X<break_code_blocks>
 5698 
 5699 
 5700     -1 >> -8  #                        255
 5701     -1 >> -1  #                          1
 5702     -1 >>  0  # 18_446_744_073_709_551_615
 5703     -1 >>  1  #  9_223_372_036_854_775_807
 5704     -1 >>  8  #     72_057_594_037_927_935
 5705      0 >> -8  #                          0
 5706      0 >> -1  #                          0
 5707      0 >>  0  #                          0
 5708      0 >>  1  #                          0
 5709      0 >>  8  #                          0
 5710      1 >> -8  #                          0
 5711      1 >> -1  #                          0
 5712      1 >>  0  #                          1
 5713      1 >>  1  #                          0
 5714      1 >>  8  #                          0
 5715 
 5716 X<break_code_blocks>
 5717 
 5718 
 5719     use integer;
 5720     -1 >> -8  # -1
 5721     -1 >> -1  # -1
 5722     -1 >>  0  # -1
 5723     -1 >>  1  # -1
 5724     -1 >>  8  # -1
 5725      0 >> -8  #  0
 5726      0 >> -1  #  0
 5727      0 >>  0  #  0
 5728      0 >>  1  #  0
 5729      0 >>  8  #  0
 5730      1 >> -8  #  0
 5731      1 >> -1  #  0
 5732      1 >>  0  #  1
 5733      1 >>  1  #  0
 5734      1 >>  8  #  0
 5735 
 5736 =back
 5737 
 5738 =over
 5739 
 5740 =item * B<Bitwise And>
 5741 
 5742     VALUE1 & VALUE2
 5743 
 5744 VALUE1 and VALUE2 are numeric values;
 5745 
 5746 Take conjunction of each bit of first operand VALUE1 with respective bit of second operand VALUE2, return result
 5747 
 5748     -1 & -8  # 18_446_744_073_709_551_608
 5749     -1 & -1  # 18_446_744_073_709_551_615
 5750     -1 &  0  #                          0
 5751     -1 &  1  #                          1
 5752     -1 &  8  #                          8
 5753      0 & -8  #                          0
 5754      0 & -1  #                          0
 5755      0 &  0  #                          0
 5756      0 &  1  #                          0
 5757      0 &  8  #                          0
 5758      1 & -8  #                          0
 5759      1 & -1  #                          1
 5760      1 &  0  #                          0
 5761      1 &  1  #                          1
 5762      1 &  8  #                          0
 5763 
 5764 X<break_code_blocks>
 5765 
 5766 
 5767     use integer;
 5768     -1 & -8  # -8
 5769     -1 & -1  # -1
 5770     -1 &  0  #  0
 5771     -1 &  1  #  1
 5772     -1 &  8  #  8
 5773      0 & -8  #  0
 5774      0 & -1  #  0
 5775      0 &  0  #  0
 5776      0 &  1  #  0
 5777      0 &  8  #  0
 5778      1 & -8  #  0
 5779      1 & -1  #  1
 5780      1 &  0  #  0
 5781      1 &  1  #  1
 5782      1 &  8  #  0
 5783 
 5784 =back
 5785 
 5786 =over
 5787 
 5788 =item * B<Bitwise Or>
 5789 
 5790     VALUE1 | VALUE2
 5791 
 5792 VALUE1 and VALUE2 are numeric values;
 5793 
 5794 Take disjunction of each bit of first operand VALUE1 with respective bit of second operand VALUE2, return result
 5795 
 5796     -1 | -8  # 18_446_744_073_709_551_615
 5797     -1 | -1  # 18_446_744_073_709_551_615
 5798     -1 |  0  # 18_446_744_073_709_551_615
 5799     -1 |  1  # 18_446_744_073_709_551_615
 5800     -1 |  8  # 18_446_744_073_709_551_615
 5801      0 | -8  # 18_446_744_073_709_551_608
 5802      0 | -1  # 18_446_744_073_709_551_615
 5803      0 |  0  #                          0
 5804      0 |  1  #                          1
 5805      0 |  8  #                          8
 5806      1 | -8  # 18_446_744_073_709_551_609
 5807      1 | -1  # 18_446_744_073_709_551_615
 5808      1 |  0  #                          1
 5809      1 |  1  #                          1
 5810      1 |  8  #                          9
 5811 
 5812 X<break_code_blocks>
 5813 
 5814 
 5815     use integer;
 5816     -1 | -8  # -1
 5817     -1 | -1  # -1
 5818     -1 |  0  # -1
 5819     -1 |  1  # -1
 5820     -1 |  8  # -1
 5821      0 | -8  # -8
 5822      0 | -1  # -1
 5823      0 |  0  #  0
 5824      0 |  1  #  1
 5825      0 |  8  #  8
 5826      1 | -8  # -7
 5827      1 | -1  # -1
 5828      1 |  0  #  1
 5829      1 |  1  #  1
 5830      1 |  8  #  9
 5831 
 5832 =back
 5833 
 5834 =over
 5835 
 5836 =item * B<Bitwise Xor>
 5837 
 5838     VALUE1 ^ VALUE2
 5839 
 5840 VALUE1 and VALUE2 are numeric values;
 5841 
 5842 Take exclusive disjunction of each bit of first operand VALUE1 with respective bit of second operand VALUE2, return result
 5843 
 5844     -1 ^ -8  #                          7
 5845     -1 ^ -1  #                          0
 5846     -1 ^  0  # 18_446_744_073_709_551_615
 5847     -1 ^  1  # 18_446_744_073_709_551_614
 5848     -1 ^  8  # 18_446_744_073_709_551_607
 5849      0 ^ -8  # 18_446_744_073_709_551_608
 5850      0 ^ -1  # 18_446_744_073_709_551_615
 5851      0 ^  0  #                          0
 5852      0 ^  1  #                          1
 5853      0 ^  8  #                          8
 5854      1 ^ -8  # 18_446_744_073_709_551_609
 5855      1 ^ -1  # 18_446_744_073_709_551_614
 5856      1 ^  0  #                          1
 5857      1 ^  1  #                          0
 5858      1 ^  8  #                          9
 5859 
 5860 X<break_code_blocks>
 5861 
 5862 
 5863     use integer;
 5864     -1 ^ -8  #  7
 5865     -1 ^ -1  #  0
 5866     -1 ^  0  # -1
 5867     -1 ^  1  # -2
 5868     -1 ^  8  # -9
 5869      0 ^ -8  # -8
 5870      0 ^ -1  # -1
 5871      0 ^  0  #  0
 5872      0 ^  1  #  1
 5873      0 ^  8  #  8
 5874      1 ^ -8  # -7
 5875      1 ^ -1  # -2
 5876      1 ^  0  #  1
 5877      1 ^  1  #  0
 5878      1 ^  8  #  9
 5879 
 5880 =back
 5881 
 5882 =head3 Section 2.1.16: Miscellaneous Operators
 5883 
 5884 =begin text
 5885 
 5886 my $z = q{<<< BEGIN TEXT EVAL >>>};
 5887 
 5888 use Text::ASCIITable;
 5889 
 5890 my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1});
 5891 
 5892 $table->setCols(splice @{[split /\s*\n\s*/, q{
 5893 
 5894 =end text
 5895 
 5896 =begin man
 5897 
 5898 .TS
 5899 allbox tab(@) ;
 5900 c c c c c c c
 5901 l l l l r l l .
 5902 
 5903 =end man
 5904 
 5905 =for html <table class="rperl operators">
 5906 
 5907 =begin docbook
 5908 
 5909 <table id="learning_rperl-section_2.1.16-table_1" label="" frame="all" colsep="1" rowsep="1">
 5910 <title>Miscellaneous Operators</title>
 5911 <tgroup cols="6">
 5912 
 5913 =end docbook
 5914 
 5915 =for man T{
 5916 
 5917 =for html <tr><th>
 5918 
 5919 =for docbook <thead>
 5920 
 5921 =for docbook <row><entry align="center">
 5922 
 5923 B<Name>
 5924 
 5925 =for man T}@T{
 5926 
 5927 =for html </th><th>
 5928 
 5929 =for docbook </entry><entry align="center">
 5930 
 5931 B<Symbol>
 5932 
 5933 =for man T}@T{
 5934 
 5935 =for html </th><th>
 5936 
 5937 =for docbook </entry><entry align="center">
 5938 
 5939 B<Arity>
 5940 
 5941 =for man T}@T{
 5942 
 5943 =for html </th><th>
 5944 
 5945 =for docbook </entry><entry align="center">
 5946 
 5947 B<Fixity>
 5948 
 5949 =for man T}@T{
 5950 
 5951 =for html </th><th>
 5952 
 5953 =for docbook </entry><entry align="center">
 5954 
 5955 B<Precedence>
 5956 
 5957 =for man T}@T{
 5958 
 5959 =for html </th><th>
 5960 
 5961 =for docbook </entry><entry align="center">
 5962 
 5963 B<Associativity>
 5964 
 5965 =for man T}@T{
 5966 
 5967 =for html </th><th>
 5968 
 5969 =for docbook </entry><entry align="center">
 5970 
 5971 B<Supported>
 5972 
 5973 =for text }]}, 1);
 5974 
 5975 =for man T}
 5976 
 5977 =for html </td></tr>
 5978 
 5979 =for docbook </entry></row>
 5980 
 5981 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 5982 
 5983 =for man T{
 5984 
 5985 =for html <tr><td>
 5986 
 5987 =for docbook <row><entry align="left">
 5988 
 5989 Floor with Parentheses
 5990 
 5991 =for man T}@T{
 5992 
 5993 =for html </td><td>
 5994 
 5995 =for docbook </entry><entry align="left">
 5996 
 5997 POSIX::floor( )
 5998 
 5999 =for man T}@T{
 6000 
 6001 =for html </td><td>
 6002 
 6003 =for docbook </entry><entry align="left">
 6004 
 6005 Unary
 6006 
 6007 =for man T}@T{
 6008 
 6009 =for html </td><td>
 6010 
 6011 =for docbook </entry><entry align="left">
 6012 
 6013 Closed
 6014 
 6015 =for man T}@T{
 6016 
 6017 =for html </td><td>
 6018 
 6019 =for docbook </entry><entry align="right">
 6020 
 6021 01
 6022 
 6023 =for man T}@T{
 6024 
 6025 =for html </td><td>
 6026 
 6027 =for docbook </entry><entry align="left">
 6028 
 6029 Left
 6030 
 6031 =for man T}@T{
 6032 
 6033 =for html </td><td>
 6034 
 6035 =for docbook </entry><entry align="left">
 6036 
 6037 Coming Soon
 6038 
 6039 =for text }]}, 1);
 6040 
 6041 =for man T}
 6042 
 6043 =for html </td></tr>
 6044 
 6045 =for docbook </entry></row>
 6046 
 6047 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 6048 
 6049 =for man T{
 6050 
 6051 =for html <tr><td>
 6052 
 6053 =for docbook <row><entry align="left">
 6054 
 6055 Ceiling with Parentheses
 6056 
 6057 =for man T}@T{
 6058 
 6059 =for html </td><td>
 6060 
 6061 =for docbook </entry><entry align="left">
 6062 
 6063 POSIX::ceil( )
 6064 
 6065 =for man T}@T{
 6066 
 6067 =for html </td><td>
 6068 
 6069 =for docbook </entry><entry align="left">
 6070 
 6071 Unary
 6072 
 6073 =for man T}@T{
 6074 
 6075 =for html </td><td>
 6076 
 6077 =for docbook </entry><entry align="left">
 6078 
 6079 Closed
 6080 
 6081 =for man T}@T{
 6082 
 6083 =for html </td><td>
 6084 
 6085 =for docbook </entry><entry align="right">
 6086 
 6087 01
 6088 
 6089 =for man T}@T{
 6090 
 6091 =for html </td><td>
 6092 
 6093 =for docbook </entry><entry align="left">
 6094 
 6095 Left
 6096 
 6097 =for man T}@T{
 6098 
 6099 =for html </td><td>
 6100 
 6101 =for docbook </entry><entry align="left">
 6102 
 6103 Coming Soon
 6104 
 6105 =for text }]}, 1);
 6106 
 6107 =for man T}
 6108 
 6109 =for html </td></tr>
 6110 
 6111 =for docbook </entry></row>
 6112 
 6113 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 6114 
 6115 =for man T{
 6116 
 6117 =for html <tr><td>
 6118 
 6119 =for docbook <row><entry align="left">
 6120 
 6121 Separate Integer & Fraction Parts with Parentheses
 6122 
 6123 =for man T}@T{
 6124 
 6125 =for html </td><td>
 6126 
 6127 =for docbook </entry><entry align="left">
 6128 
 6129 POSIX::modf( )
 6130 
 6131 =for man T}@T{
 6132 
 6133 =for html </td><td>
 6134 
 6135 =for docbook </entry><entry align="left">
 6136 
 6137 Binary
 6138 
 6139 =for man T}@T{
 6140 
 6141 =for html </td><td>
 6142 
 6143 =for docbook </entry><entry align="left">
 6144 
 6145 Closed
 6146 
 6147 =for man T}@T{
 6148 
 6149 =for html </td><td>
 6150 
 6151 =for docbook </entry><entry align="right">
 6152 
 6153 01
 6154 
 6155 =for man T}@T{
 6156 
 6157 =for html </td><td>
 6158 
 6159 =for docbook </entry><entry align="left">
 6160 
 6161 Left
 6162 
 6163 =for man T}@T{
 6164 
 6165 =for html </td><td>
 6166 
 6167 =for docbook </entry><entry align="left">
 6168 
 6169 Coming Soon
 6170 
 6171 =for text }]}, 1);
 6172 
 6173 =for man T}
 6174 
 6175 =for html </td></tr>
 6176 
 6177 =for docbook </entry></row>
 6178 
 6179 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 6180 
 6181 =for man T{
 6182 
 6183 =for html <tr><td>
 6184 
 6185 =for docbook <row><entry align="left">
 6186 
 6187 Integer Part
 6188 
 6189 =for man T}@T{
 6190 
 6191 =for html </td><td>
 6192 
 6193 =for docbook </entry><entry align="left">
 6194 
 6195 int
 6196 
 6197 =for man T}@T{
 6198 
 6199 =for html </td><td>
 6200 
 6201 =for docbook </entry><entry align="left">
 6202 
 6203 Unary
 6204 
 6205 =for man T}@T{
 6206 
 6207 =for html </td><td>
 6208 
 6209 =for docbook </entry><entry align="left">
 6210 
 6211 Prefix
 6212 
 6213 =for man T}@T{
 6214 
 6215 =for html </td><td>
 6216 
 6217 =for docbook </entry><entry align="right">
 6218 
 6219 10
 6220 
 6221 =for man T}@T{
 6222 
 6223 =for html </td><td>
 6224 
 6225 =for docbook </entry><entry align="left">
 6226 
 6227 Non
 6228 
 6229 =for man T}@T{
 6230 
 6231 =for html </td><td>
 6232 
 6233 =for docbook </entry><entry align="left">
 6234 
 6235 Coming Soon
 6236 
 6237 =for text }]}, 1);
 6238 
 6239 =for man T}
 6240 
 6241 =for html </td></tr>
 6242 
 6243 =for docbook </entry></row>
 6244 
 6245 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 6246 
 6247 =for man T{
 6248 
 6249 =for html <tr><td>
 6250 
 6251 =for docbook <row><entry align="left">
 6252 
 6253 Random Number
 6254 
 6255 =for man T}@T{
 6256 
 6257 =for html </td><td>
 6258 
 6259 =for docbook </entry><entry align="left">
 6260 
 6261 rand
 6262 
 6263 =for man T}@T{
 6264 
 6265 =for html </td><td>
 6266 
 6267 =for docbook </entry><entry align="left">
 6268 
 6269 Nullary or Unary
 6270 
 6271 =for man T}@T{
 6272 
 6273 =for html </td><td>
 6274 
 6275 =for docbook </entry><entry align="left">
 6276 
 6277 Prefix
 6278 
 6279 =for man T}@T{
 6280 
 6281 =for html </td><td>
 6282 
 6283 =for docbook </entry><entry align="right">
 6284 
 6285 10
 6286 
 6287 =for man T}@T{
 6288 
 6289 =for html </td><td>
 6290 
 6291 =for docbook </entry><entry align="left">
 6292 
 6293 Non
 6294 
 6295 =for man T}@T{
 6296 
 6297 =for html </td><td>
 6298 
 6299 =for docbook </entry><entry align="left">
 6300 
 6301 Coming Soon
 6302 
 6303 =for text }]}, 1);
 6304 
 6305 =for man T}
 6306 
 6307 =for html </th></tr>
 6308 
 6309 =for docbook </entry></row>
 6310 
 6311 =for docbook </thead>
 6312 
 6313 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 6314 
 6315 =for man T{
 6316 
 6317 =for html <tr><td>
 6318 
 6319 =for docbook <tbody>
 6320 
 6321 =for docbook <row><entry align="left">
 6322 
 6323 Random Seed
 6324 
 6325 =for man T}@T{
 6326 
 6327 =for html </td><td>
 6328 
 6329 =for docbook </entry><entry align="left">
 6330 
 6331 srand
 6332 
 6333 =for man T}@T{
 6334 
 6335 =for html </td><td>
 6336 
 6337 =for docbook </entry><entry align="left">
 6338 
 6339 Nullary or Unary
 6340 
 6341 =for man T}@T{
 6342 
 6343 =for html </td><td>
 6344 
 6345 =for docbook </entry><entry align="left">
 6346 
 6347 Prefix
 6348 
 6349 =for man T}@T{
 6350 
 6351 =for html </td><td>
 6352 
 6353 =for docbook </entry><entry align="right">
 6354 
 6355 10
 6356 
 6357 =for man T}@T{
 6358 
 6359 =for html </td><td>
 6360 
 6361 =for docbook </entry><entry align="left">
 6362 
 6363 Non
 6364 
 6365 =for man T}@T{
 6366 
 6367 =for html </td><td>
 6368 
 6369 =for docbook </entry><entry align="left">
 6370 
 6371 Coming Soon
 6372 
 6373 =for text }]}, 1);
 6374 
 6375 =for man T}
 6376 
 6377 =for html </td></tr>
 6378 
 6379 =for docbook </entry></row>
 6380 
 6381 =begin text
 6382 
 6383 return $table->draw( ['.=','=.','=','='],   # .=============.
 6384 
 6385                      ['|','|','|'],         # | info | info |
 6386  
 6387                      ['|-','-|','=','='],   # |-===========-|
 6388 
 6389                      ['|','|','|'],         # | info | info |
 6390 
 6391                      ["'=","='",'=','='],   # '============='
 6392 
 6393                      ['|-','-|','-','+']    # rowseperator
 6394 
 6395                     );
 6396 
 6397 $z = q{<<< END TEXT EVAL >>>};
 6398 
 6399 =end text
 6400 
 6401 =for man .TE
 6402 
 6403 =for html </table>
 6404 
 6405 =for docbook </tbody></tgroup></table>
 6406 
 6407 =over
 6408 
 6409 =item * B<Floor with Parentheses>
 6410 
 6411     POSIX::floor( VALUE )
 6412 
 6413 VALUE is numeric value;
 6414 
 6415 If operand VALUE contains fractional part, then return next lowest integer, otherwise return VALUE unchanged;
 6416 
 6417 Not a Perl built-in operator, it is a Perl subroutine (which happens to provide an interface to the underlying C subroutine of the same name); thus, C<POSIX::floor()> must be called with both the preceding C<POSIX::> namespace and parentheses around the operand
 6418 
 6419     POSIX::floor( 0)  #  0
 6420     POSIX::floor( 1)  #  1
 6421     POSIX::floor(-1)  # -1
 6422 
 6423     POSIX::floor(1.1)  # 1
 6424     POSIX::floor(1.5)  # 1
 6425     POSIX::floor(1.9)  # 1
 6426 
 6427     POSIX::floor(-2.2)  # -3
 6428     POSIX::floor(-2.6)  # -3
 6429     POSIX::floor(-2.8)  # -3
 6430 
 6431 =back
 6432 
 6433 =over
 6434 
 6435 =item * B<Ceiling with Parentheses>
 6436 
 6437     POSIX::ceil( VALUE )
 6438 
 6439 VALUE is numeric value;
 6440 
 6441 If operand VALUE contains fractional part, then return next highest integer, otherwise return VALUE unchanged;
 6442 
 6443 Not a Perl built-in operator, it is a Perl subroutine (which happens to provide an interface to the underlying C subroutine of the same name); thus, C<POSIX::ceil()> must be called with both the preceding C<POSIX::> namespace and parentheses around the operand
 6444 
 6445     POSIX::ceil( 0)  #  0
 6446     POSIX::ceil( 1)  #  1
 6447     POSIX::ceil(-1)  # -1
 6448 
 6449     POSIX::ceil(1.1)  # 2
 6450     POSIX::ceil(1.5)  # 2
 6451     POSIX::ceil(1.9)  # 2
 6452 
 6453     POSIX::ceil(-2.2)  # -2
 6454     POSIX::ceil(-2.6)  # -2
 6455     POSIX::ceil(-2.8)  # -2
 6456 
 6457 =back
 6458 
 6459 =over
 6460 
 6461 =item * B<Separate Integer & Fraction Parts with Parentheses>
 6462 
 6463     POSIX::modf( VALUE )
 6464 
 6465 VALUE is numeric value;
 6466 
 6467 Break apart operand VALUE into integer part and fraction part, return both, fraction part first;
 6468 
 6469 Not a Perl built-in operator, it is a Perl subroutine (which happens to provide an interface to the underlying C subroutine of the same name); thus, C<POSIX::modf()> must be called with both the preceding C<POSIX::> namespace and parentheses around the operand;
 6470 
 6471 Returns more than one return value (always two); thus, must be wrapped in square-brackets C<[ ]> and stored in C<number_arrayref> data structure, then individual parts accessed via thin-arrow C<-E<gt>> array dereference and element retrieval
 6472 
 6473     POSIX::modf( 0)  # 0,  0
 6474     POSIX::modf( 1)  # 0,  1
 6475     POSIX::modf(-1)  # 0, -1
 6476 
 6477     POSIX::modf(1.1)  # 0.1, 1
 6478     POSIX::modf(1.5)  # 0.5, 1
 6479     POSIX::modf(1.9)  # 0.9, 1
 6480 
 6481     POSIX::modf(-2.2)  # -0.2, -2
 6482     POSIX::modf(-2.6)  # -0.6, -2
 6483     POSIX::modf(-2.8)  # -0.8, -2
 6484 
 6485 X<break_code_blocks>
 6486 
 6487 
 6488     my number_hashref $retvals = [POSIX::modf(-3.141_59)];  # -0.141_59, -3
 6489     my number $integer_part    = $retvals->[1];  # -3
 6490     my number $fraction_part   = $retvals->[0];  # -0.141_59
 6491 
 6492 =back
 6493 
 6494 =over
 6495 
 6496 =item * B<Integer Part>
 6497 
 6498     int VALUE
 6499 
 6500 VALUE is numeric value;
 6501 
 6502 Discard fractional component of operand VALUE, return result
 6503 
 6504 B<WARNING, FLOATING-POINT ERROR:>
 6505 
 6506 B<The C<int> operator may produce unexpected behavior due to floating-point error; you may instead prefer use of the C<POSIX::floor()>, C<POSIX::ceil()>, and C<POSIX::modf()> subroutines.>
 6507 
 6508     int  0  #  0
 6509     int  1  #  1
 6510     int -1  # -1
 6511 
 6512     int 1.1  # 1
 6513     int 1.5  # 1
 6514     int 1.9  # 1
 6515 
 6516     int -2.2  # -2
 6517     int -2.6  # -2
 6518     int -2.8  # -2
 6519 
 6520 X<break_code_blocks>
 6521 
 6522 
 6523     int               (-4.725 / 0.025)  # UNEXPECTED BEHAVIOR: -188 due to floating-point error
 6524     -189 ==           (-4.725 / 0.025)  # UNEXPECTED BEHAVIOR: false, values in memory do not match
 6525     printf "%.18f\n", (-4.725 / 0.025)  # UNEXPECTED BEHAVIOR: -188.999_999_999_999_971_578 due to floating-point error
 6526     print             (-4.725 / 0.025)  #   EXPECTED BEHAVIOR: -189 due to automatic floating-point epsilon checking
 6527     POSIX::floor      (-4.725 / 0.025)  #   EXPECTED BEHAVIOR: -189 due to explicitly forcing to next lowest integer 
 6528 
 6529 =back
 6530 
 6531 =over
 6532 
 6533 =item * B<Random Number>
 6534 
 6535     rand
 6536     rand VALUE
 6537 
 6538 VALUE is numeric value;
 6539 
 6540 Returns pseudo-random floating-point number between 0 and operand VALUE, defaults to VALUE of 1 if omitted;
 6541 
 6542 Generated pseudo-random number is based on seed value passed to C<srand> operator, and C<srand> is called automatically if not called explicitly
 6543 
 6544 B<WARNING, SECURITY LIABILITY:>
 6545 
 6546 B<The C<rand> operator is not considered to be cryptographically secure pseudo-random number generator (CSPRNG), and should thus not be utilized for cryptography or other security-sensitive purposes.> 
 6547 
 6548     rand     # between 0 and 1
 6549     rand 1   # between 0 and 1
 6550     rand 10  # between 0 and 10
 6551 
 6552 =back
 6553 
 6554 =over
 6555 
 6556 =item * B<Random Seed>
 6557 
 6558     srand
 6559     srand VALUE
 6560 
 6561 VALUE is numeric value;
 6562 
 6563 Seed C<rand> operator with operand VALUE, defaults to automatically-selected VALUE if omitted;
 6564 
 6565 Entropy (randomness) is decreased if called more than once per program;
 6566 
 6567 If C<srand> is called with a specific seed value followed by one or more calls to C<rand>, then you call C<srand> with the same seed value followed by C<rand> again, you will receive the same value(s) returned by C<rand> after both calls to C<srand>
 6568 
 6569     srand       # seed is automatically chosen
 6570     srand 1     # seed is 1
 6571     srand 10    # seed is 10
 6572     srand time  # seed is number of non-leap seconds since epoch, usually Unix epoch (19700101 AKA 1970.001 AKA January 1st 1970)
 6573 
 6574 X<break_code_blocks>
 6575 
 6576     srand 23;
 6577     print to_string(rand), "\n";  # 0.199_281_135_414_825
 6578     print to_string(rand), "\n";  # 0.955_482_658_089_267
 6579     print to_string(rand), "\n";  # 0.080_619_594_120_559
 6580     srand 23;
 6581     print to_string(rand), "\n";  # 0.199_281_135_414_825 REPEATED
 6582     print to_string(rand), "\n";  # 0.955_482_658_089_267 REPEATED
 6583     print to_string(rand), "\n";  # 0.080_619_594_120_559 REPEATED
 6584 
 6585 =back
 6586 
 6587 =head2 Section 2.2: Text Data & Operators
 6588 
 6589 RPerl provides 2 text data types:
 6590 
 6591 =over
 6592 
 6593 =item * C<character>
 6594 
 6595 S< >S< >S< >S< >a single text character; either a letter, number, or special character
 6596 
 6597 =item * C<string>
 6598 
 6599 S< >S< >S< >S< >one or more text characters; any combination of letters, numbers, and special characters
 6600 
 6601 =back
 6602 
 6603 RPerl provides 3 delimiters for enclosing text data:
 6604 
 6605 =over
 6606 
 6607 =item * Single-Quotes
 6608 
 6609 C<'I am a single-quoted string literal'>
 6610 
 6611 =back
 6612 
 6613 =over
 6614 
 6615 =item * Double-Quotes
 6616 
 6617 C<"I am a double-quoted string literal">
 6618 
 6619 =back
 6620 
 6621 =over
 6622 
 6623 =item * q Quotes
 6624 
 6625 C<q{I am a q-quoted string literal}>
 6626 
 6627 =back
 6628 
 6629 Perl 5 provides several built-in operators designed for use with text data, which can be organized into 7 general categories:
 6630 
 6631 =over
 6632 
 6633 =item * Editing
 6634 
 6635 =item * Case
 6636 
 6637 =item * Comparison (Relational & Equality)
 6638 
 6639 =item * Search
 6640 
 6641 =item * Formatting
 6642 
 6643 =item * Base
 6644 
 6645 =item * Miscellaneous
 6646 
 6647 =back
 6648 
 6649 =head3 Section 2.2.1: Character Literals
 6650 
 6651 The most memory-efficient text literal is C<character>, which represents exactly zero characters or one character of information.  A C<character> may express the value of any single numeric digit (0, 1, 2, ..., 8, 9); letter (a, b, c, ..., y, z, A, B, C, ..., Y, Z ); or special ASCII character (!, #, *, +, etc).  If the C<character> literal has length zero, meaning it represents zero characters of information, then it is called the I<"empty character"> and contains no data.
 6652 
 6653     ''           # INVALID: use q{} for empty character
 6654     '0'          #   VALID
 6655     'h'          #   VALID
 6656     '+'          #   VALID
 6657     '\n'         # INVALID: too many characters, use "\n" for newline character
 6658     '-1'         # INVALID: too many characters
 6659     'howdy23!'   # INVALID: too many characters
 6660 
 6661     ""           # INVALID: use q{} for empty character
 6662     "0"          #   VALID
 6663     "h"          #   VALID
 6664     "+"          #   VALID
 6665     "\n"         #   VALID: newline
 6666     "-1"         # INVALID: too many characters & invalid use of double-quotes
 6667     "howdy23!"   # INVALID: too many characters & invalid use of double-quotes
 6668 
 6669     q{}          #   VALID: empty
 6670     q{0}         #   VALID
 6671     q{h}         #   VALID
 6672     q{+}         #   VALID
 6673     q{\n}        # INVALID: too many characters, use "\n" for newline character
 6674     q{-1}        # INVALID: too many characters
 6675     q{howdy23!}  # INVALID: too many characters
 6676 
 6677 =head3 Section 2.2.2: String Literals
 6678 
 6679 Any text data more than 1 character in length must be represented by a C<string> literal, which is comprised of any combination of valid C<character> literal characters (numeric digits, letters, and special ASCII characters).  Like the empty character, if a C<string> literal has length zero then it is called the I<"empty string"> and contains no data.
 6680 
 6681     ''           # INVALID: use q{} for empty string
 6682     '0'          #   VALID
 6683     'h'          #   VALID
 6684     '+'          #   VALID
 6685     '\n'         # INVALID: not a newline, use "\n" for string containing newline
 6686     '\\n'        #   VALID: interpolated to become two characters (backslash, letter n)
 6687     '-1'         #   VALID
 6688     'howdy23!'   #   VALID
 6689 
 6690     ""           # INVALID: use q{} for empty string
 6691     "0"          # INVALID: invalid use of double-quotes, must contain newline or tab character(s)
 6692     "h"          # INVALID: invalid use of double-quotes, must contain newline or tab character(s)
 6693     "+"          # INVALID: invalid use of double-quotes, must contain newline or tab character(s)
 6694     "\n"         #   VALID: interpolated to become newline character
 6695     "-1"         # INVALID: invalid use of double-quotes, must contain newline or tab character(s)
 6696     "howdy23!"   # INVALID: invalid use of double-quotes, must contain newline or tab character(s)
 6697 
 6698     q{}          #   VALID: empty string
 6699     q{0}         #   VALID
 6700     q{h}         #   VALID
 6701     q{+}         #   VALID
 6702     q{\n}        # INVALID: not a newline, use "\n" for string containing newline
 6703     q{\\n}       #   VALID: interpolated to become two characters (backslash, letter n)
 6704     q{-1}        #   VALID
 6705     q{howdy23!}  #   VALID
 6706 
 6707 =head3 Section 2.2.3: Single-Quotes
 6708 
 6709 Text literals enclosed in single-quotes are the simplest and most common case in RPerl.
 6710 
 6711 Single-quoted text literals are not I<"interpolated">, which means the literal's data contents are not changed by Perl or RPerl in any way, except for the extra-special double-backslash C<\\> as described below.  Because single-quotes do not activate string interpolation, you can not use a single-quoted string literal to represent special characters such as newline or tab.
 6712 
 6713 Do not use single-quotes to represent a newline or tab character, use double-quotes C<"\n"> or C<"\t"> instead.
 6714 
 6715 Do not use single-quotes to represent an empty character or empty string, use q-quotes C<q{}> instead.
 6716 
 6717 In normal Perl, single-backslash characters C<\> are used to create special characters called I<"escape sequences">, the most common of which are the well-known newline C<\n> and tab C<\t> escape sequences.  Each valid escape sequence actually counts as only one character of computer data, even though it is represented to humans by 2 or more typed characters, so a single escape sequence may be utilized as either a C<character> text literal or a C<string> text literal.  (Thus, C<"\n"> and C<"\t"> may both be utilized as either a C<character> or C<string> in RPerl, but only when using double-quotes as discussed in the following section.)
 6718 
 6719 In single-quoted string literals, the only escape sequence supported by RPerl is the double-backslash C<\\>, so the string literal C<'\\'> is interpolated to mean only one single-backslash character C<\>.  To represent two backslash characters C<\\>, utilize two double-backslash escape sequences in a row C<'\\\\'>; for three backslashes C<\\\> utilize three escape sequences C<'\\\\\\'>, and so forth.
 6720 
 6721 Because RPerl only accepts double-backslashes (not single-backslashes) within single-quotes, RPerl thus does not accept any odd number of consecutive backslash characters within single-quotes.  For example, two or four backslashes in a row are supported, but one or three or five directly adjacent backslashes are not supported.
 6722 
 6723 In normal Perl, the backslash single-quote C<\'> escape sequence may be used to include a single-quote character C<'> within a single-quoted text literal.  As stated above, RPerl only supports the double-backslash C<\\> escape sequence within single-quotes, so the backslash single-quote C<\'> escape sequence is thus not supported.  Use double-quotes C<"'"> or q-quotes C<q{'}> to represent a single-quote C<'> character in an RPerl string literal.
 6724 
 6725 Single-quoted text literals must B<not> contain:
 6726 
 6727 =over
 6728 
 6729 =item * Single-Quote Character: C<'>
 6730 
 6731 =item * Single-Backslash Character: C<\>
 6732 
 6733 =item * Odd Number Of Consecutive Backslash Characters: C<\\\> C<\\\\\> C<\\\\\\\>
 6734 
 6735 =item * No Characters AKA Empty String
 6736 
 6737 =back
 6738 
 6739 Single-quoted text literals may contain:
 6740 
 6741 =over
 6742 
 6743 =item * Double-Quote Character: C<">
 6744 
 6745 =item * Right-Curly-Brace Character: C<}>
 6746 
 6747 =item * Double-Backslash Characters: C<\\>
 6748 
 6749 =item * Even Number Of Consecutive Backslash Characters: C<\\\\> C<\\\\\\> C<\\\\\\\\>
 6750 
 6751 =item * Any Other Characters
 6752 
 6753 =back
 6754 
 6755     ''      # INVALID: empty string
 6756     ' '     #   VALID: single space
 6757     'a'     #   VALID: single letter
 6758     '\'     # INVALID: single-backslash
 6759 
 6760     '   '   #   VALID: three spaces
 6761     ' ' '   # INVALID: single-quote within single-quotes
 6762     '\' '   # INVALID: backslash single-quote escape sequence, also single-backslash
 6763 
 6764     ' a '   #   VALID: space, letter, space
 6765     '"a}'   #   VALID: double-quote, letter, right brace
 6766     '\a}'   # INVALID: single-backslash       not interpolated as audible bell (alarm beep) escape sequence
 6767     '\n}'   # INVALID: single-backslash       not interpolated as newline                   escape sequence
 6768     '\\}'   #   VALID: double-backslash           interpolated as one backslash character, right brace
 6769     '\\\'   # INVALID: odd  number of backslashes 
 6770     '\\\\'  #   VALID: even number of backslashes interpolated as half as many backslash characters
 6771 
 6772 =for html <u>
 6773 
 6774 I<BEST PRACTICES>
 6775 
 6776 =over
 6777 
 6778 =item * I<Use single-quoted text literals whenever possible.>
 6779 
 6780 =back
 6781 
 6782 =for html </u>
 6783 
 6784     'n'      #     BEST PRACTICE
 6785     "n"      # NOT BEST PRACTICE: double-quotes not needed
 6786     q{n}     # NOT BEST PRACTICE:      q-quotes not needed
 6787 
 6788     '1atx'   #     BEST PRACTICE
 6789     "1atx"   # NOT BEST PRACTICE: double-quotes not needed
 6790     q{1atx}  # NOT BEST PRACTICE:      q-quotes not needed
 6791 
 6792     '\\tx'   #     BEST PRACTICE
 6793     "\\tx"   # NOT BEST PRACTICE: double-quotes    invalid, extra backslash
 6794     q{\\tx}  # NOT BEST PRACTICE:      q-quotes not needed
 6795 
 6796 =head3 Section 2.2.4: Double-Quotes
 6797 
 6798 Text literals enclosed in double-quotes are fully interpolated in normal Perl, and are only used for trivial interpolation of strings containing the newline C<"\n"> or tab C<"\t"> escape sequences in RPerl.  All double-quoted strings in RPerl must contain at least one newline or tab special character.
 6799 
 6800 In addition to escape sequences, string interpolation in normal Perl is also triggered by finding either the dollar-sign C<$> or I<"at-sign"> C<@> characters inside of a double-quoted string literal.  Because RPerl does not support string interpolation, double-quoted string literals must not contain the C<$> or C<@> characters.
 6801 
 6802 Double-quoted string literals must not contain any backslash characters, other than those used in newline C<\n> and tab C<\t> escape sequences, and thus can not represent a single-backslash character C<\>; use single-quotes C<'\\'> or q-quotes C<q{\\}> double-backslash escape sequences instead. 
 6803 
 6804 As with single-quotes, in normal Perl the backslash double-quote C<\"> escape sequence may be used to include a double-quote character C<"> within a double-quoted text literal.  As stated above, RPerl only supports the newline C<\n> and tab C<\t> escape sequences within double-quotes, so the backslash double-quote C<\"> escape sequence is thus not supported.  Use single-quotes C<'"'> or q-quotes C<q{"}> to represent a double-quote C<"> character in an RPerl string literal.
 6805 
 6806 Double-quoted text literals must B<not> contain:
 6807 
 6808 =over
 6809 
 6810 =item * Double-Quote Character: C<">
 6811 
 6812 =item * Dollar-Sign Character: C<$>
 6813 
 6814 =item * At-Sign Character: C<@>
 6815 
 6816 =item * Extra Backslash Characters (Other Than C<\n> Or C<\t>): C<\> C<\\> C<\\\> C<\r> C<123\456>
 6817 
 6818 =item * No Characters AKA Empty String
 6819 
 6820 =back
 6821 
 6822 Double-quoted text literals B<must> contain 1 or more:
 6823 
 6824 =over
 6825 
 6826 =item * Newline Character: C<\n>
 6827 
 6828 =item * Tab Character: C<\t>
 6829 
 6830 =back
 6831 
 6832 Double-quoted text literals may contain:
 6833 
 6834 =over
 6835 
 6836 =item * Single-Quote Character: C<'>
 6837 
 6838 =item * Right-Curly-Brace Character: C<}>
 6839 
 6840 =item * Any Other Characters
 6841 
 6842 =back
 6843 
 6844     ""      # INVALID: empty string
 6845     " "     #   VALID: single space
 6846     "a"     #   VALID: single letter
 6847     "\"     # INVALID: extra  backslash,                                                                     only \n and \t supported
 6848 
 6849     "   "   #   VALID: three spaces
 6850     " " "   # INVALID: double-quote within double-quotes
 6851     "\" "   # INVALID: backslash double-quote escape sequence, also single-backslash
 6852 
 6853     " a "   #   VALID: space, letter, space
 6854     "'a}"   #   VALID: single-quote, letter, right brace
 6855     "\a}"   # INVALID: single-backslash           interpolated as audible bell (alarm beep) escape sequence, only \n and \t supported
 6856     "\n}"   #   VALID: single-backslash           interpolated as newline                   escape sequence, right brace
 6857     "\\}"   # INVALID: extra  backslashes,                                                                   only \n and \t supported
 6858     "\\\"   # INVALID: extra  backslashes,                                                                   only \n and \t supported 
 6859     "\\\\"  # INVALID: extra  backslashes,                                                                   only \n and \t supported
 6860 
 6861 =for html <u>
 6862 
 6863 I<BEST PRACTICES>
 6864 
 6865 =over
 6866 
 6867 =item * I<Use double-quoted text literals to contain newline C<\n> and tab C<\t> characters only, not other normal characters.>
 6868 
 6869 =item * I<To represent a mixture of normal characters with newline and/or tab characters, enclose the normal characters in single-quotes, enclose the newline and tab characters in double-quotes, and use the dot C<.> "string concatenation" operator to append one string literal to the other.  (Please see L</Section 2.2.6: Editing Operators> for more information about string concatenation.)>
 6870 
 6871 =back
 6872 
 6873 =for html </u>
 6874 
 6875     "\n"        #     BEST PRACTICE:     newline         only
 6876     "\t"        #     BEST PRACTICE:                 tab only
 6877     "\t\n\t"    #     BEST PRACTICE:     newline and tab only
 6878 
 6879     "a\n"       # NOT BEST PRACTICE: not newline and tab only
 6880     'a' . "\n"  #     BEST PRACTICE:     newline         only, additional characters in single-quotes
 6881 
 6882     "\tx"       # NOT BEST PRACTICE: not newline and tab only
 6883     "\t" . 'x'  #     BEST PRACTICE:                 tab only, additional characters in single-quotes
 6884 
 6885     "a\tx\n"                 # NOT BEST PRACTICE: not newline and tab only
 6886     'a' . "\t" . 'x' . "\n"  #     BEST PRACTICE:     newline and tab only, additional characters in single-quotes
 6887 
 6888 =head3 Section 2.2.5: C<q> Quotes
 6889 
 6890 Text literals enclosed in I<"q-quotes"> begin with lowercase letter q and left I<"curly-brace"> characters C<q{>, and end with the right curly-brace C<}> character.  You must use q-quotes to represent empty text C<q{}> literals, which contain no characters.  Curly braces are also known as I<"curly-brackets"> or just I<"braces"> for short.
 6891 
 6892 Normal Perl supports q-quoted string literals using delimiters other than curly-braces, as well as I<"qq-quotes"> which provide string interpolation in the same way as double-quoted strings.  RPerl's existing string quoting mechanisms cover all non-interpolated use cases, so RPerl does not support the additional qq-quotes or non-curly-brace q-quotes, because TDNNTBMTOWTDI.
 6893 
 6894 q-quoted literals behave exactly the same as single-quoted literals, other than the empty string C<q{}> and the difference in delimiters.
 6895 
 6896 q-quoted text literals must B<not> contain:
 6897 
 6898 =over
 6899 
 6900 =item * Right-Curly-Brace Character: C<}>
 6901 
 6902 =item * Single-Backslash Character: C<\>
 6903 
 6904 =item * Odd Number Of Consecutive Backslash Characters: C<\\\> C<\\\\\> C<\\\\\\\>
 6905 
 6906 =back
 6907 
 6908 q-quoted text literals may contain:
 6909 
 6910 =over
 6911 
 6912 =item * Single-Quote Character: C<'>
 6913 
 6914 =item * Double-Quote Character: C<">
 6915 
 6916 =item * Double-Backslash Characters: C<\\>
 6917 
 6918 =item * Even Number Of Consecutive Backslash Characters: C<\\\\> C<\\\\\\> C<\\\\\\\\>
 6919 
 6920 =item * No Characters AKA Empty String
 6921 
 6922 =item * Any Other Characters
 6923 
 6924 =back
 6925 
 6926     q{}      #   VALID: empty string
 6927     q{ }     #   VALID: single space
 6928     q{a}     #   VALID: single letter
 6929     q{\}     # INVALID: single-backslash
 6930 
 6931     q{   }   #   VALID: three spaces
 6932     q{ } }   # INVALID: right brace within q-quotes
 6933     q{\} }   # INVALID: backslash right brace escape sequence, also single-backslash
 6934 
 6935     q{ a }   #   VALID: space, letter, space
 6936     q{"a'}   #   VALID: double-quote, letter, single-quote
 6937     q{\a'}   # INVALID: single-backslash       not interpolated as audible bell (alarm beep) escape sequence
 6938     q{\n'}   # INVALID: single-backslash       not interpolated as newline                   escape sequence
 6939     q{\\'}   #   VALID: double-backslash           interpolated as one backslash character, single-quote
 6940     q{\\\}   # INVALID: odd  number of backslashes 
 6941     q{\\\\}  #   VALID: even number of backslashes interpolated as half as many backslash characters
 6942 
 6943 =for html <u>
 6944 
 6945 I<BEST PRACTICES>
 6946 
 6947 =over
 6948 
 6949 =item * I<Use q-quoted text literals to represent empty text literals only.>
 6950 
 6951 =back
 6952 
 6953 =for html </u>
 6954 
 6955     ''      # NOT BEST PRACTICE: single-quotes invalid, empty string
 6956     ""      # NOT BEST PRACTICE: double-quotes invalid, empty string
 6957     q{}     #     BEST PRACTICE
 6958 
 6959     '0gnb'   #     BEST PRACTICE
 6960     "0gnb"   # NOT BEST PRACTICE: double-quotes not needed
 6961     q{0gnb}  # NOT BEST PRACTICE:      q-quotes not needed
 6962 
 6963     '\\nx'   #     BEST PRACTICE
 6964     "\\nx"   # NOT BEST PRACTICE: double-quotes    invalid, extra backslash
 6965     q{\\nx}  # NOT BEST PRACTICE:      q-quotes not needed
 6966 
 6967 =head3 Section 2.2.6: Editing Operators
 6968 
 6969 =begin text
 6970 
 6971 my $z = q{<<< BEGIN TEXT EVAL >>>};
 6972 
 6973 use Text::ASCIITable;
 6974 
 6975 my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1});
 6976 
 6977 $table->setCols(splice @{[split /\s*\n\s*/, q{
 6978 
 6979 =end text
 6980 
 6981 =begin man
 6982 
 6983 .TS
 6984 allbox tab(@) ;
 6985 c c c c c c c
 6986 l l l l r l l .
 6987 
 6988 =end man
 6989 
 6990 =for html <table class="rperl operators">
 6991 
 6992 =begin docbook
 6993 
 6994 <table id="learning_rperl-section_2.2.6-table_1" label="" frame="all" colsep="1" rowsep="1">
 6995 <title>Editing Operators</title>
 6996 <tgroup cols="6">
 6997 
 6998 =end docbook
 6999 
 7000 =for man T{
 7001 
 7002 =for html <tr><th>
 7003 
 7004 =for docbook <thead>
 7005 
 7006 =for docbook <row><entry align="center">
 7007 
 7008 B<Name>
 7009 
 7010 =for man T}@T{
 7011 
 7012 =for html </th><th>
 7013 
 7014 =for docbook </entry><entry align="center">
 7015 
 7016 B<Symbol>
 7017 
 7018 =for man T}@T{
 7019 
 7020 =for html </th><th>
 7021 
 7022 =for docbook </entry><entry align="center">
 7023 
 7024 B<Arity>
 7025 
 7026 =for man T}@T{
 7027 
 7028 =for html </th><th>
 7029 
 7030 =for docbook </entry><entry align="center">
 7031 
 7032 B<Fixity>
 7033 
 7034 =for man T}@T{
 7035 
 7036 =for html </th><th>
 7037 
 7038 =for docbook </entry><entry align="center">
 7039 
 7040 B<Precedence>
 7041 
 7042 =for man T}@T{
 7043 
 7044 =for html </th><th>
 7045 
 7046 =for docbook </entry><entry align="center">
 7047 
 7048 B<Associativity>
 7049 
 7050 =for man T}@T{
 7051 
 7052 =for html </th><th>
 7053 
 7054 =for docbook </entry><entry align="center">
 7055 
 7056 B<Supported>
 7057 
 7058 =for text }]}, 1);
 7059 
 7060 =for man T}
 7061 
 7062 =for html </td></tr>
 7063 
 7064 =for docbook </entry></row>
 7065 
 7066 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 7067 
 7068 =for man T{
 7069 
 7070 =for html <tr><td>
 7071 
 7072 =for docbook <row><entry align="left">
 7073 
 7074 Substring
 7075 
 7076 =for man T}@T{
 7077 
 7078 =for html </td><td>
 7079 
 7080 =for docbook </entry><entry align="left">
 7081 
 7082 substr
 7083 
 7084 =for man T}@T{
 7085 
 7086 =for html </td><td>
 7087 
 7088 =for docbook </entry><entry align="left">
 7089 
 7090 Variadic
 7091 
 7092 =for man T}@T{
 7093 
 7094 =for html </td><td>
 7095 
 7096 =for docbook </entry><entry align="left">
 7097 
 7098 Prefix
 7099 
 7100 =for man T}@T{
 7101 
 7102 =for html </td><td>
 7103 
 7104 =for docbook </entry><entry align="right">
 7105 
 7106 01
 7107 
 7108 =for man T}@T{
 7109 
 7110 =for html </td><td>
 7111 
 7112 =for docbook </entry><entry align="left">
 7113 
 7114 Left
 7115 
 7116 =for man T}@T{
 7117 
 7118 =for html </td><td>
 7119 
 7120 =for docbook </entry><entry align="left">
 7121 
 7122 Coming Soon
 7123 
 7124 =for text }]}, 1);
 7125 
 7126 =for man T}
 7127 
 7128 =for html </td></tr>
 7129 
 7130 =for docbook </entry></row>
 7131 
 7132 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 7133 
 7134 =for man T{
 7135 
 7136 =for html <tr><td>
 7137 
 7138 =for docbook <row><entry align="left">
 7139 
 7140 Repeat
 7141 
 7142 =for man T}@T{
 7143 
 7144 =for html </td><td>
 7145 
 7146 =for docbook </entry><entry align="left">
 7147 
 7148 x
 7149 
 7150 =for man T}@T{
 7151 
 7152 =for html </td><td>
 7153 
 7154 =for docbook </entry><entry align="left">
 7155 
 7156 Binary
 7157 
 7158 =for man T}@T{
 7159 
 7160 =for html </td><td>
 7161 
 7162 =for docbook </entry><entry align="left">
 7163 
 7164 Infix
 7165 
 7166 =for man T}@T{
 7167 
 7168 =for html </td><td>
 7169 
 7170 =for docbook </entry><entry align="right">
 7171 
 7172 07
 7173 
 7174 =for man T}@T{
 7175 
 7176 =for html </td><td>
 7177 
 7178 =for docbook </entry><entry align="left">
 7179 
 7180 Left
 7181 
 7182 =for man T}@T{
 7183 
 7184 =for html </td><td>
 7185 
 7186 =for docbook </entry><entry align="left">
 7187 
 7188 Coming Soon
 7189 
 7190 =for text }]}, 1);
 7191 
 7192 =for man T}
 7193 
 7194 =for html </td></tr>
 7195 
 7196 =for docbook </entry></row>
 7197 
 7198 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 7199 
 7200 =for man T{
 7201 
 7202 =for html <tr><td>
 7203 
 7204 =for docbook <row><entry align="left">
 7205 
 7206 Concatenate
 7207 
 7208 =for man T}@T{
 7209 
 7210 =for html </td><td>
 7211 
 7212 =for docbook </entry><entry align="left">
 7213 
 7214 .
 7215 
 7216 =for man T}@T{
 7217 
 7218 =for html </td><td>
 7219 
 7220 =for docbook </entry><entry align="left">
 7221 
 7222 Binary
 7223 
 7224 =for man T}@T{
 7225 
 7226 =for html </td><td>
 7227 
 7228 =for docbook </entry><entry align="left">
 7229 
 7230 Infix
 7231 
 7232 =for man T}@T{
 7233 
 7234 =for html </td><td>
 7235 
 7236 =for docbook </entry><entry align="right">
 7237 
 7238 08
 7239 
 7240 =for man T}@T{
 7241 
 7242 =for html </td><td>
 7243 
 7244 =for docbook </entry><entry align="left">
 7245 
 7246 Left
 7247 
 7248 =for man T}@T{
 7249 
 7250 =for html </td><td>
 7251 
 7252 =for docbook </entry><entry align="left">
 7253 
 7254 Yes
 7255 
 7256 =for text }]}, 1);
 7257 
 7258 =for man T}
 7259 
 7260 =for html </td></tr>
 7261 
 7262 =for docbook </entry></row>
 7263 
 7264 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 7265 
 7266 =for man T{
 7267 
 7268 =for html <tr><td>
 7269 
 7270 =for docbook <row><entry align="left">
 7271 
 7272 Length
 7273 
 7274 =for man T}@T{
 7275 
 7276 =for html </td><td>
 7277 
 7278 =for docbook </entry><entry align="left">
 7279 
 7280 length
 7281 
 7282 =for man T}@T{
 7283 
 7284 =for html </td><td>
 7285 
 7286 =for docbook </entry><entry align="left">
 7287 
 7288 Unary
 7289 
 7290 =for man T}@T{
 7291 
 7292 =for html </td><td>
 7293 
 7294 =for docbook </entry><entry align="left">
 7295 
 7296 Prefix
 7297 
 7298 =for man T}@T{
 7299 
 7300 =for html </td><td>
 7301 
 7302 =for docbook </entry><entry align="right">
 7303 
 7304 10
 7305 
 7306 =for man T}@T{
 7307 
 7308 =for html </td><td>
 7309 
 7310 =for docbook </entry><entry align="left">
 7311 
 7312 Non
 7313 
 7314 =for man T}@T{
 7315 
 7316 =for html </td><td>
 7317 
 7318 =for docbook </entry><entry align="left">
 7319 
 7320 Coming Soon
 7321 
 7322 =for text }]}, 1);
 7323 
 7324 =for man T}
 7325 
 7326 =for html </td></tr>
 7327 
 7328 =for docbook </entry></row>
 7329 
 7330 =begin text
 7331 
 7332 return $table->draw( ['.=','=.','=','='],   # .=============.
 7333 
 7334                      ['|','|','|'],         # | info | info |
 7335  
 7336                      ['|-','-|','=','='],   # |-===========-|
 7337 
 7338                      ['|','|','|'],         # | info | info |
 7339 
 7340                      ["'=","='",'=','='],   # '============='
 7341 
 7342                      ['|-','-|','-','+']    # rowseperator
 7343 
 7344                     );
 7345 
 7346 $z = q{<<< END TEXT EVAL >>>};
 7347 
 7348 =end text
 7349 
 7350 =for man .TE
 7351 
 7352 =for html </table>
 7353 
 7354 =for docbook </tbody></tgroup></table>
 7355 
 7356 =over
 7357 
 7358 =item * B<Substring>
 7359 
 7360     substr EXPR, OFFSET
 7361     substr EXPR, OFFSET, LENGTH
 7362     substr EXPR, OFFSET, LENGTH, REPLACEMENT
 7363 
 7364 EXPR and REPLACEMENT are string values, OFFSET and LENGTH are integer values;
 7365 
 7366 When called with 2 operands, return substring of first operand EXPR, beginning at second operand OFFSET character and ending at end of first operand;
 7367 
 7368 When called with 3 operands, return substring of first operand EXPR, beginning at second operand OFFSET character and ending after third operand LENGTH characters;
 7369 
 7370 When called with 4 operands, return substring of first operand EXPR, beginning at second operand OFFSET character and ending after third operand LENGTH characters, and also edit first operand by replacing original substring with fourth operand REPLACEMENT string;
 7371 
 7372 In all variants, OFFSET begins at 0;
 7373 
 7374 In all variants, if second operand OFFSET is negative then substring begins absolute value of LENGTH characters before end of first operand EXPR;
 7375 
 7376 In 3-operand and 4-operand variants, if third operand LENGTH is negative then substring ends absolute value of LENGTH characters before end of first operand EXPR;
 7377 
 7378 In 4-operand variant, return value is original substring before replacement occurs, thus you can retrieve a substring and replace it with one operation;
 7379 
 7380 In 4-operand variant, length of substring in third operand LENGTH need not equal length of string in fourth operand REPLACEMENT, length of first operand EXPR will be automatically increased or decreased as needed
 7381 
 7382     # common usage
 7383     my string $foo = 'abc123!?*';               # $foo = 'abc123!?*'
 7384     my string $bar = substr $foo, 2;            #                     $bar =   'c123!?*'
 7385     my string $bat = substr $foo, 2, 3;         #                     $bat =   'c12'
 7386     my string $bax = substr $foo, 2, 3, 'd45';  # $foo = 'abd453!?*', $bax =   'c12'
 7387 
 7388 X<break_code_blocks>
 7389 
 7390 
 7391     # negative OFFSET
 7392     my string $foo = 'abc123!?*';                # $foo = 'abc123!?*'
 7393     my string $bar = substr $foo, -4;            #                     $bar =   '3!?*'
 7394     my string $bat = substr $foo, -4, 3;         #                     $bat =   '3!?'
 7395     my string $bax = substr $foo, -4, 3, 'd45';  # $foo = 'abc12d45*', $bax =   '3!?'
 7396 
 7397 X<break_code_blocks>
 7398 
 7399 
 7400     # negative LENGTH
 7401     my string $foo = 'abc123!?*';                 # $foo = 'abc123!?*'
 7402     my string $bar = substr $foo, 2;              #                     $bar =   'c123!?*'
 7403     my string $bat = substr $foo, 2, -3;          #                     $bat =   'c123'
 7404     my string $bax = substr $foo, 2, -3, 'd456';  # $foo = 'abd456!?*', $bax =   'c123'
 7405 
 7406 X<break_code_blocks>
 7407 
 7408 
 7409     # negative OFFSET and LENGTH
 7410     my string $foo = 'abc123!?*';                  # $foo = 'abc123!?*'
 7411     my string $bar = substr $foo, -6;              #                     $bar =   '123!?*'
 7412     my string $bat = substr $foo, -6, -2;          #                     $bat =   '123!'
 7413     my string $bax = substr $foo, -6, -2, 'd456';  # $foo = 'abcd456?*', $bax =   '123!'
 7414 
 7415 X<break_code_blocks>
 7416 
 7417 
 7418     # LENGTH less-than REPLACEMENT length
 7419     my string $foo = 'abc123!?*';                   # $foo = 'abc123!?*'
 7420     my string $bar = substr $foo, 2;                #                         $bar =   'c123!?*'
 7421     my string $bat = substr $foo, 2, 3;             #                         $bat =   'c12'
 7422     my string $bax = substr $foo, 2, 3, 'd456789';  # $foo = 'abd4567893!?*', $bax =   'c12'
 7423 
 7424 X<break_code_blocks>
 7425 
 7426 
 7427     # LENGTH greater-than REPLACEMENT length, and empty replacement string
 7428     my string $foo = 'abc123!?*';             # $foo = 'abc123!?*'
 7429     my string $bar = substr $foo, 2;          #                     $bar =   'c123!?*'
 7430     my string $bat = substr $foo, 2, 3;       #                     $bat =   'c12'
 7431     my string $bax = substr $foo, 2, 3, q{};  # $foo = 'ab3!?*',    $bax =   'c12'
 7432 
 7433 =back
 7434 
 7435 =over
 7436 
 7437 =item * B<Repeat>
 7438 
 7439     EXPR x COUNT
 7440 
 7441 EXPR is string value, COUNT is unsigned_integer (non-negative whole number) value;
 7442 
 7443 Return a new string value comprised of string EXPR repeated COUNT times;
 7444 
 7445 Analogous to arithmetic multiply operator C<*>;
 7446 
 7447 Consecutive repeat C<x> operators may be chained for multiplicative effect
 7448 
 7449     'a' x 0      # '' (empty string)
 7450     'a' x 1      # 'a'
 7451     'a' x 2      # 'aa'
 7452     'a' x 3      # 'aaa'
 7453     'a' x 3 x 2  # 'aaaaaa'
 7454 
 7455     'howdy' x 3  # 'howdyhowdyhowdy'
 7456 
 7457 =back
 7458 
 7459 =over
 7460 
 7461 =item * B<Concatenate>
 7462 
 7463     EXPR1 . EXPR2
 7464 
 7465 EXPR1 and EXPR2 are string values;
 7466 
 7467 Return a new string value comprised of string EXPR1 followed by EXPR2;
 7468 
 7469 Analogous to arithmetic add operator C<+>;
 7470 
 7471 Consecutive concatenate C<.> operators may be chained for additive (cumulative) effect
 7472 
 7473     '' . ''          # '' (empty string)
 7474     'a' . ''         # 'a'
 7475     '' . 'a'         # 'a'
 7476     'a' . 'a'        # 'aa'
 7477     'a' . 'a' . 'a'  # 'aaa'
 7478 
 7479     'howdy' . 'howdy' . 'howdy'  # 'howdyhowdyhowdy'
 7480 
 7481 =back
 7482 
 7483 =over
 7484 
 7485 =item * B<Length>
 7486 
 7487     length EXPR
 7488 
 7489 EXPR is string value;
 7490 
 7491 Return number of characters in string EXPR
 7492 
 7493     length ''     # 0
 7494     length 'a'    # 1
 7495     length 'aa'   # 2
 7496     length 'aaa'  # 3
 7497 
 7498     length 'howdy'            # 5
 7499     length 'howdyhowdyhowdy'  # 15
 7500 
 7501 =back
 7502 
 7503 =head3 Section 2.2.7: Case Operators
 7504 
 7505 =begin text
 7506 
 7507 my $z = q{<<< BEGIN TEXT EVAL >>>};
 7508 
 7509 use Text::ASCIITable;
 7510 
 7511 my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1});
 7512 
 7513 $table->setCols(splice @{[split /\s*\n\s*/, q{
 7514 
 7515 =end text
 7516 
 7517 =begin man
 7518 
 7519 .TS
 7520 allbox tab(@) ;
 7521 c c c c c c c
 7522 l l l l r l l .
 7523 
 7524 =end man
 7525 
 7526 =for html <table class="rperl operators">
 7527 
 7528 =begin docbook
 7529 
 7530 <table id="learning_rperl-section_2.2.7-table_1" label="" frame="all" colsep="1" rowsep="1">
 7531 <title>Case Operators</title>
 7532 <tgroup cols="6">
 7533 
 7534 =end docbook
 7535 
 7536 =for man T{
 7537 
 7538 =for html <tr><th>
 7539 
 7540 =for docbook <thead>
 7541 
 7542 =for docbook <row><entry align="center">
 7543 
 7544 B<Name>
 7545 
 7546 =for man T}@T{
 7547 
 7548 =for html </th><th>
 7549 
 7550 =for docbook </entry><entry align="center">
 7551 
 7552 B<Symbol>
 7553 
 7554 =for man T}@T{
 7555 
 7556 =for html </th><th>
 7557 
 7558 =for docbook </entry><entry align="center">
 7559 
 7560 B<Arity>
 7561 
 7562 =for man T}@T{
 7563 
 7564 =for html </th><th>
 7565 
 7566 =for docbook </entry><entry align="center">
 7567 
 7568 B<Fixity>
 7569 
 7570 =for man T}@T{
 7571 
 7572 =for html </th><th>
 7573 
 7574 =for docbook </entry><entry align="center">
 7575 
 7576 B<Precedence>
 7577 
 7578 =for man T}@T{
 7579 
 7580 =for html </th><th>
 7581 
 7582 =for docbook </entry><entry align="center">
 7583 
 7584 B<Associativity>
 7585 
 7586 =for man T}@T{
 7587 
 7588 =for html </th><th>
 7589 
 7590 =for docbook </entry><entry align="center">
 7591 
 7592 B<Supported>
 7593 
 7594 =for text }]}, 1);
 7595 
 7596 =for man T}
 7597 
 7598 =for html </td></tr>
 7599 
 7600 =for docbook </entry></row>
 7601 
 7602 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 7603 
 7604 =for man T{
 7605 
 7606 =for html <tr><td>
 7607 
 7608 =for docbook <row><entry align="left">
 7609 
 7610 Lowercase
 7611 
 7612 =for man T}@T{
 7613 
 7614 =for html </td><td>
 7615 
 7616 =for docbook </entry><entry align="left">
 7617 
 7618 lc
 7619 
 7620 =for man T}@T{
 7621 
 7622 =for html </td><td>
 7623 
 7624 =for docbook </entry><entry align="left">
 7625 
 7626 Unary
 7627 
 7628 =for man T}@T{
 7629 
 7630 =for html </td><td>
 7631 
 7632 =for docbook </entry><entry align="left">
 7633 
 7634 Prefix
 7635 
 7636 =for man T}@T{
 7637 
 7638 =for html </td><td>
 7639 
 7640 =for docbook </entry><entry align="right">
 7641 
 7642 10
 7643 
 7644 =for man T}@T{
 7645 
 7646 =for html </td><td>
 7647 
 7648 =for docbook </entry><entry align="left">
 7649 
 7650 Non
 7651 
 7652 =for man T}@T{
 7653 
 7654 =for html </td><td>
 7655 
 7656 =for docbook </entry><entry align="left">
 7657 
 7658 Coming Soon
 7659 
 7660 =for text }]}, 1);
 7661 
 7662 =for man T}
 7663 
 7664 =for html </td></tr>
 7665 
 7666 =for docbook </entry></row>
 7667 
 7668 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 7669 
 7670 =for man T{
 7671 
 7672 =for html <tr><td>
 7673 
 7674 =for docbook <row><entry align="left">
 7675 
 7676 Lowercase First Character
 7677 
 7678 =for man T}@T{
 7679 
 7680 =for html </td><td>
 7681 
 7682 =for docbook </entry><entry align="left">
 7683 
 7684 lcfirst
 7685 
 7686 =for man T}@T{
 7687 
 7688 =for html </td><td>
 7689 
 7690 =for docbook </entry><entry align="left">
 7691 
 7692 Unary
 7693 
 7694 =for man T}@T{
 7695 
 7696 =for html </td><td>
 7697 
 7698 =for docbook </entry><entry align="left">
 7699 
 7700 Prefix
 7701 
 7702 =for man T}@T{
 7703 
 7704 =for html </td><td>
 7705 
 7706 =for docbook </entry><entry align="right">
 7707 
 7708 10
 7709 
 7710 =for man T}@T{
 7711 
 7712 =for html </td><td>
 7713 
 7714 =for docbook </entry><entry align="left">
 7715 
 7716 Non
 7717 
 7718 =for man T}@T{
 7719 
 7720 =for html </td><td>
 7721 
 7722 =for docbook </entry><entry align="left">
 7723 
 7724 Coming Soon
 7725 
 7726 =for text }]}, 1);
 7727 
 7728 =for man T}
 7729 
 7730 =for html </td></tr>
 7731 
 7732 =for docbook </entry></row>
 7733 
 7734 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 7735 
 7736 =for man T{
 7737 
 7738 =for html <tr><td>
 7739 
 7740 =for docbook <row><entry align="left">
 7741 
 7742 Uppercase
 7743 
 7744 =for man T}@T{
 7745 
 7746 =for html </td><td>
 7747 
 7748 =for docbook </entry><entry align="left">
 7749 
 7750 uc
 7751 
 7752 =for man T}@T{
 7753 
 7754 =for html </td><td>
 7755 
 7756 =for docbook </entry><entry align="left">
 7757 
 7758 Unary
 7759 
 7760 =for man T}@T{
 7761 
 7762 =for html </td><td>
 7763 
 7764 =for docbook </entry><entry align="left">
 7765 
 7766 Prefix
 7767 
 7768 =for man T}@T{
 7769 
 7770 =for html </td><td>
 7771 
 7772 =for docbook </entry><entry align="right">
 7773 
 7774 10
 7775 
 7776 =for man T}@T{
 7777 
 7778 =for html </td><td>
 7779 
 7780 =for docbook </entry><entry align="left">
 7781 
 7782 Non
 7783 
 7784 =for man T}@T{
 7785 
 7786 =for html </td><td>
 7787 
 7788 =for docbook </entry><entry align="left">
 7789 
 7790 Coming Soon
 7791 
 7792 =for text }]}, 1);
 7793 
 7794 =for man T}
 7795 
 7796 =for html </td></tr>
 7797 
 7798 =for docbook </entry></row>
 7799 
 7800 =for text $table->addRow(splice @{[split /\s*\n\s*/, q{
 7801 
 7802 =for man T{
 7803 
 7804 =for html <tr><td>
 7805 
 7806 =for docbook <row><entry align="left">
 7807 
 7808 Uppercase First Character
 7809 
 7810 =for man T}@T{
 7811 
 7812 =for html </td><td>
 7813 
 7814 =for docbook </entry><entry align="left">
 7815 
 7816 ucfirst
 7817 
 7818 =for man T}@T{
 7819 
 7820 =for html </td><td>
 7821 
 7822 =for docbook </entry><entry align="left">
 7823 
 7824 Unary
 7825 
 7826 =for man T}@T{
 7827 
 7828 =for html </td><td>
 7829 
 7830 =for docbook </entry><entry align="left">
 7831 
 7832 Prefix
 7833 
 7834 =for man T}@T{
 7835 
 7836 =for html </td><td>
 7837 
 7838 =for docbook </entry><entry align="right">
 7839 
 7840 10
 7841 
 7842 =for man T}@T{
 7843 
 7844 =for html </td><td>
 7845 
 7846 =for docbook </entry><entry align="left">
 7847 
 7848 Non
 7849 
 7850 =for man T}@T{
 7851 
 7852 =for html </td><td>
 7853 
 7854 =for docbook </entry><entry align="left">
 7855 
 7856 Coming Soon
 7857 
 7858 =for text }]}, 1);
 7859 
 7860 =for man T}
 7861 
 7862 =for html </td></tr>
 7863 
 7864 =for docbook </entry></row>
 7865 
 7866 =begin text
 7867 
 7868 return $table->draw( ['.=','=.','=','='],   # .=============.
 7869 
 7870                      ['|','|','|'],         # | info | info |
 7871  
 7872                      ['|-','-|','=','='],   # |-===========-|
 7873 
 7874                      ['|','|','|'],         # | info | info |
 7875 
 7876                      ["'=","='",'=','='],   # '============='
 7877 
 7878                      ['|-','-|','-','+']    # rowseperator
 7879 
 7880                     );
 7881 
 7882 $z = q{<<< END TEXT EVAL >>>};
 7883 
 7884 =end text
 7885 
 7886 =for man .TE
 7887 
 7888 =for html </table>
 7889 
 7890 =for docbook </tbody></tgroup></table>
 7891 
 7892 =over
 7893 
 7894 =item * B<Lowercase>
 7895 
 7896     lc EXPR
 7897 
 7898 EXPR is string value;
 7899 
 7900 Return new string comprised of all characters in string EXPR converted to lowercase format
 7901 
 7902     lc ''     #  '' (empty string)
 7903     lc 'a'    #  'a'
 7904     lc 'A'    #  'a'
 7905     lc 'aA'   #  'aa'
 7906     lc 'AA'   #  'aa'
 7907     lc 'AAA'  #  'aaa'
 7908 
 7909     lc 'howdyHowdyHOWDY'  # 'howdyhowdyhowdy'
 7910 
 7911 =back
 7912 
 7913 =over
 7914 
 7915 =item * B<Lowercase First Character>
 7916 
 7917     lcfirst EXPR
 7918 
 7919 EXPR is string value;
 7920 
 7921 Return new string comprised of first character in string EXPR converted to lowercase format and remaining characters in EXPR unmodified
 7922 
 7923     lcfirst ''     #  '' (empty string)
 7924     lcfirst 'a'    #  'a'
 7925     lcfirst 'A'    #  'a'
 7926     lcfirst 'aA'   #  'aa'
 7927     lcfirst 'AA'   #  'aA'
 7928     lcfirst 'AAA'  #  'aAA'
 7929 
 7930     lcfirst 'HOWDYHOWDYHOWDY'  # 'hOWDYHOWDYHOWDY'
 7931 
 7932 =back
 7933 
 7934 =over
 7935 
 7936 =item * B<Uppercase>
 7937 
 7938     uc EXPR
 7939 
 7940 EXPR is string value;
 7941 
 7942 Return new string comprised of all characters in string EXPR converted to uppercase format
 7943 
 7944     uc ''     #  '' (empty string)
 7945     uc 'A'    #  'A'
 7946     uc 'a'    #  'A'
 7947     uc 'Aa'   #  'AA'
 7948     uc 'aa'   #  'AA'
 7949     uc 'aaa'  #  'AAA'
 7950 
 7951     uc 'HOWDYhOWDYhowdy'  # 'HOWDYHOWDYHOWDY'
 7952 
 7953 =back
 7954 
 7955 =over<