~dkuhlman/python-training-materials/Materials : revision 45

1

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

2

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

3

4

5

6

<head>

7

8

9

<title>Sequence Protocol — Python 3.5.2 documentation</title>

10

11

12

13

14

15

var DOCUMENTATION_OPTIONS = {

16

URL_ROOT: '../',

17

VERSION: '3.5.2',

18

COLLAPSE_INDEX: false,

19

FILE_SUFFIX: '.html',

20

HAS_SOURCE: true

21

};

22

</script>

23

24

25

26

27

28

title="Search within Python 3.5.2 documentation"

29

href="../_static/opensearch.xml"/>

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

</head>

45

46

47

<h3>Navigation</h3>

48

<ul>

49

50

<a href="../genindex.html" title="General Index"

51

accesskey="I">index</a></li>

52

53

<a href="../py-modindex.html" title="Python Module Index"

54

>modules</a> |</li>

55

56

<a href="mapping.html" title="Mapping Protocol"

57

accesskey="N">next</a> |</li>

58

59

<a href="number.html" title="Number Protocol"

60

accesskey="P">previous</a> |</li>

61

<li><img src="../_static/py.png" alt=""

62

style="vertical-align: middle; margin-top: -1px"/></li>

63

<li><a href="https://www.python.org/">Python</a> »</li>

64

<li>

65

3.5.2

66

<a href="../index.html">Documentation </a> »

67

</li>

68

69

<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>

70

<li class="nav-item nav-item-2"><a href="abstract.html" accesskey="U">Abstract Objects Layer</a> »</li>

71

72

73

74

75

76

77

78

79

80

</form>

81

</div>

82

83

|

84

</li>

85

86

</ul>

87

</div>

88

89

90

91

92

93

94

95

<h1>Sequence Protocol<a class="headerlink" href="#sequence-protocol" title="Permalink to this headline">¶</a></h1>

96

97

98

int <code class="descname">PySequence_Check</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.PySequence_Check" title="Permalink to this definition">¶</a></dt>

99

<dd>Return <code class="docutils literal">1</code> if the object provides sequence protocol, and <code class="docutils literal">0</code> otherwise.

100

This function always succeeds.

101

</dd></dl>

102

103

104

105

Py_ssize_t <code class="descname">PySequence_Size</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.PySequence_Size" title="Permalink to this definition">¶</a></dt>

106

107

Py_ssize_t <code class="descname">PySequence_Length</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.PySequence_Length" title="Permalink to this definition">¶</a></dt>

108

<dd>Returns the number of objects in sequence o on success, and <code class="docutils literal">-1</code> on failure.

109

For objects that do not provide sequence protocol, this is equivalent to the

110

Python expression <code class="docutils literal">len(o)</code>.

111

</dd></dl>

112

113

114

115

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_Concat</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o1, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o2)<a class="headerlink" href="#c.PySequence_Concat" title="Permalink to this definition">¶</a></dt>

116

<dd>Return value: New reference.Return the concatenation of o1 and o2 on success, and NULL on failure.

117

This is the equivalent of the Python expression <code class="docutils literal">o1 + o2</code>.

118

</dd></dl>

119

120

121

122

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_Repeat</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, Py_ssize_t count)<a class="headerlink" href="#c.PySequence_Repeat" title="Permalink to this definition">¶</a></dt>

123

<dd>Return value: New reference.Return the result of repeating sequence object o count times, or NULL on

124

failure. This is the equivalent of the Python expression <code class="docutils literal">o * count</code>.

125

</dd></dl>

126

127

128

129

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_InPlaceConcat</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o1, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o2)<a class="headerlink" href="#c.PySequence_InPlaceConcat" title="Permalink to this definition">¶</a></dt>

130

<dd>Return value: New reference.Return the concatenation of o1 and o2 on success, and NULL on failure.

131

The operation is done in-place when o1 supports it. This is the equivalent

132

of the Python expression <code class="docutils literal">o1 += o2</code>.

133

</dd></dl>

134

135

136

137

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_InPlaceRepeat</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, Py_ssize_t count)<a class="headerlink" href="#c.PySequence_InPlaceRepeat" title="Permalink to this definition">¶</a></dt>

138

<dd>Return value: New reference.Return the result of repeating sequence object o count times, or NULL on

139

failure. The operation is done in-place when o supports it. This is the

140

equivalent of the Python expression <code class="docutils literal">o *= count</code>.

141

</dd></dl>

142

143

144

145

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_GetItem</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, Py_ssize_t i)<a class="headerlink" href="#c.PySequence_GetItem" title="Permalink to this definition">¶</a></dt>

146

<dd>Return value: New reference.Return the ith element of o, or NULL on failure. This is the equivalent of

147

the Python expression <code class="docutils literal">o[i]</code>.

148

</dd></dl>

149

150

151

152

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_GetSlice</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, Py_ssize_t i1, Py_ssize_t i2)<a class="headerlink" href="#c.PySequence_GetSlice" title="Permalink to this definition">¶</a></dt>

153

