[io grant] Document IO::Path.child-secure

Rakudo impl: rakudo/rakudo@1887114dd8
Tests: Raku/roast@f3c5dae288

Author: zoffixznet

doc/Type/IO/Path.pod6

@@ -132,6 +132,38 @@ C<IO::Path>.
     "foo/bar".IO.concat-with("../meow") .resolve.relative.say; # OUTPUT: «foo/meow␤»
     "foo/bar".IO.concat-with("../../")  .resolve.relative.say; # OUTPUT: «.␤»
 
+=head2 method child
+
+    method child(IO::Path:D: Str() $childname --> IO::Path:D)
+
+Alias for L«C<.concat-with>|/routine/concat-with». See also
+L«C<.child-secure>|/routine/child-secure»
+
+=head2 method child-secure
+
+  method child-secure(IO::Path:D: Str() $childname --> IO::Path:D)
+
+Same as L«C<.child>|/routine/child», except it will
+B«fully L<resolve|/routine/resolve>» the resultant path and check that it is in
+fact a child of the invocant. On success, returns the resultant path;
+L«fails|/routine/fail» with C<X::IO::Resolve> if the path could not be
+completely resolved or with C<X::IO::NotAChild> if the resultant path is not
+a child of the invocant.
+
+B<Note:> since the path has to be fully resolved, the method can still fail
+with C<X::IO::Resolve> even for paths that would be child paths, if some of
+the directories do not exist yet. The last part of the path does not have to
+exist for the routine to succeed.
+
+=for code :skip-test
+my $parent = 'foo'.IO.mkdir;
+say $parent.child-secure: 'bar';     # OUTPUT: «"foo/bar".IO␤»
+say $parent.child-secure: '../bar';  # Fails with X::IO::NotAChild
+say $parent.child-secure: 'bar/ber'; # Fails with X::IO::Resolve
+
+$parent.child('bar').mkdir; # create 'bar' so the call below succeeds
+say $parent.child-secure: 'bar/ber'; # OUTPUT: «"foo/bar/ber".IO␤»
+
 =head2 method extension
 
 Defined as:
@@ -300,16 +332,6 @@ Removes the last portion of the path and returns the result as a new C<IO::Path>
     my $io = IO::Path.new( "/etc/passwd" );
     say $io.parent;                          # OUTPUT: «"/etc".IO␤»
 
-=head2 method child
-
-    method child(IO::Path:D: $childname --> IO::Path)
-
-Appends C<$childname> to the end of the path, adding path separators where
-needed and returns the result as a new C<IO::Path>.
-
-    my $io = IO::Path.new( "/bin" );
-    say $io.child('netstat');                # OUTPUT: «"/bin/netstat".IO␤»
-
 =head2 method resolve
 
     method resolve(IO::Path:D: :$completely --> IO::Path)