[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / ref / sequence-methods.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="ref.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="ref.html" title='Python Reference Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="numeric-types.html" />
<link rel="prev" href="sequence-types.html" />
<link rel="parent" href="specialnames.html" />
<link rel="next" href="numeric-types.html" />
<meta name='aesop' content='information' />
<title>3.3.6 Additional methods for emulation of sequence types </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="3.3.5 Emulating container types"
  href="sequence-types.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="3.3 Special method names"
  href="specialnames.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="3.3.7 Emulating numeric types"
  href="numeric-types.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="sequence-types.html">3.3.5 Emulating container types</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="specialnames.html">3.3 Special method names</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="numeric-types.html">3.3.7 Emulating numeric types</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION005360000000000000000"></A><A NAME="sequence-methods"></A>
<BR>
3.3.6 Additional methods for emulation of sequence types
  
</H2>

<P>
The following optional methods can be defined to further emulate sequence
objects.  Immutable sequences methods should at most only define
<tt class="method">__getslice__()</tt>; mutable sequences might define all three
methods.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-237' xml:id='l2h-237' class="method">__getslice__</tt></b>(</nobr></td>
  <td><var>self, i, j</var>)</td></tr></table></dt>
<dd>
<div class="versionnote"><b>Deprecated since release 2.0.</b>
Support slice objects as parameters to the
<tt class="method">__getitem__()</tt> method.</div><p></p>
Called to implement evaluation of <code><var>self</var>[<var>i</var>:<var>j</var>]</code>.
The returned object should be of the same type as <var>self</var>.  Note
that missing <var>i</var> or <var>j</var> in the slice expression are replaced
by zero or <code>sys.maxint</code>, respectively.  If negative indexes are
used in the slice, the length of the sequence is added to that index.
If the instance does not implement the <tt class="method">__len__()</tt> method, an
<tt class="exception">AttributeError</tt> is raised.
No guarantee is made that indexes adjusted this way are not still
negative.  Indexes which are greater than the length of the sequence
are not modified.
If no <tt class="method">__getslice__()</tt> is found, a slice
object is created instead, and passed to <tt class="method">__getitem__()</tt> instead.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-238' xml:id='l2h-238' class="method">__setslice__</tt></b>(</nobr></td>
  <td><var>self, i, j, sequence</var>)</td></tr></table></dt>
<dd>
Called to implement assignment to <code><var>self</var>[<var>i</var>:<var>j</var>]</code>.
Same notes for <var>i</var> and <var>j</var> as for <tt class="method">__getslice__()</tt>.

<P>
This method is deprecated. If no <tt class="method">__setslice__()</tt> is found,
or for extended slicing of the form
<code><var>self</var>[<var>i</var>:<var>j</var>:<var>k</var>]</code>, a
slice object is created, and passed to <tt class="method">__setitem__()</tt>,
instead of <tt class="method">__setslice__()</tt> being called.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-239' xml:id='l2h-239' class="method">__delslice__</tt></b>(</nobr></td>
  <td><var>self, i, j</var>)</td></tr></table></dt>
<dd>
Called to implement deletion of <code><var>self</var>[<var>i</var>:<var>j</var>]</code>.
Same notes for <var>i</var> and <var>j</var> as for <tt class="method">__getslice__()</tt>.
This method is deprecated. If no <tt class="method">__delslice__()</tt> is found,
or for extended slicing of the form
<code><var>self</var>[<var>i</var>:<var>j</var>:<var>k</var>]</code>, a
slice object is created, and passed to <tt class="method">__delitem__()</tt>,
instead of <tt class="method">__delslice__()</tt> being called.
</dl>

<P>
Notice that these methods are only invoked when a single slice with a
single colon is used, and the slice method is available.  For slice
operations involving extended slice notation, or in absence of the
slice methods, <tt class="method">__getitem__()</tt>, <tt class="method">__setitem__()</tt> or
<tt class="method">__delitem__()</tt> is called with a slice object as argument.

<P>
The following example demonstrate how to make your program or module
compatible with earlier versions of Python (assuming that methods
<tt class="method">__getitem__()</tt>, <tt class="method">__setitem__()</tt> and <tt class="method">__delitem__()</tt>
support slice objects as arguments):

<P>
<div class="verbatim"><pre>
class MyClass:
    ...
    def __getitem__(self, index):
        ...
    def __setitem__(self, index, value):
        ...
    def __delitem__(self, index):
        ...

    if sys.version_info &lt; (2, 0):
        # They won't be defined if version is at least 2.0 final

        def __getslice__(self, i, j):
            return self[max(0, i):max(0, j):]
        def __setslice__(self, i, j, seq):
            self[max(0, i):max(0, j):] = seq
        def __delslice__(self, i, j):
            del self[max(0, i):max(0, j):]
    ...
</pre></div>

