home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _51e867502bde194142e429c32813fc84 < prev    next >
Text File  |  2000-03-23  |  9KB  |  204 lines

  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Tie::Array - base class for tied arrays</TITLE>
  5. <LINK REL="stylesheet" HREF="../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Tie::Array - base class for tied arrays</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#caveats">CAVEATS</A></LI>
  26.     <LI><A HREF="#author">AUTHOR</A></LI>
  27. </UL>
  28. <!-- INDEX END -->
  29.  
  30. <HR>
  31. <P>
  32. <H1><A NAME="name">NAME</A></H1>
  33. <P>Tie::Array - base class for tied arrays</P>
  34. <P>
  35. <HR>
  36. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  37. <UL>
  38. <LI>Linux</LI>
  39. <LI>Solaris</LI>
  40. <LI>Windows</LI>
  41. </UL>
  42. <HR>
  43. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  44. <PRE>
  45.     package NewArray;
  46.     use Tie::Array;
  47.     @ISA = ('Tie::Array');</PRE>
  48. <PRE>
  49.     # mandatory methods
  50.     sub TIEARRAY { ... }  
  51.     sub FETCH { ... }     
  52.     sub FETCHSIZE { ... }</PRE>
  53. <PRE>
  54.     sub STORE { ... }        # mandatory if elements writeable
  55.     sub STORESIZE { ... }    # mandatory if elements can be added/deleted
  56.     sub EXISTS { ... }       # mandatory if exists() expected to work
  57.     sub DELETE { ... }       # mandatory if delete() expected to work</PRE>
  58. <PRE>
  59.     # optional methods - for efficiency
  60.     sub CLEAR { ... }  
  61.     sub PUSH { ... } 
  62.     sub POP { ... } 
  63.     sub SHIFT { ... } 
  64.     sub UNSHIFT { ... } 
  65.     sub SPLICE { ... } 
  66.     sub EXTEND { ... } 
  67.     sub DESTROY { ... }</PRE>
  68. <PRE>
  69.     package NewStdArray;
  70.     use Tie::Array;</PRE>
  71. <PRE>
  72.     @ISA = ('Tie::StdArray');</PRE>
  73. <PRE>
  74.     # all methods provided by default</PRE>
  75. <PRE>
  76.     package main;</PRE>
  77. <PRE>
  78.     $object = tie @somearray,Tie::NewArray;
  79.     $object = tie @somearray,Tie::StdArray;
  80.     $object = tie @somearray,Tie::NewStdArray;</PRE>
  81. <P>
  82. <HR>
  83. <H1><A NAME="description">DESCRIPTION</A></H1>
  84. <P>This module provides methods for array-tying classes. See
  85. <A HREF="../../lib/Pod/perltie.html">the perltie manpage</A> for a list of the functions required in order to tie an array
  86. to a package. The basic <STRONG>Tie::Array</STRONG> package provides stub <CODE>DESTROY</CODE>,
  87. and <CODE>EXTEND</CODE> methods that do nothing, stub <CODE>DELETE</CODE> and <CODE>EXISTS</CODE>
  88. methods that <CODE>croak()</CODE> if the <A HREF="../../lib/Pod/perlfunc.html#item_delete"><CODE>delete()</CODE></A> or <A HREF="../../lib/Pod/perlfunc.html#item_exists"><CODE>exists()</CODE></A> builtins are ever called
  89. on the tied array, and implementations of <CODE>PUSH</CODE>, <CODE>POP</CODE>, <CODE>SHIFT</CODE>,
  90. <CODE>UNSHIFT</CODE>, <CODE>SPLICE</CODE> and <CODE>CLEAR</CODE> in terms of basic <CODE>FETCH</CODE>, <CODE>STORE</CODE>,
  91. <CODE>FETCHSIZE</CODE>, <CODE>STORESIZE</CODE>.</P>
  92. <P>The <STRONG>Tie::StdArray</STRONG> package provides efficient methods required for tied arrays 
  93. which are implemented as blessed references to an ``inner'' perl array.
  94. It inherits from <STRONG>Tie::Array</STRONG>, and should cause tied arrays to behave exactly 
  95. like standard arrays, allowing for selective overloading of methods.</P>
  96. <P>For developers wishing to write their own tied arrays, the required methods
  97. are briefly defined below. See the <A HREF="../../lib/Pod/perltie.html">the perltie manpage</A> section for more detailed
  98. descriptive, as well as example code:</P>
  99. <DL>
  100. <DT><STRONG><A NAME="item_TIEARRAY_classname%2C_LIST">TIEARRAY classname, LIST</A></STRONG><BR>
  101. <DD>
  102. The class method is invoked by the command <CODE>tie @array, classname</CODE>. Associates
  103. an array instance with the specified class. <CODE>LIST</CODE> would represent
  104. additional arguments (along the lines of <A HREF="../../lib/AnyDBM_File.html">the AnyDBM_File manpage</A> and compatriots) needed
  105. to complete the association. The method should return an object of a class which
  106. provides the methods below.
  107. <P></P>
  108. <DT><STRONG><A NAME="item_STORE_this%2C_index%2C_value">STORE this, index, value</A></STRONG><BR>
  109. <DD>
  110. Store datum <EM>value</EM> into <EM>index</EM> for the tied array associated with
  111. object <EM>this</EM>. If this makes the array larger then
  112. class's mapping of <A HREF="../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> should be returned for new positions.
  113. <P></P>
  114. <DT><STRONG><A NAME="item_FETCH_this%2C_index">FETCH this, index</A></STRONG><BR>
  115. <DD>
  116. Retrieve the datum in <EM>index</EM> for the tied array associated with
  117. object <EM>this</EM>.
  118. <P></P>
  119. <DT><STRONG><A NAME="item_FETCHSIZE_this">FETCHSIZE this</A></STRONG><BR>
  120. <DD>
  121. Returns the total number of items in the tied array associated with
  122. object <EM>this</EM>. (Equivalent to <A HREF="../../lib/Pod/perlfunc.html#item_scalar"><CODE>scalar(@array)</CODE></A>).
  123. <P></P>
  124. <DT><STRONG><A NAME="item_STORESIZE_this%2C_count">STORESIZE this, count</A></STRONG><BR>
  125. <DD>
  126. Sets the total number of items in the tied array associated with
  127. object <EM>this</EM> to be <EM>count</EM>. If this makes the array larger then
  128. class's mapping of <A HREF="../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> should be returned for new positions.
  129. If the array becomes smaller then entries beyond count should be
  130. deleted.
  131. <P></P>
  132. <DT><STRONG><A NAME="item_EXTEND_this%2C_count">EXTEND this, count</A></STRONG><BR>
  133. <DD>
  134. Informative call that array is likely to grow to have <EM>count</EM> entries.
  135. Can be used to optimize allocation. This method need do nothing.
  136. <P></P>
  137. <DT><STRONG><A NAME="item_EXISTS_this%2C_key">EXISTS this, key</A></STRONG><BR>
  138. <DD>
  139. Verify that the element at index <EM>key</EM> exists in the tied array <EM>this</EM>.
  140. <P>The <STRONG>Tie::Array</STRONG> implementation is a stub that simply croaks.</P>
  141. <P></P>
  142. <DT><STRONG><A NAME="item_DELETE_this%2C_key">DELETE this, key</A></STRONG><BR>
  143. <DD>
  144. Delete the element at index <EM>key</EM> from the tied array <EM>this</EM>.
  145. <P>The <STRONG>Tie::Array</STRONG> implementation is a stub that simply croaks.</P>
  146. <P></P>
  147. <DT><STRONG><A NAME="item_CLEAR_this">CLEAR this</A></STRONG><BR>
  148. <DD>
  149. Clear (remove, delete, ...) all values from the tied array associated with
  150. object <EM>this</EM>.
  151. <P></P>
  152. <DT><STRONG><A NAME="item_DESTROY_this">DESTROY this</A></STRONG><BR>
  153. <DD>
  154. Normal object destructor method.
  155. <P></P>
  156. <DT><STRONG><A NAME="item_PUSH_this%2C_LIST">PUSH this, LIST</A></STRONG><BR>
  157. <DD>
  158. Append elements of LIST to the array.
  159. <P></P>
  160. <DT><STRONG><A NAME="item_POP_this">POP this</A></STRONG><BR>
  161. <DD>
  162. Remove last element of the array and return it.
  163. <P></P>
  164. <DT><STRONG><A NAME="item_SHIFT_this">SHIFT this</A></STRONG><BR>
  165. <DD>
  166. Remove the first element of the array (shifting other elements down)
  167. and return it.
  168. <P></P>
  169. <DT><STRONG><A NAME="item_UNSHIFT_this%2C_LIST">UNSHIFT this, LIST</A></STRONG><BR>
  170. <DD>
  171. Insert LIST elements at the beginning of the array, moving existing elements
  172. up to make room.
  173. <P></P>
  174. <DT><STRONG><A NAME="item_SPLICE_this%2C_offset%2C_length%2C_LIST">SPLICE this, offset, length, LIST</A></STRONG><BR>
  175. <DD>
  176. Perform the equivalent of <A HREF="../../lib/Pod/perlfunc.html#item_splice"><CODE>splice</CODE></A> on the array.
  177. <P><EM>offset</EM> is optional and defaults to zero, negative values count back 
  178. from the end of the array.</P>
  179. <P><EM>length</EM> is optional and defaults to rest of the array.</P>
  180. <P><EM>LIST</EM> may be empty.</P>
  181. <P>Returns a list of the original <EM>length</EM> elements at <EM>offset</EM>.</P>
  182. <P></P></DL>
  183. <P>
  184. <HR>
  185. <H1><A NAME="caveats">CAVEATS</A></H1>
  186. <P>There is no support at present for tied @ISA. There is a potential conflict 
  187. between magic entries needed to notice setting of @ISA, and those needed to
  188. implement 'tie'.</P>
  189. <P>Very little consideration has been given to the behaviour of tied arrays
  190. when <CODE>$[</CODE> is not default value of zero.</P>
  191. <P>
  192. <HR>
  193. <H1><A NAME="author">AUTHOR</A></H1>
  194. <P>Nick Ing-Simmons <<A HREF="mailto:nik@tiuk.ti.com">nik@tiuk.ti.com</A>></P>
  195. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  196. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  197. <STRONG><P CLASS=block> Tie::Array - base class for tied arrays</P></STRONG>
  198. </TD></TR>
  199. </TABLE>
  200.  
  201. </BODY>
  202.  
  203. </HTML>
  204.