Some more P5 to P6 hints

- got to pos

Author: lizmat

doc/Language/5to6-perlfunc.pod6

@@ -248,9 +248,9 @@ in C<$x> containing "howdy".
 Note that C<chomp()> (without arguments) is not supported in Perl 6.
 
 The Perl 6 ecosystem has a module C<P5chomp> which exports a C<chomp>
-function that mimics the original Perl 5 behaviour as much as possible,
+function that mimics the original Perl 5 behaviour as much as possible.
 
-=head2 chop
+.head2 chop
 
 =item chop VARIABLE
 
@@ -261,9 +261,9 @@ being "howdy" and C<$y> being "howd". Also works as a method: C<$y = $x.chop>.
 Note that C<chop()> (without arguments) is not supported in Perl 6.
 
 The Perl 6 ecosystem has a module C<P5chomp> which exports a C<chop>
-function that mimics the original Perl 5 behaviour as much as possible,
+function that mimics the original Perl 5 behaviour as much as possible.
 
-=head2 chown
+.head2 chown
 
 =item chown LIST
 
@@ -283,7 +283,7 @@ function and a method:
 Note that C<chr()> (without arguments) is not supported in Perl 6.
 
 The Perl 6 ecosystem has a module C<P5chr> which exports a C<chr>
-function that mimics the original Perl 5 behaviour as much as possible,
+function that mimics the original Perl 5 behaviour as much as possible.
 
 =head2 chroot
 
@@ -363,7 +363,7 @@ considered undefined.
 Note that C<defined()> (without arguments) is not supported in Perl 6.
 
 The Perl 6 ecosystem has a module C<P5defined> which exports a C<defined>
-function that mimics the original Perl 5 behaviour as much as possible,
+function that mimics the original Perl 5 behaviour as much as possible.
 
 =head2 delete
 
@@ -419,7 +419,7 @@ L<https://design.perl6.org/S06.html#%22Pointy_blocks%22>. There is also
 some information at L<https://en.wikibooks.org/wiki/Perl_6_Programming/Blocks_and_Closures#Pointy_Blocks>
 
 The Perl 6 ecosystem has a module C<P5each> which exports an C<each>
-function that mimics the original Perl 5 behaviour as much as possible,
+function that mimics the original Perl 5 behaviour as much as possible.
 
 =head2 eof
 
@@ -434,7 +434,8 @@ C<$filehandle.eof>. Returns C<True> if at end of file.
 
 =item eval EXPR
 
-Replaced by L<EVAL|/routine/EVAL>. Note that C<EVAL> does not do any L<exception handling|/language/exceptions>!
+Replaced by L<EVAL|/routine/EVAL>. Note that C<EVAL> does not do any
+L<exception handling|/language/exceptions>!
 
 =head2 evalbytes
 
@@ -492,7 +493,11 @@ Same as in Perl 5, but can also be used as a method: C<5.exp>;
 
 =item fc EXPR
 
-Looks like it does the same thing as in Perl 5.
+Looks like it does the same thing as in Perl 5 except that calling it without
+arguments is not supported in Perl 6.
+
+The Perl 6 ecosystem has a module C<P5fc> which exports a C<fc>
+function that mimics the original Perl 5 behaviour as much as possible.
 
 =head2 fcntl
 
@@ -510,8 +515,11 @@ Replaced by C<$?FILE>.
 
 =item fileno FILEHANDLE
 
-S32 indicates that this should be available as a method, but appears currently
-unimplemented.
+The C<native-descriptor> method on C<IO::Handle> returns the equivalent of
+C<fileno>.
+
+The Perl 6 ecosystem has a module C<P5fileno> which exports a C<fileno>
+function that mimics the original Perl 5 behaviour as much as possible.
 
 =head2 flock
 
@@ -673,7 +681,10 @@ C<DateTime> object for the current time, for instance, use C<my $gmtime
 
 =item goto &NAME
 
-goto is not yet implemented
+The syntax for C<goto LABEL> is already accepted, but the runtime part of
+C<goto> is not yet implemented.  So this will result in a runtime error:
+
+    FOO: goto FOO; # Label.goto() not yet implemented. Sorry.
 
 =head2 grep
 
@@ -689,6 +700,8 @@ also be used as a method: C<@foo = @bar.grep(/^f/)>
 
 =item hex EXPR
 
+In Perl 6 an expression B<must> be specified.
+
 Replaced by the adverbial form C<:16>. E. g. C<:16("aF")> returns 175.
 
 Alternately, the same result can be achieved by using the C<.base> method:
@@ -698,6 +711,9 @@ It just so happens that C<.Str> defaults to base 10, so if you just C<say
 0xaF>, that will also print 175, but that may not be immediately obvious, so
 may not be the best way to go for this.
 
+The Perl 6 ecosystem has a module C<P5hex> which exports a C<hex>
+function that mimics the original Perl 5 behaviour as much as possible.
+
 =head2 import
 
 =item import LIST
@@ -713,7 +729,19 @@ L<this section|/language/5to6-nutshell#Importing_specific_functions_from_a_modul
 =item index STR, SUBSTR, POSITION
 
 Works as in Perl 5. Can also now be used as a method:
-C<"howdy!".index("how"); # 0>
+C<"howdy!".index("how"); # 0>.  Main difference with Perl 5 is that C<Nil> is
+returned instead of C<-1>.  This is very useful in combination with the
+C<with> command:
+
+    with index("foo","o") -> $index {
+        say "Found it at $index";
+    }
+    else {
+        say "Not found"
+    }
+
+The Perl 6 ecosystem has a module C<P5index> which exports an C<index>
+function that mimics the original Perl 5 behaviour as much as possible.
 
 =head2 int
 