<P>
Note the calls to <tt class="function">max()</tt>; these are necessary because of
the handling of negative indices before the
<tt class="method">__*slice__()</tt> methods are called.  When negative indexes are
used, the <tt class="method">__*item__()</tt> methods receive them as provided, but
the <tt class="method">__*slice__()</tt> methods get a ``cooked'' form of the index
values.  For each negative index value, the length of the sequence is
added to the index before calling the method (which may still result
in a negative index); this is the customary handling of negative
indexes by the built-in sequence types, and the <tt class="method">__*item__()</tt>
methods are expected to do this as well.  However, since they should
already be doing that, negative indexes cannot be passed in; they must
be constrained to the bounds of the sequence before being passed to
the <tt class="method">__*item__()</tt> methods.
Calling <code>max(0, i)</code> conveniently returns the proper value.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="3.3.5 Emulating container types"
  href="sequence-types.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="3.3 Special method names"
  href="specialnames.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="3.3.7 Emulating numeric types"
  href="numeric-types.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="sequence-types.html">3.3.5 Emulating container types</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="specialnames.html">3.3 Special method names</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="numeric-types.html">3.3.7 Emulating numeric types</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="ref.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="ref.html" title='Python Reference Manual' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="numeric-types.html" />
	13	<link rel="prev" href="sequence-types.html" />
	14	<link rel="parent" href="specialnames.html" />
	15	<link rel="next" href="numeric-types.html" />
	16	<meta name='aesop' content='information' />
	17	<title>3.3.6 Additional methods for emulation of sequence types </title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="3.3.5 Emulating container types"
	25	href="sequence-types.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="3.3 Special method names"
	28	href="specialnames.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="3.3.7 Emulating numeric types"
	31	href="numeric-types.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Reference Manual</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><img src='../icons/blank.png'
	38	border='0' height='32' alt='' width='32' /></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="sequence-types.html">3.3.5 Emulating container types</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="specialnames.html">3.3 Special method names</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="numeric-types.html">3.3.7 Emulating numeric types</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION005360000000000000000"></A><A NAME="sequence-methods"></A>
	56	<BR>
	57	3.3.6 Additional methods for emulation of sequence types
	58
	59	</H2>
	60
	61	<P>
	62	The following optional methods can be defined to further emulate sequence
	63	objects. Immutable sequences methods should at most only define
	64	<tt class="method">__getslice__()</tt>; mutable sequences might define all three
