txt: ## dist_zef-lizmat-P5substr.md
  [![Actions Status](https://github.com/lizmat/P5substr/workflows/test/badge.svg)](https://github.com/lizmat/P5substr/actions)
  
  # NAME
  
  Raku port of Perl's substr() built-in
  
  # SYNOPSIS
  
  ```
  use P5substr; # exports substr()
  
  say substr("foobar",3);   # bar
  say substr("foobar",1,4); # ooba
  
  my $a = "foobar";
  substr($a,1,2) = "OO";
  say $a;                   # fOObar
  
  ```
  
  # DESCRIPTION
  
  This module tries to mimic the behaviour of Perl's `substr` built-in as closely as possible in the Raku Programming Language.
  
  # ORIGINAL PERL DOCUMENTATION
  
  ```
  substr EXPR,OFFSET,LENGTH,REPLACEMENT
  substr EXPR,OFFSET,LENGTH
  substr EXPR,OFFSET
          Extracts a substring out of EXPR and returns it. First character
          is at offset zero. If OFFSET is negative, starts that far back
          from the end of the string. If LENGTH is omitted, returns
          everything through the end of the string. If LENGTH is negative,
          leaves that many characters off the end of the string.
  
              my $s = "The black cat climbed the green tree";
              my $color  = substr $s, 4, 5;      # black
              my $middle = substr $s, 4, -11;    # black cat climbed the
              my $end    = substr $s, 14;        # climbed the green tree
              my $tail   = substr $s, -4;        # tree
              my $z      = substr $s, -4, 2;     # tr
  
          You can use the substr() function as an lvalue, in which case EXPR
          must itself be an lvalue. If you assign something shorter than
          LENGTH, the string will shrink, and if you assign something longer
          than LENGTH, the string will grow to accommodate it. To keep the
          string the same length, you may need to pad or chop your value
          using "sprintf".
  
          If OFFSET and LENGTH specify a substring that is partly outside
          the string, only the part within the string is returned. If the
          substring is beyond either end of the string, substr() returns the
          undefined value and produces a warning. When used as an lvalue,
          specifying a substring that is entirely outside the string raises
          an exception. Here's an example showing the behavior for boundary
          cases:
  
              my $name = 'fred';
              substr($name, 4) = 'dy';         # $name is now 'freddy'
              my $null = substr $name, 6, 2;   # returns "" (no warning)
              my $oops = substr $name, 7;      # returns undef, with warning
              substr($name, 7) = 'gap';        # raises an exception
  
          An alternative to using substr() as an lvalue is to specify the
          replacement string as the 4th argument. This allows you to replace
          parts of the EXPR and return what was there before in one
          operation, just as you can with splice().
  
              my $s = "The black cat climbed the green tree";
              my $z = substr $s, 14, 7, "jumped from";    # climbed
              # $s is now "The black cat jumped from the green tree"
  
          Note that the lvalue returned by the three-argument version of
          substr() acts as a 'magic bullet'; each time it is assigned to, it
          remembers which part of the original string is being modified; for
          example:
  
              $x = '1234';
              for (substr($x,1,2)) {
                  $_ = 'a';   print $x,"\n";    # prints 1a4
                  $_ = 'xyz'; print $x,"\n";    # prints 1xyz4
                  $x = '56789';
                  $_ = 'pq';  print $x,"\n";    # prints 5pq9
              }
  
          With negative offsets, it remembers its position from the end of
          the string when the target string is modified:
  
              $x = '1234';
              for (substr($x, -3, 2)) {
                  $_ = 'a';   print $x,"\n";    # prints 1a4, as above
                  $x = 'abcdefg';
                  print $_,"\n";                # prints f
              }
  
          Prior to Perl version 5.10, the result of using an lvalue multiple
          times was unspecified. Prior to 5.16, the result with negative
          offsets was unspecified.
  
  ```
  
  # AUTHOR
  
  Elizabeth Mattijsen [liz@raku.rocks](mailto:liz@raku.rocks)
  
  Source can be located at: <https://github.com/lizmat/P5substr> . Comments and Pull Requests are welcome.
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2018, 2019, 2020, 2021 Elizabeth Mattijsen
  
  Re-imagined from Perl as part of the CPAN Butterfly Plan.
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  