<dd>Return value: New reference.Return the slice of sequence object o between i1 and i2, or NULL on

154

failure. This is the equivalent of the Python expression <code class="docutils literal">o[i1:i2]</code>.

155

</dd></dl>

156

157

158

159

int <code class="descname">PySequence_SetItem</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, Py_ssize_t i, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *v)<a class="headerlink" href="#c.PySequence_SetItem" title="Permalink to this definition">¶</a></dt>

160

<dd>Assign object v to the ith element of o. Raise an exception

161

and return <code class="docutils literal">-1</code> on failure; return <code class="docutils literal">0</code> on success. This

162

is the equivalent of the Python statement <code class="docutils literal">o[i] = v</code>. This function does

163

not steal a reference to v.

164

If v is NULL, the element is deleted, however this feature is

165

deprecated in favour of using <a class="reference internal" href="#c.PySequence_DelItem" title="PySequence_DelItem"><code class="xref c c-func docutils literal">PySequence_DelItem()</code></a>.

166

</dd></dl>

167

168

169

170

int <code class="descname">PySequence_DelItem</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, Py_ssize_t i)<a class="headerlink" href="#c.PySequence_DelItem" title="Permalink to this definition">¶</a></dt>

171

<dd>Delete the ith element of object o. Returns <code class="docutils literal">-1</code> on failure. This is the

172

equivalent of the Python statement <code class="docutils literal">del o[i]</code>.

173

</dd></dl>

174

175

176

177

int <code class="descname">PySequence_SetSlice</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, Py_ssize_t i1, Py_ssize_t i2, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *v)<a class="headerlink" href="#c.PySequence_SetSlice" title="Permalink to this definition">¶</a></dt>

178

<dd>Assign the sequence object v to the slice in sequence object o from i1 to

179

i2. This is the equivalent of the Python statement <code class="docutils literal">o[i1:i2] = v</code>.

180

</dd></dl>

181

182

183

184

int <code class="descname">PySequence_DelSlice</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, Py_ssize_t i1, Py_ssize_t i2)<a class="headerlink" href="#c.PySequence_DelSlice" title="Permalink to this definition">¶</a></dt>

185

<dd>Delete the slice in sequence object o from i1 to i2. Returns <code class="docutils literal">-1</code> on

186

failure. This is the equivalent of the Python statement <code class="docutils literal">del o[i1:i2]</code>.

187

</dd></dl>

188

189

190

191

Py_ssize_t <code class="descname">PySequence_Count</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *value)<a class="headerlink" href="#c.PySequence_Count" title="Permalink to this definition">¶</a></dt>

192

<dd>Return the number of occurrences of value in o, that is, return the number

193

of keys for which <code class="docutils literal">o[key] == value</code>. On failure, return <code class="docutils literal">-1</code>. This is

194

equivalent to the Python expression <code class="docutils literal">o.count(value)</code>.

195

</dd></dl>

196

197

198

199

int <code class="descname">PySequence_Contains</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *value)<a class="headerlink" href="#c.PySequence_Contains" title="Permalink to this definition">¶</a></dt>

200

<dd>Determine if o contains value. If an item in o is equal to value,

201

return <code class="docutils literal">1</code>, otherwise return <code class="docutils literal">0</code>. On error, return <code class="docutils literal">-1</code>. This is

202

equivalent to the Python expression <code class="docutils literal">value in o</code>.

203

</dd></dl>

204

205

206

207

Py_ssize_t <code class="descname">PySequence_Index</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *value)<a class="headerlink" href="#c.PySequence_Index" title="Permalink to this definition">¶</a></dt>

208

<dd>Return the first index i for which <code class="docutils literal">o[i] == value</code>. On error, return

209

<code class="docutils literal">-1</code>. This is equivalent to the Python expression <code class="docutils literal">o.index(value)</code>.

210

</dd></dl>

211

212

213

214

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_List</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.PySequence_List" title="Permalink to this definition">¶</a></dt>

215

<dd>Return value: New reference.Return a list object with the same contents as the sequence or iterable o,

216

or NULL on failure. The returned list is guaranteed to be new. This is

217

equivalent to the Python expression <code class="docutils literal">list(o)</code>.

218

</dd></dl>

219

220

221

222

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_Tuple</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.PySequence_Tuple" title="Permalink to this definition">¶</a></dt>

223

<dd>Return value: New reference.Return a tuple object with the same contents as the arbitrary sequence o or

224

NULL on failure. If o is a tuple, a new reference will be returned,

225

otherwise a tuple will be constructed with the appropriate contents. This is

226

equivalent to the Python expression <code class="docutils literal">tuple(o)</code>.

227

</dd></dl>

228

229

230

231

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_Fast</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, const char *m)<a class="headerlink" href="#c.PySequence_Fast" title="Permalink to this definition">¶</a></dt>

232

<dd>Return value: New reference.Return the sequence o as a list, unless it is already a tuple or list, in

233

