Add a note to the future that they should read the latest perlootut

[perl5.git] / pod / perlguts.pod

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 8f3ed0c..0738938 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -351,11 +351,11 @@ to these new elements.
 
 Here are some other functions:
 
-    I32   av_len(AV*);
+    I32   av_top_index(AV*);
     SV**  av_fetch(AV*, I32 key, I32 lval);
     SV**  av_store(AV*, I32 key, SV* val);
 
-The C<av_len> function returns the highest index value in an array (just
+The C<av_top_index> function returns the highest index value in an array (just
 like $#array in Perl).  If the array is empty, -1 is returned.  The
 C<av_fetch> function returns the value at index C<key>, but if C<lval>
 is non-zero, then C<av_fetch> will store an undef value at that index.
@@ -462,15 +462,13 @@ by using the following:
 
 This returns NULL if the variable does not exist.
 
-The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
+The hash algorithm is defined in the C<PERL_HASH> macro:
 
-    hash = 0;
-    while (klen--)
-       hash = (hash * 33) + *key++;
-    hash = hash + (hash >> 5);                 /* after 5.6 */
+    PERL_HASH(hash, key, klen)
 
-The last step was added in version 5.6 to improve distribution of
-lower bits in the resulting hash value.
+The exact implementation of this macro varies by architecture and version
+of perl, and the return value may change per invocation, so the value
+is only valid for the duration of a single perl process.
 
 See L<Understanding the Magic of Tied Hashes and Arrays> for more
 information on how to use the hash access functions on tied hashes.
@@ -606,17 +604,13 @@ macro and then check the return value.
 
 The most useful types that will be returned are:
 
-    SVt_IV    Scalar
-    SVt_NV    Scalar
-    SVt_PV    Scalar
-    SVt_RV    Scalar
-    SVt_PVAV  Array
-    SVt_PVHV  Hash
-    SVt_PVCV  Code
-    SVt_PVGV  Glob (possibly a file handle)
-    SVt_PVMG  Blessed or Magical Scalar
+    < SVt_PVAV  Scalar
+    SVt_PVAV    Array
+    SVt_PVHV    Hash
+    SVt_PVCV    Code
+    SVt_PVGV    Glob (possibly a file handle)
 
-See the F<sv.h> header file for more details.
+See L<perlapi/svtype> for more details.
 
 =head2 Blessed References and Class Objects
 
@@ -1063,6 +1057,7 @@ will be lost.
  #  PERL_MAGIC_arylen         vtbl_arylen    Array length ($#ary)
  %  PERL_MAGIC_rhash          (none)         extra data for restricted
                                              hashes
+ &  PERL_MAGIC_proto          (none)         my sub prototype CV
  .  PERL_MAGIC_pos            vtbl_pos       pos() lvalue
  :  PERL_MAGIC_symtab         (none)         extra data for symbol
                                              tables
@@ -1078,7 +1073,7 @@ will be lost.
                                              element
  E  PERL_MAGIC_env            vtbl_env       %ENV hash
  e  PERL_MAGIC_envelem        vtbl_envelem   %ENV hash element
- f  PERL_MAGIC_fm             vtbl_regdata   Formline 
+ f  PERL_MAGIC_fm             vtbl_regexp    Formline 
                                              ('compiled' format)
  g  PERL_MAGIC_regex_global   vtbl_mglob     m//g target
  H  PERL_MAGIC_hints          vtbl_hints     %^H hash
@@ -1103,7 +1098,7 @@ will be lost.
                                              extensions
  u  PERL_MAGIC_uvar_elem      (none)         Reserved for use by
                                              extensions
- V  PERL_MAGIC_vstring        vtbl_vstring   SV was vstring literal
+ V  PERL_MAGIC_vstring        (none)         SV was vstring literal
  v  PERL_MAGIC_vec            vtbl_vec       vec() lvalue
  w  PERL_MAGIC_utf8           vtbl_utf8      Cached UTF-8 information
  x  PERL_MAGIC_substr         vtbl_substr    substr() lvalue
@@ -1541,7 +1536,7 @@ But it also puts the same information in certain fields of the XSUB itself:
     const char *subname = SvPVX(cv);
     STRLEN name_length  = SvCUR(cv); /* in bytes */
     U32 is_utf8         = SvUTF8(cv);
-    
+
 C<SvPVX(cv)> contains just the sub name itself, not including the package.
 For an AUTOLOAD routine in UNIVERSAL or one of its superclasses,
 C<CvSTASH(cv)> returns NULL during a method call on a nonexistent package.
@@ -1559,7 +1554,7 @@ within a C program.  These four are:
     I32  call_sv(SV*, I32);
     I32  call_pv(const char*, I32);
     I32  call_method(const char*, I32);
-    I32  call_argv(const char*, I32, register char**);
+    I32  call_argv(const char*, I32, char**);
 
 The routine most often used is C<call_sv>.  The C<SV*> argument
 contains either the name of the Perl subroutine to be called, or a
@@ -1929,7 +1924,7 @@ per-subroutine or recursive stage, like this:
     static void my_peep(pTHX_ OP *o)
     {
         /* custom per-subroutine optimisation goes here */
-        prev_peepp(o);
+        prev_peepp(aTHX_ o);
         /* custom per-subroutine optimisation may also go here */
     }
     BOOT:
@@ -1943,7 +1938,7 @@ per-subroutine or recursive stage, like this:
         for(; o; o = o->op_next) {
             /* custom per-op optimisation goes here */
         }
-        prev_rpeepp(orig_o);
+        prev_rpeepp(aTHX_ orig_o);
     }
     BOOT:
         prev_rpeepp = PL_rpeepp;
@@ -2817,7 +2812,7 @@ a new string which is UTF-8 encoded, and then combine them.
 
 =head1 Custom Operators
 
-Custom operator support is a new experimental feature that allows you to
+Custom operator support is an experimental feature that allows you to
 define your own ops. This is primarily to allow the building of
 interpreters for other languages in the Perl core, but it also allows
 optimizations through the creation of "macro-ops" (ops which perform the
@@ -2839,7 +2834,7 @@ tree using a C<CHECK> block and the C<B::Generate> module, or by adding
 a custom peephole optimizer with the C<optimize> module.
 
 When you do this, you replace ordinary Perl ops with custom ops by
-creating ops with the type C<OP_CUSTOM> and the C<pp_addr> of your own
+creating ops with the type C<OP_CUSTOM> and the C<op_ppaddr> of your own
 PP function. This should be defined in XS code, and should look like
 the PP ops in C<pp_*.c>. You are responsible for ensuring that your op
 takes the appropriate number of values from the stack, and you are