[io grant] Document new IO::Path.extension

- Now has a means to specify the number of parts in the wanted extension
- Now has a means to replace an extension with a new one, optionally
    joining it to the filename with a non-'.' joiner

Rakudo impl. rakudo/rakudo@b1e7a01f87
Tests: Raku/roast@b23e53eb79

Author: zoffixznet

doc/Type/IO/Path.pod6

@@ -57,14 +57,71 @@ the file relative to its directory.
 
     say IO::Path.new("docs/README.pod").basename;      # OUTPUT: «README.pod␤»
 
-
 =head2 method extension
 
-    method extension(IO::Path:D:)
-
-Returns the extension (if any) of the path object.
-
-    say IO::Path.new("docs/README.pod").extension; # OUTPUT: «pod␤»
+Defined as:
+
+    multi extension(IO::Path:D                                         --> Str:D)
+    multi extension(IO::Path:D               Int :$parts               --> Str:D)
+    multi extension(IO::Path:D             Range :$parts               --> Str:D)
+    multi extension(IO::Path:D Str $subst,   Int :$parts, Str :$joiner --> IO::Path:D)
+    multi extension(IO::Path:D Str $subst, Range :$parts, Str :$joiner -->
+    IO::Path:D)
+
+Returns the extension consisting of C<$parts> parts (defaults to C<1>),
+where a "part" is defined
+as a dot followed by possibly-empty string up to the end of the string, or
+previous part. That is C<"foo.tar.gz"> has an extension of two parts: first part
+is C<"gz"> and second part is C<"tar"> and calling
+C<"foo.tar.gz".IO.extension: :2parts> gives C<"tar.gz">. If an extension with
+the specified number of C<$parts> is not found, returns an empty string.
+
+C<$parts> can be a L«C<Range>|/type/Range», specifying the minimum number of
+parts and maximum number of parts the extension should have. The routine will
+attempt to much the most parts it can. If C<$parts> range's endpoints that are
+smaller than C<0> they'll be treated as C<0>; implementations may treat
+endpoints larger than C<2⁶³-1> as C<2⁶³-1>. Ranges with C<NaN> or
+L«C<Str>|/type/Str» endpoints will cause an exception to be thrown.
+
+If C<$subst> is provided, the extension will be instead replaced with C<$subst>
+and a new C<IO::Path> object will be returned. It will be joined to the file's
+name with C<$joiner>, which defaults to an empty string when C<$subst> is
+an empty string and to C<"."> when C<$subst> is not empty. B<Note:> if as
+the result of replacement the L«C<basename>|/routine/basename» of the path
+ends up being empty, it will be assumed to be C<.> (a single dot).
+
+    # Getting an extension:
+    say "foo.tar.gz".IO.extension2;               # OUTPUT: «gz␤»
+    say "foo.tar.gz".IO.extension2: :2parts;      # OUTPUT: «tar.gz␤»
+    say "foo.tar.gz".IO.extension2: :parts(^5);   # OUTPUT: «tar.gz␤»
+    say "foo.tar.gz".IO.extension2: :parts(0..1); # OUTPUT: «gz␤»
+
+    # Replacing an extension
+    say "foo.tar.gz".IO.extension2: ''; # OUTPUT: «"foo.tar".IO␤»
+    say "foo.tar.gz".IO.extension2: 'ZIP'; # OUTPUT: «"foo.tar.ZIP".IO␤»
+    say "foo.tar.gz".IO.extension2: 'ZIP', :0parts; # OUTPUT: «"foo.tar.gz.ZIP".IO␤»
+    say "foo.tar.gz".IO.extension2: 'ZIP', :2parts; # OUTPUT: «"foo.ZIP".IO␤»
+    say "foo.tar.gz".IO.extension2: 'ZIP', :parts(^5); # OUTPUT: «"foo.ZIP".IO␤»
+
+    # Replacing an extension using non-standard joiner:
+    say "foo.tar.gz".IO.extension2: '',    :joiner<_>; # OUTPUT: «"foo.tar_".IO␤»
+    say "foo.tar.gz".IO.extension2: 'ZIP', :joiner<_>; # OUTPUT: «"foo.tar_ZIP".IO␤»
+    say "foo.tar.gz".IO.extension2: 'ZIP', :joiner<_>, :2parts; # OUTPUT: «"foo_ZIP".IO␤»
+    say "foo.tar.gz".IO.extension2: 'ZIP', :joiner<_>, :parts(^5); # OUTPUT: «"foo_ZIP".IO␤»
+
+    # EDGE CASES:
+    # There is no 5-part extension, so returned value is an empty string
+    say "foo.tar.gz".IO.extension2: :5parts; # OUTPUT: «␤»
+    # There is no 5-part extension, so we replaced nothing:
+    say "foo.tar.gz".IO.extension2: 'ZIP', :5parts; # OUTPUT: «"foo.tar.gz".IO␤»
+    # Replacing a 0-part extension, is just appending:
+    say "foo.tar.gz".IO.extension2: 'ZIP', :0parts; # OUTPUT: «"foo.tar.gz.ZIP".IO␤»
+    # A replace 1 part of the extension, using '.' joiner
+    say "...".IO.extension2: 'tar'; # OUTPUT: «"....tar".IO␤»
+    # A replace 1 part of the extension, using empty string joiner
+    say "...".IO.extension2: 'tar', :joiner(''); # OUTPUT: «"...tar".IO␤»
+    # Remove 1-part extension; results in empty basename, so result is ".".IO
+    say ".".IO.extension2: ''; # OUTPUT: «".".IO␤»
 
 =head2 method dirname