which case o is returned. Use <a class="reference internal" href="#c.PySequence_Fast_GET_ITEM" title="PySequence_Fast_GET_ITEM"><code class="xref c c-func docutils literal">PySequence_Fast_GET_ITEM()</code></a> to access

234

the members of the result. Returns NULL on failure. If the object is not

235

a sequence, raises <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> with m as the message text.

236

</dd></dl>

237

238

239

240

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_Fast_GET_ITEM</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, Py_ssize_t i)<a class="headerlink" href="#c.PySequence_Fast_GET_ITEM" title="Permalink to this definition">¶</a></dt>

241

<dd>Return value: Borrowed reference.Return the ith element of o, assuming that o was returned by

242

<a class="reference internal" href="#c.PySequence_Fast" title="PySequence_Fast"><code class="xref c c-func docutils literal">PySequence_Fast()</code></a>, o is not NULL, and that i is within bounds.

243

</dd></dl>

244

245

246

247

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>** <code class="descname">PySequence_Fast_ITEMS</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.PySequence_Fast_ITEMS" title="Permalink to this definition">¶</a></dt>

248

<dd>Return the underlying array of PyObject pointers. Assumes that o was returned

249

by <a class="reference internal" href="#c.PySequence_Fast" title="PySequence_Fast"><code class="xref c c-func docutils literal">PySequence_Fast()</code></a> and o is not NULL.

250

Note, if a list gets resized, the reallocation may relocate the items array.

251

So, only use the underlying array pointer in contexts where the sequence

252

cannot change.

253

</dd></dl>

254

255

256

257

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_ITEM</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o, Py_ssize_t i)<a class="headerlink" href="#c.PySequence_ITEM" title="Permalink to this definition">¶</a></dt>

258

<dd>Return value: New reference.Return the ith element of o or NULL on failure. Macro form of

259

<a class="reference internal" href="#c.PySequence_GetItem" title="PySequence_GetItem"><code class="xref c c-func docutils literal">PySequence_GetItem()</code></a> but without checking that

260

<a class="reference internal" href="#c.PySequence_Check" title="PySequence_Check"><code class="xref c c-func docutils literal">PySequence_Check()</code></a> on o is true and without adjustment for negative

261

indices.

262

</dd></dl>

263

264

265

266

Py_ssize_t <code class="descname">PySequence_Fast_GET_SIZE</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.PySequence_Fast_GET_SIZE" title="Permalink to this definition">¶</a></dt>

267

<dd>Returns the length of o, assuming that o was returned by

268

<a class="reference internal" href="#c.PySequence_Fast" title="PySequence_Fast"><code class="xref c c-func docutils literal">PySequence_Fast()</code></a> and that o is not NULL. The size can also be

269

gotten by calling <a class="reference internal" href="#c.PySequence_Size" title="PySequence_Size"><code class="xref c c-func docutils literal">PySequence_Size()</code></a> on o, but

270

<a class="reference internal" href="#c.PySequence_Fast_GET_SIZE" title="PySequence_Fast_GET_SIZE"><code class="xref c c-func docutils literal">PySequence_Fast_GET_SIZE()</code></a> is faster because it can assume o is a list

271

or tuple.

272

</dd></dl>

273

274

</div>

275

276

277

</div>

278

</div>

279

</div>

280

281

282

<h4>Previous topic</h4>

283

<a href="number.html"

284

title="previous chapter">Number Protocol</a>

285

<h4>Next topic</h4>

286

<a href="mapping.html"

287

title="next chapter">Mapping Protocol</a>

288

289

290

291

<li><a href="../bugs.html">Report a Bug</a></li>

292

<li><a href="../_sources/c-api/sequence.txt"

293

rel="nofollow">Show Source</a></li>

294

</ul>

295

</div>

296

</div>

297

</div>

298

299

</div>

300

301

<h3>Navigation</h3>

302

<ul>

303

304

<a href="../genindex.html" title="General Index"

305

>index</a></li>

306

307

<a href="../py-modindex.html" title="Python Module Index"

308

>modules</a> |</li>

309

310

<a href="mapping.html" title="Mapping Protocol"

311

>next</a> |</li>

312

313

<a href="number.html" title="Number Protocol"

314

>previous</a> |</li>

315

<li><img src="../_static/py.png" alt=""

316

style="vertical-align: middle; margin-top: -1px"/></li>

317

<li><a href="https://www.python.org/">Python</a> »</li>

318

<li>

319

3.5.2

320

<a href="../index.html">Documentation </a> »

321

</li>

322

323

<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>

324

<li class="nav-item nav-item-2"><a href="abstract.html" >Abstract Objects Layer</a> »</li>

325

326

327

328

329

330

331

332

333

334

</form>

335

</div>

336

337

|

338

</li>

339

340

</ul>

341

</div>

342

343

344

345

The Python Software Foundation is a non-profit corporation.

346

<a href="https://www.python.org/psf/donations/">Please donate.</a>

347

348

Last updated on Sep 23, 2016.

349

<a href="../bugs.html">Found a bug</a>?

350

351

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

352

</div>

353

354

</body>

355

</html>

b'\\ No newline at end of file'