65	methods.
66
67	<P>
68	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
69	<td><nobr><b><tt id='l2h-237' xml:id='l2h-237' class="method">__getslice__</tt></b>(</nobr></td>
70	<td><var>self, i, j</var>)</td></tr></table></dt>
71	<dd>
72	<div class="versionnote"><b>Deprecated since release 2.0.</b>
73	Support slice objects as parameters to the
74	<tt class="method">__getitem__()</tt> method.</div><p></p>
75	Called to implement evaluation of <code><var>self</var>[<var>i</var>:<var>j</var>]</code>.
76	The returned object should be of the same type as <var>self</var>. Note
77	that missing <var>i</var> or <var>j</var> in the slice expression are replaced
78	by zero or <code>sys.maxint</code>, respectively. If negative indexes are
79	used in the slice, the length of the sequence is added to that index.
80	If the instance does not implement the <tt class="method">__len__()</tt> method, an
81	<tt class="exception">AttributeError</tt> is raised.
82	No guarantee is made that indexes adjusted this way are not still
83	negative. Indexes which are greater than the length of the sequence
84	are not modified.
85	If no <tt class="method">__getslice__()</tt> is found, a slice
86	object is created instead, and passed to <tt class="method">__getitem__()</tt> instead.
87	</dl>
88
89	<P>
90	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
91	<td><nobr><b><tt id='l2h-238' xml:id='l2h-238' class="method">__setslice__</tt></b>(</nobr></td>
92	<td><var>self, i, j, sequence</var>)</td></tr></table></dt>
93	<dd>
94	Called to implement assignment to <code><var>self</var>[<var>i</var>:<var>j</var>]</code>.
95	Same notes for <var>i</var> and <var>j</var> as for <tt class="method">__getslice__()</tt>.
96
97	<P>
98	This method is deprecated. If no <tt class="method">__setslice__()</tt> is found,
99	or for extended slicing of the form
100	<code><var>self</var>[<var>i</var>:<var>j</var>:<var>k</var>]</code>, a
101	slice object is created, and passed to <tt class="method">__setitem__()</tt>,
102	instead of <tt class="method">__setslice__()</tt> being called.
103	</dl>
104
105	<P>
106	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
107	<td><nobr><b><tt id='l2h-239' xml:id='l2h-239' class="method">__delslice__</tt></b>(</nobr></td>
108	<td><var>self, i, j</var>)</td></tr></table></dt>
109	<dd>
110	Called to implement deletion of <code><var>self</var>[<var>i</var>:<var>j</var>]</code>.
111	Same notes for <var>i</var> and <var>j</var> as for <tt class="method">__getslice__()</tt>.
112	This method is deprecated. If no <tt class="method">__delslice__()</tt> is found,
113	or for extended slicing of the form
114	<code><var>self</var>[<var>i</var>:<var>j</var>:<var>k</var>]</code>, a
115	slice object is created, and passed to <tt class="method">__delitem__()</tt>,
116	instead of <tt class="method">__delslice__()</tt> being called.
117	</dl>
118
119	<P>
120	Notice that these methods are only invoked when a single slice with a
121	single colon is used, and the slice method is available. For slice
122	operations involving extended slice notation, or in absence of the
123	slice methods, <tt class="method">__getitem__()</tt>, <tt class="method">__setitem__()</tt> or
124	<tt class="method">__delitem__()</tt> is called with a slice object as argument.
125
126	<P>
127	The following example demonstrate how to make your program or module
128	compatible with earlier versions of Python (assuming that methods
129	<tt class="method">__getitem__()</tt>, <tt class="method">__setitem__()</tt> and <tt class="method">__delitem__()</tt>
130	support slice objects as arguments):
131
132	<P>
133	<div class="verbatim"><pre>
134	class MyClass:
135	...
136	def __getitem__(self, index):
137	...
138	def __setitem__(self, index, value):
139	...
140	def __delitem__(self, index):
141	...
142
143	if sys.version_info < (2, 0):
144	# They won't be defined if version is at least 2.0 final
145
146	def __getslice__(self, i, j):
147	return self[max(0, i):max(0, j):]
148	def __setslice__(self, i, j, seq):
149	self[max(0, i):max(0, j):] = seq
150	def __delslice__(self, i, j):
151	del self[max(0, i):max(0, j):]
152	...
153	</pre></div>
154
155	<P>
156	Note the calls to <tt class="function">max()</tt>; these are necessary because of
157	the handling of negative indices before the
158	<tt class="method">__*slice__()</tt> methods are called. When negative indexes are
159	used, the <tt class="method">__*item__()</tt> methods receive them as provided, but
160	the <tt class="method">__*slice__()</tt> methods get a ``cooked'' form of the index
161	values. For each negative index value, the length of the sequence is
162	added to the index before calling the method (which may still result
163	in a negative index); this is the customary handling of negative
164	indexes by the built-in sequence types, and the <tt class="method">__*item__()</tt>
165	methods are expected to do this as well. However, since they should
166	already be doing that, negative indexes cannot be passed in; they must
167	be constrained to the bounds of the sequence before being passed to
168	the <tt class="method">__*item__()</tt> methods.
169	Calling <code>max(0, i)</code> conveniently returns the proper value.
170
171	<P>
172
173	<DIV CLASS="navigation">
174	<div class='online-navigation'>
175	<p></p><hr />
176	<table align="center" width="100%" cellpadding="0" cellspacing="2">
177	<tr>
178	<td class='online-navigation'><a rel="prev" title="3.3.5 Emulating container types"
179	href="sequence-types.html"><img src='../icons/previous.png'
180	border='0' height='32' alt='Previous Page' width='32' /></A></td>
181	<td class='online-navigation'><a rel="parent" title="3.3 Special method names"
182	href="specialnames.html"><img src='../icons/up.png'
183	border='0' height='32' alt='Up One Level' width='32' /></A></td>
184	<td class='online-navigation'><a rel="next" title="3.3.7 Emulating numeric types"
185	href="numeric-types.html"><img src='../icons/next.png'
186	border='0' height='32' alt='Next Page' width='32' /></A></td>
187	<td align="center" width="100%">Python Reference Manual</td>
188	<td class='online-navigation'><a rel="contents" title="Table of Contents"
189	href="contents.html"><img src='../icons/contents.png'
190	border='0' height='32' alt='Contents' width='32' /></A></td>
191	<td class='online-navigation'><img src='../icons/blank.png'
192	border='0' height='32' alt='' width='32' /></td>
193	<td class='online-navigation'><a rel="index" title="Index"
194	href="genindex.html"><img src='../icons/index.png'
195	border='0' height='32' alt='Index' width='32' /></A></td>
196	</tr></table>
197	<div class='online-navigation'>
198	<b class="navlabel">Previous:</b>
199	<a class="sectref" rel="prev" href="sequence-types.html">3.3.5 Emulating container types</A>
200	<b class="navlabel">Up:</b>
201	<a class="sectref" rel="parent" href="specialnames.html">3.3 Special method names</A>
202	<b class="navlabel">Next:</b>
203	<a class="sectref" rel="next" href="numeric-types.html">3.3.7 Emulating numeric types</A>
204	</div>
205	</div>
206	<hr />
207	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
208	</DIV>
209	<!--End of Navigation Panel-->
210	<ADDRESS>
211	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
212	</ADDRESS>
213	</BODY>
214	</HTML>