@@ -725,6 +753,14 @@ translation of Perl 5 code, but in Perl 6, you can just as easily call
 the C<.Int> method on the number. C<3.9.Int; # 3> and C<3.9.truncate>
 are equivalent.
 
+Please note that C<int> B<does> have a meaning in Perl 6.  It is type that
+can be used to indicate a native integer:
+
+    my int $a = 42;   # a native integer, similar to Perl 5's integer values
+
+Because of this, it has proven impossible to create a Perl 6 module that
+would export a sub that would mimic the Perl 5 behaviour.
+
 =head2 ioctl
 
 =item ioctl FILEHANDLE, FUNCTION, SCALAR
@@ -773,21 +809,31 @@ Same as in Perl 5.
 
 =item lc EXPR
 
-Works as in Perl 5, and also as a method: C<"UGH".lc>
+Works as in Perl 5, and also as a method: C<"UGH".lc>.  In Perl 6 an
+expression B<must> be specified.
+
+The Perl 6 ecosystem has a module C<P5lc> which exports an C<lc>
+function that mimics the original Perl 5 behaviour as much as possible.
 
 =head2 lcfirst
 
 =item lcfirst EXPR
 
 Does not exist in Perl 6.
 
+The Perl 6 ecosystem has a module C<P5lcfirst> which exports an C<lcfirst>
+function that mimics the original Perl 5 behaviour as much as possible.
+
 =head2 length
 
 =item length EXPR
 
 Replaced by C<chars>, typically used as a method (C<$string.chars>), but
 also works as a function.
 
+The Perl 6 ecosystem has a module C<P5length> which exports an C<length>
+function that mimics the original Perl 5 behaviour as much as possible.
+
 =head2 __LINE__
 
 =item __LINE__
@@ -847,14 +893,16 @@ lines of "2015-06-29T12:49:31-04:00".
 
 =item lock THING
 
-In Perl 6, a method in the C<Lock> class.
+There currently is no equivalent for this In Perl 6.  There is a C<Lock>
+class for creating a Lock object, that can be locked/unlocked as needed.
+But such a lock does not refer to any external objects.
 
 =head2 log
 
 =item log EXPR
 
-Available in Perl 6. Also works as a method. I. e. C<log(2)> is
-equivalent to C<2.log>.
+Available in Perl 6, but B<must> have an expression to work on. Also available
+as a method. I. e. C<log(2)> is equivalent to C<2.log>.
 
 =head2 lstat
 
@@ -896,7 +944,10 @@ used as a method: C<@new = @old.map: { $_ * 2 }>
 
 =item mkdir FILENAME
 
-Works as in Perl 5.
+Works as in Perl 5.  When giving a multi-level directory specification,
+it will automatically create non-existing intermediate directories with
+the same MASK (similar to what "make_path" does of the File::Path module
+in Perl 5).
 
 =item mkdir
 
@@ -958,6 +1009,9 @@ Replaced by the adverbial form C<:8>. E. g. C<:8("100")> returns 64.
 If you want to deal with strings that start in C<0x>, C<0o>, or C<0b>,
 you can just use the C«prefix:<+>» operator.
 
+The Perl 6 ecosystem has a module C<P5hex> which exports an C<oct>
+function that mimics the original Perl 5 behaviour as much as possible.
+
 =head2 open
 
 =item open FILEHANDLE, EXPR
@@ -990,6 +1044,11 @@ No replacement. See L«C<&dir>/C<IO::Path.dir>|/routine/dir» for alternatives.
 
 Same as in Perl 5. May be used as a method: C<"howdy!".ord; # 104>
 
+Note that C<ord()> (without arguments) is not supported in Perl 6.
+
+The Perl 6 ecosystem has a module C<P5chr> which exports a C<ord>
+function that mimics the original Perl 5 behaviour as much as possible.
+
 =head2 our
 
 =item our VARLIST
@@ -1006,9 +1065,15 @@ The same in Perl 6.
 
 =item pack TEMPLATE, LIST
 
-Available in Perl 6. The template options are currently more restricted
-than they are in Perl 5. The current documented list can be found at
-L<unpack|/routine/unpack>.
+Available in Perl 6 when C<use experimental :pack> has been specified in the
+scope where C<pack> needs to be called. The template options are currently
+more restricted than they are in Perl 5. The current documented list can be
+found at L<unpack|/routine/unpack>.
+
+The Perl 6 ecosystem has a module C<P5pack> which exports a C<pack>
+function that mimics the original Perl 5 behaviour as much as possible
+and which has a bigger set of supported features than the experimental
+Perl 6 version.
 
 =head2 package
 
@@ -1051,6 +1116,23 @@ and from processes.
 Works in Perl 6, and can also be used as a method. I. e. C<my $x = pop
 @a;> and C<my $x = @a.pop;> are equivalent.
 
+The non-paramater version of C<pop> does not exist.  Also, if the array
+is empty, a Failure will be returned in Perl 6, which will throw if the
+value is actually used in a significant way.
+
+If you are using only defined values in your array, you can use the C<with>
+function to handle this case:
+
+    with pop @array -> $popped {
+        say "popped '$popped' of the array";
+    }
+    else {
+        say "there was nothing to pop";
+    }
+
+The Perl 6 ecosystem has a module C<P5push> which exports a C<pop>
+function that mimics the original Perl 5 behaviour as much as possible
+
 =head2 pos
 
 =item pos SCALAR