~dkuhlman/python-training-materials/Materials

for <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> and store Unicode values internally as UCS2. It is also

possible to build a UCS4 version of Python (most recent Linux distributions come

with UCS4 builds of Python). These builds then use a 32-bit type for

<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> and store Unicode data internally as UCS4. On platforms

where <code class="xref c c-type docutils literal">wchar_t</code> is available and compatible with the chosen Python

Unicode build variant, <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> is a typedef alias for

<code class="xref c c-type docutils literal">wchar_t</code> to enhance native platform compatibility. On all other

platforms, <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> is a typedef alias for either <code class="xref c c-type docutils literal">unsigned

short</code> (UCS2) or <code class="xref c c-type docutils literal">unsigned long</code> (UCS4).

</dd></dl>

100

101

Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep

102

this in mind when writing extensions or interfaces.

103

104

105

<code class="descname">PyUnicodeObject</code><a class="headerlink" href="#c.PyUnicodeObject" title="Permalink to this definition">¶</a></dt>

106

<dd>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal">PyObject</code></a> represents a Python Unicode object.

107

</dd></dl>

108

109

110

111

<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyUnicode_Type</code><a class="headerlink" href="#c.PyUnicode_Type" title="Permalink to this definition">¶</a></dt>

112

<dd>This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal">PyTypeObject</code></a> represents the Python Unicode type. It

113

is exposed to Python code as <code class="docutils literal">unicode</code> and <code class="docutils literal">types.UnicodeType</code>.

114

</dd></dl>

115

116

The following APIs are really C macros and can be used to do fast checks and to

117

access internal read-only data of Unicode objects:

118

119

120

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

121

<dd>Return true if the object o is a Unicode object or an instance of a Unicode

122

subtype.

123

124

Changed in version 2.2: Allowed subtypes to be accepted.

125

</div>

126

</dd></dl>

127

128

129

130

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

131

<dd>Return true if the object o is a Unicode object, but not an instance of a

132

subtype.

133

134

New in version 2.2.

135

</div>

136

</dd></dl>

137

138

139

140

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

141

<dd>Return the size of the object. o has to be a <a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject"><code class="xref c c-type docutils literal">PyUnicodeObject</code></a> (not

142

checked).

143

144

Changed in version 2.5: This function returned an <code class="xref c c-type docutils literal">int</code> type. This might require changes

145

in your code for properly supporting 64-bit systems.

146

</div>

147

</dd></dl>

148

149

150

151

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

152

<dd>Return the size of the object’s internal buffer in bytes. o has to be a

153

<a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject"><code class="xref c c-type docutils literal">PyUnicodeObject</code></a> (not checked).

154

155

156

in your code for properly supporting 64-bit systems.

157

</div>

158

</dd></dl>

159

160

161

162

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

163

<dd>Return a pointer to the internal <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> buffer of the object. o

164

has to be a <a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject"><code class="xref c c-type docutils literal">PyUnicodeObject</code></a> (not checked).

165

</dd></dl>

166

167

168

169

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

170

<dd>Return a pointer to the internal buffer of the object. o has to be a

171

<a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject"><code class="xref c c-type docutils literal">PyUnicodeObject</code></a> (not checked).

172

</dd></dl>

173

174

175

176

int <code class="descname">PyUnicode_ClearFreeList</code>()<a class="headerlink" href="#c.PyUnicode_ClearFreeList" title="Permalink to this definition">¶</a></dt>

177

<dd>Clear the free list. Return the total number of freed items.

178

179

New in version 2.6.

180

</div>

181

</dd></dl>

182

183

</div>

184

185

<h3>Unicode Character Properties<a class="headerlink" href="#unicode-character-properties" title="Permalink to this headline">¶</a></h3>

186

Unicode provides many different character properties. The most often needed ones

187

are available through these macros which are mapped to C functions depending on

188

the Python configuration.

189

190

191

int <code class="descname">Py_UNICODE_ISSPACE</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_ISSPACE" title="Permalink to this definition">¶</a></dt>

192

<dd>Return 1 or 0 depending on whether ch is a whitespace character.

193

</dd></dl>

194

195

196

197

int <code class="descname">Py_UNICODE_ISLOWER</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_ISLOWER" title="Permalink to this definition">¶</a></dt>

198

<dd>Return 1 or 0 depending on whether ch is a lowercase character.

199

</dd></dl>

200

201

202

203

int <code class="descname">Py_UNICODE_ISUPPER</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_ISUPPER" title="Permalink to this definition">¶</a></dt>

204

<dd>Return 1 or 0 depending on whether ch is an uppercase character.

205

</dd></dl>

206

207

208

209

int <code class="descname">Py_UNICODE_ISTITLE</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_ISTITLE" title="Permalink to this definition">¶</a></dt>

210

<dd>Return 1 or 0 depending on whether ch is a titlecase character.

211

</dd></dl>

212

213

214

215

int <code class="descname">Py_UNICODE_ISLINEBREAK</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_ISLINEBREAK" title="Permalink to this definition">¶</a></dt>

216

<dd>Return 1 or 0 depending on whether ch is a linebreak character.

217

</dd></dl>

218

219

220

221

int <code class="descname">Py_UNICODE_ISDECIMAL</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_ISDECIMAL" title="Permalink to this definition">¶</a></dt>

222

<dd>Return 1 or 0 depending on whether ch is a decimal character.

223

</dd></dl>

224

225

226

227

int <code class="descname">Py_UNICODE_ISDIGIT</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_ISDIGIT" title="Permalink to this definition">¶</a></dt>

228

<dd>Return 1 or 0 depending on whether ch is a digit character.

229

</dd></dl>

230

231

232

233

int <code class="descname">Py_UNICODE_ISNUMERIC</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_ISNUMERIC" title="Permalink to this definition">¶</a></dt>

234

<dd>Return 1 or 0 depending on whether ch is a numeric character.

235

</dd></dl>

236

237

238

239

int <code class="descname">Py_UNICODE_ISALPHA</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_ISALPHA" title="Permalink to this definition">¶</a></dt>

240

<dd>Return 1 or 0 depending on whether ch is an alphabetic character.

241

</dd></dl>

242

243

244

245

int <code class="descname">Py_UNICODE_ISALNUM</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_ISALNUM" title="Permalink to this definition">¶</a></dt>

246

<dd>Return 1 or 0 depending on whether ch is an alphanumeric character.

247

</dd></dl>

248

249

These APIs can be used for fast direct character conversions:

250

251

252

<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> <code class="descname">Py_UNICODE_TOLOWER</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_TOLOWER" title="Permalink to this definition">¶</a></dt>

253

<dd>Return the character ch converted to lower case.

254

</dd></dl>

255

256

257

258

<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> <code class="descname">Py_UNICODE_TOUPPER</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_TOUPPER" title="Permalink to this definition">¶</a></dt>

259

<dd>Return the character ch converted to upper case.

260

</dd></dl>

261

262

263

264

<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> <code class="descname">Py_UNICODE_TOTITLE</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_TOTITLE" title="Permalink to this definition">¶</a></dt>

265

<dd>Return the character ch converted to title case.

266

</dd></dl>

267

268

269

270

int <code class="descname">Py_UNICODE_TODECIMAL</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_TODECIMAL" title="Permalink to this definition">¶</a></dt>

271

<dd>Return the character ch converted to a decimal positive integer. Return

272

<code class="docutils literal">-1</code> if this is not possible. This macro does not raise exceptions.

273

</dd></dl>

274

275

276

277

int <code class="descname">Py_UNICODE_TODIGIT</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_TODIGIT" title="Permalink to this definition">¶</a></dt>

278

<dd>Return the character ch converted to a single digit integer. Return <code class="docutils literal">-1</code> if

279

this is not possible. This macro does not raise exceptions.

280

</dd></dl>

281

282

283

284

double <code class="descname">Py_UNICODE_TONUMERIC</code>(<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> ch)<a class="headerlink" href="#c.Py_UNICODE_TONUMERIC" title="Permalink to this definition">¶</a></dt>

285

<dd>Return the character ch converted to a double. Return <code class="docutils literal">-1.0</code> if this is not

286

possible. This macro does not raise exceptions.

287

</dd></dl>

288

289

</div>

290

291

<h3>Plain Py_UNICODE<a class="headerlink" href="#plain-py-unicode" title="Permalink to this headline">¶</a></h3>

292

To create Unicode objects and access their basic sequence properties, use these

293

APIs:

294

295

296

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_FromUnicode</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *u, Py_ssize_t size)<a class="headerlink" href="#c.PyUnicode_FromUnicode" title="Permalink to this definition">¶</a></dt>

297

<dd>Return value: New reference.Create a Unicode object from the Py_UNICODE buffer u of the given size. u

298

may be NULL which causes the contents to be undefined. It is the user’s

299

responsibility to fill in the needed data. The buffer is copied into the new

300

object. If the buffer is not NULL, the return value might be a shared object.

301

Therefore, modification of the resulting Unicode object is only allowed when u

302

is NULL.

303

304

305

changes in your code for properly supporting 64-bit systems.

306

</div>

307

</dd></dl>

308

309

310

311

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

312

<dd>Return value: New reference.Create a Unicode object from the char buffer u. The bytes will be interpreted

313

as being UTF-8 encoded. u may also be NULL which

314

causes the contents to be undefined. It is the user’s responsibility to fill in

315

the needed data. The buffer is copied into the new object. If the buffer is not

316

NULL, the return value might be a shared object. Therefore, modification of

317

the resulting Unicode object is only allowed when u is NULL.

318

319

New in version 2.6.

320

</div>

321

</dd></dl>

322

323

324

325

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

326

<dd>Return value: New reference.Create a Unicode object from an UTF-8 encoded null-terminated char buffer

327

u.

328

329

New in version 2.6.

330

</div>

331

</dd></dl>

332

333

334

335

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

336

<dd>Return value: New reference.Take a C <code class="xref c c-func docutils literal">printf()</code>-style format string and a variable number of

337

arguments, calculate the size of the resulting Python unicode string and return

338

a string with the values formatted into it. The variable arguments must be C

339

types and must correspond exactly to the format characters in the format

340

string. The following format characters are allowed:

341

342

343

344

345

346

</colgroup>

347

348

<tr class="row-odd"><th class="head">Format Characters</th>

349

350

<th class="head">Comment</th>

351

</tr>

352

</thead>

353

354

355

356

<td>The literal % character.</td>

357

</tr>

358

359

360

<td>A single character,

361

represented as an C int.</td>

362

</tr>

363

364

365

<td>Exactly equivalent to

366

<code class="docutils literal">printf("%d")</code>.</td>

367

</tr>

368

369

<td>unsigned int</td>

370

<td>Exactly equivalent to

371

<code class="docutils literal">printf("%u")</code>.</td>

372

</tr>

373

374

375

<td>Exactly equivalent to

376

<code class="docutils literal">printf("%ld")</code>.</td>

377

</tr>

378

379

<td>unsigned long</td>

380

<td>Exactly equivalent to

381

<code class="docutils literal">printf("%lu")</code>.</td>

382

</tr>

383

384

<td>Py_ssize_t</td>

385

<td>Exactly equivalent to

386

<code class="docutils literal">printf("%zd")</code>.</td>

387

</tr>

388

389

390

<td>Exactly equivalent to

391

<code class="docutils literal">printf("%zu")</code>.</td>

392

</tr>

393

394

395

<td>Exactly equivalent to

396

<code class="docutils literal">printf("%i")</code>.</td>

397

</tr>

398

399

400

<td>Exactly equivalent to

401

<code class="docutils literal">printf("%x")</code>.</td>

402

</tr>

403

404

405

<td>A null-terminated C character

406

array.</td>

407

</tr>

408

409

410

<td>The hex representation of a C

411

pointer. Mostly equivalent to

412

<code class="docutils literal">printf("%p")</code> except that

413

it is guaranteed to start with

414

the literal <code class="docutils literal">0x</code> regardless

415

of what the platform’s

416

<code class="docutils literal">printf</code> yields.</td>

417

</tr>

418

419

<td>PyObject*</td>

420

<td>A unicode object.</td>

421

</tr>

422

423

<td>PyObject*, char *</td>

424

<td>A unicode object (which may be

425

NULL) and a null-terminated

426

C character array as a second

427

parameter (which will be used,

428

if the first parameter is

429

NULL).</td>

430

</tr>

431

432

<td>PyObject*</td>

433

<td>The result of calling

434

<code class="xref py py-func docutils literal">PyObject_Unicode()</code>.</td>

435

</tr>

436

437

<td>PyObject*</td>

438

<td>The result of calling

439

<code class="xref py py-func docutils literal">PyObject_Repr()</code>.</td>

440

</tr>

441

</tbody>

442

</table>

443

An unrecognized format character causes all the rest of the format string to be

444

copied as-is to the result string, and any extra arguments discarded.

445

446

New in version 2.6.

447

</div>

448

</dd></dl>

449

450

451

452

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

453

<dd>Return value: New reference.Identical to <code class="xref py py-func docutils literal">PyUnicode_FromFormat()</code> except that it takes exactly two

454

arguments.

455

456

New in version 2.6.

457

</div>

458

</dd></dl>

459

460

461

462

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

463

<dd>Return a read-only pointer to the Unicode object’s internal

464

<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> buffer, NULL if unicode is not a Unicode object.

465

Note that the resulting <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE*</code></a> string may contain embedded

466

null characters, which would cause the string to be truncated when used in

467

most C functions.

468

</dd></dl>

469

470

471

472

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

473

<dd>Return the length of the Unicode object.

474

475

476

in your code for properly supporting 64-bit systems.

477

</div>

478

</dd></dl>

479

480

481

482

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

483

<dd>Return value: New reference.Coerce an encoded object obj to an Unicode object and return a reference with

484

incremented refcount.

485

String and other char buffer compatible objects are decoded according to the

486

given encoding and using the error handling defined by errors. Both can be

487

NULL to have the interface use the default values (see the next section for

488

details).

489

All other objects, including Unicode objects, cause a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> to be

490

set.

491

The API returns NULL if there was an error. The caller is responsible for

492

decref’ing the returned objects.

493

</dd></dl>

494

495

496

497

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

498

<dd>Return value: New reference.Shortcut for <code class="docutils literal">PyUnicode_FromEncodedObject(obj, NULL, "strict")</code> which is used

499

throughout the interpreter whenever coercion to Unicode is needed.

500

</dd></dl>

501

502

If the platform supports <code class="xref c c-type docutils literal">wchar_t</code> and provides a header file wchar.h,

503

Python can interface directly to this type using the following functions.

504

Support is optimized if Python’s own <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> type is identical to

505

the system’s <code class="xref c c-type docutils literal">wchar_t</code>.

506

</div>

507

508

<h3>wchar_t Support<a class="headerlink" href="#wchar-t-support" title="Permalink to this headline">¶</a></h3>

509

<code class="xref c c-type docutils literal">wchar_t</code> support for platforms which support it:

510

511

512

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_FromWideChar</code>(const wchar_t *w, Py_ssize_t size)<a class="headerlink" href="#c.PyUnicode_FromWideChar" title="Permalink to this definition">¶</a></dt>

513

<dd>Return value: New reference.Create a Unicode object from the <code class="xref c c-type docutils literal">wchar_t</code> buffer w of the given size.

514

Return NULL on failure.

515

516

517

changes in your code for properly supporting 64-bit systems.

518

</div>

519

</dd></dl>

520

521

522

523

Py_ssize_t <code class="descname">PyUnicode_AsWideChar</code>(<a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject">PyUnicodeObject</a> *unicode, wchar_t *w, Py_ssize_t size)<a class="headerlink" href="#c.PyUnicode_AsWideChar" title="Permalink to this definition">¶</a></dt>

524

<dd>Copy the Unicode object contents into the <code class="xref c c-type docutils literal">wchar_t</code> buffer w. At most

525

size <code class="xref c c-type docutils literal">wchar_t</code> characters are copied (excluding a possibly trailing

526

0-termination character). Return the number of <code class="xref c c-type docutils literal">wchar_t</code> characters

527

copied or -1 in case of an error. Note that the resulting <code class="xref c c-type docutils literal">wchar_t</code>

528

string may or may not be 0-terminated. It is the responsibility of the caller

529

to make sure that the <code class="xref c c-type docutils literal">wchar_t</code> string is 0-terminated in case this is

530

required by the application. Also, note that the <code class="xref c c-type docutils literal">wchar_t*</code> string

531

might contain null characters, which would cause the string to be truncated

532

when used with most C functions.

533

534

535

type for size. This might require changes in your code for properly

536

supporting 64-bit systems.

537

</div>

538

</dd></dl>

539

540

</div>

541

</div>

542

543

<h2>Built-in Codecs<a class="headerlink" href="#built-in-codecs" title="Permalink to this headline">¶</a></h2>

544

Python provides a set of built-in codecs which are written in C for speed. All of

545

these codecs are directly usable via the following functions.

546

Many of the following APIs take two arguments encoding and errors, and they

547

have the same semantics as the ones of the built-in <a class="reference internal" href="../library/functions.html#unicode" title="unicode"><code class="xref py py-func docutils literal">unicode()</code></a> Unicode

548

object constructor.

549

Setting encoding to NULL causes the default encoding to be used which is

550

ASCII. The file system calls should use <code class="xref c c-data docutils literal">Py_FileSystemDefaultEncoding</code>

551

as the encoding for file names. This variable should be treated as read-only: on

552

some systems, it will be a pointer to a static string, on others, it will change

553

at run-time (such as when the application invokes setlocale).

554

Error handling is set by errors which may also be set to NULL meaning to use

555

the default handling defined for the codec. Default error handling for all

556

built-in codecs is “strict” (<a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> is raised).

557

The codecs all use a similar interface. Only deviation from the following

558

generic ones are documented for simplicity.

559

560

<h3>Generic Codecs<a class="headerlink" href="#generic-codecs" title="Permalink to this headline">¶</a></h3>

561

These are the generic codec APIs:

562

563

564

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Decode</code>(const char *s, Py_ssize_t size, const char *encoding, const char *errors)<a class="headerlink" href="#c.PyUnicode_Decode" title="Permalink to this definition">¶</a></dt>

565

<dd>Return value: New reference.Create a Unicode object by decoding size bytes of the encoded string s.

566

encoding and errors have the same meaning as the parameters of the same name

567

in the <a class="reference internal" href="../library/functions.html#unicode" title="unicode"><code class="xref py py-func docutils literal">unicode()</code></a> built-in function. The codec to be used is looked up

568

using the Python codec registry. Return NULL if an exception was raised by

569

the codec.

570

571

572

changes in your code for properly supporting 64-bit systems.

573

</div>

574

</dd></dl>

575

576

577

578

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Encode</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, const char *encoding, const char *errors)<a class="headerlink" href="#c.PyUnicode_Encode" title="Permalink to this definition">¶</a></dt>

579

<dd>Return value: New reference.Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> buffer s of the given size and return a Python

580

string object. encoding and errors have the same meaning as the parameters

581

of the same name in the Unicode <code class="xref py py-meth docutils literal">encode()</code> method. The codec

582

to be used is looked up using the Python codec registry. Return NULL if

583

an exception was raised by the codec.

584

585

586

changes in your code for properly supporting 64-bit systems.

587

</div>

588

</dd></dl>

589

590

591

592

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

593

<dd>Return value: New reference.Encode a Unicode object and return the result as Python string object.

594

encoding and errors have the same meaning as the parameters of the same name

595

in the Unicode <code class="xref py py-meth docutils literal">encode()</code> method. The codec to be used is looked up using

596

the Python codec registry. Return NULL if an exception was raised by the

597

codec.

598

</dd></dl>

599

600

</div>

601

602

<h3>UTF-8 Codecs<a class="headerlink" href="#utf-8-codecs" title="Permalink to this headline">¶</a></h3>

603

These are the UTF-8 codec APIs:

604

605

606

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

607

<dd>Return value: New reference.Create a Unicode object by decoding size bytes of the UTF-8 encoded string

608

s. Return NULL if an exception was raised by the codec.

609

610

611

changes in your code for properly supporting 64-bit systems.

612

</div>

613

</dd></dl>

614

615

616

617

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF8Stateful</code>(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)<a class="headerlink" href="#c.PyUnicode_DecodeUTF8Stateful" title="Permalink to this definition">¶</a></dt>

618

<dd>Return value: New reference.If consumed is NULL, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF8" title="PyUnicode_DecodeUTF8"><code class="xref c c-func docutils literal">PyUnicode_DecodeUTF8()</code></a>. If

619

consumed is not NULL, trailing incomplete UTF-8 byte sequences will not be

620

treated as an error. Those bytes will not be decoded and the number of bytes

621

that have been decoded will be stored in consumed.

622

623

New in version 2.4.

624

</div>

625

626

627

changes in your code for properly supporting 64-bit systems.

628

</div>

629

</dd></dl>

630

631

632

633

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeUTF8</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, const char *errors)<a class="headerlink" href="#c.PyUnicode_EncodeUTF8" title="Permalink to this definition">¶</a></dt>

634

635

Python string object. Return NULL if an exception was raised by the codec.

636

637

638

changes in your code for properly supporting 64-bit systems.

639

</div>

640

</dd></dl>

641

642

643

644

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

645

<dd>Return value: New reference.Encode a Unicode object using UTF-8 and return the result as Python string

646

object. Error handling is “strict”. Return NULL if an exception was raised

647

by the codec.

648

</dd></dl>

649

650

</div>

651

652

<h3>UTF-32 Codecs<a class="headerlink" href="#utf-32-codecs" title="Permalink to this headline">¶</a></h3>

653

These are the UTF-32 codec APIs:

654

655

656

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF32</code>(const char *s, Py_ssize_t size, const char *errors, int *byteorder)<a class="headerlink" href="#c.PyUnicode_DecodeUTF32" title="Permalink to this definition">¶</a></dt>

657

<dd>Decode size bytes from a UTF-32 encoded buffer string and return the

658

corresponding Unicode object. errors (if non-NULL) defines the error

659

handling. It defaults to “strict”.

660

If byteorder is non-NULL, the decoder starts decoding using the given byte

661

order:

662

<div class="highlight-c"><div class="highlight"><pre>*byteorder == -1: little endian

663

*byteorder == 0: native order

664

*byteorder == 1: big endian

665

</pre></div>

666

</div>

667

If <code class="docutils literal">*byteorder</code> is zero, and the first four bytes of the input data are a

668

byte order mark (BOM), the decoder switches to this byte order and the BOM is

669

not copied into the resulting Unicode string. If <code class="docutils literal">*byteorder</code> is <code class="docutils literal">-1</code> or

670

<code class="docutils literal">1</code>, any byte order mark is copied to the output.

671

After completion, *byteorder is set to the current byte order at the end

672

of input data.

673

In a narrow build code points outside the BMP will be decoded as surrogate pairs.

674

If byteorder is NULL, the codec starts in native order mode.

675

Return NULL if an exception was raised by the codec.

676

677

New in version 2.6.

678

</div>

679

</dd></dl>

680

681

682

683

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF32Stateful</code>(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)<a class="headerlink" href="#c.PyUnicode_DecodeUTF32Stateful" title="Permalink to this definition">¶</a></dt>

684

<dd>If consumed is NULL, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF32" title="PyUnicode_DecodeUTF32"><code class="xref c c-func docutils literal">PyUnicode_DecodeUTF32()</code></a>. If

685

consumed is not NULL, <a class="reference internal" href="#c.PyUnicode_DecodeUTF32Stateful" title="PyUnicode_DecodeUTF32Stateful"><code class="xref c c-func docutils literal">PyUnicode_DecodeUTF32Stateful()</code></a> will not treat

686

trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible

687

by four) as an error. Those bytes will not be decoded and the number of bytes

688

that have been decoded will be stored in consumed.

689

690

New in version 2.6.

691

</div>

692

</dd></dl>

693

694

695

696

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeUTF32</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, const char *errors, int byteorder)<a class="headerlink" href="#c.PyUnicode_EncodeUTF32" title="Permalink to this definition">¶</a></dt>

697

<dd>Return a Python bytes object holding the UTF-32 encoded value of the Unicode

698

data in s. Output is written according to the following byte order:

699

<div class="highlight-c"><div class="highlight"><pre>byteorder == -1: little endian

700

byteorder == 0: native byte order (writes a BOM mark)

701

byteorder == 1: big endian

702

</pre></div>

703

</div>

704

If byteorder is <code class="docutils literal">0</code>, the output string will always start with the Unicode BOM

705

mark (U+FEFF). In the other two modes, no BOM mark is prepended.

706

If Py_UNICODE_WIDE is not defined, surrogate pairs will be output

707

as a single code point.

708

Return NULL if an exception was raised by the codec.

709

710

New in version 2.6.

711

</div>

712

</dd></dl>

713

714

715

716

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

717

<dd>Return a Python string using the UTF-32 encoding in native byte order. The

718

string always starts with a BOM mark. Error handling is “strict”. Return

719

NULL if an exception was raised by the codec.

720

721

New in version 2.6.

722

</div>

723

</dd></dl>

724

725

</div>

726

727

<h3>UTF-16 Codecs<a class="headerlink" href="#utf-16-codecs" title="Permalink to this headline">¶</a></h3>

728

These are the UTF-16 codec APIs:

729

730

731

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF16</code>(const char *s, Py_ssize_t size, const char *errors, int *byteorder)<a class="headerlink" href="#c.PyUnicode_DecodeUTF16" title="Permalink to this definition">¶</a></dt>

732

<dd>Return value: New reference.Decode size bytes from a UTF-16 encoded buffer string and return the

733

corresponding Unicode object. errors (if non-NULL) defines the error

734

handling. It defaults to “strict”.

735

If byteorder is non-NULL, the decoder starts decoding using the given byte

736

order:

737

738

*byteorder == 0: native order

739

*byteorder == 1: big endian

740

</pre></div>

741

</div>

742

If <code class="docutils literal">*byteorder</code> is zero, and the first two bytes of the input data are a

743

byte order mark (BOM), the decoder switches to this byte order and the BOM is

744

not copied into the resulting Unicode string. If <code class="docutils literal">*byteorder</code> is <code class="docutils literal">-1</code> or

745

<code class="docutils literal">1</code>, any byte order mark is copied to the output (where it will result in

746

either a <code class="docutils literal">\ufeff</code> or a <code class="docutils literal">\ufffe</code> character).

747

After completion, *byteorder is set to the current byte order at the end

748

of input data.

749

If byteorder is NULL, the codec starts in native order mode.

750

Return NULL if an exception was raised by the codec.

751

752

753

changes in your code for properly supporting 64-bit systems.

754

</div>

755

</dd></dl>

756

757

758

759

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF16Stateful</code>(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)<a class="headerlink" href="#c.PyUnicode_DecodeUTF16Stateful" title="Permalink to this definition">¶</a></dt>

760

<dd>Return value: New reference.If consumed is NULL, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF16" title="PyUnicode_DecodeUTF16"><code class="xref c c-func docutils literal">PyUnicode_DecodeUTF16()</code></a>. If

761

consumed is not NULL, <a class="reference internal" href="#c.PyUnicode_DecodeUTF16Stateful" title="PyUnicode_DecodeUTF16Stateful"><code class="xref c c-func docutils literal">PyUnicode_DecodeUTF16Stateful()</code></a> will not treat

762

trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a

763

split surrogate pair) as an error. Those bytes will not be decoded and the

764

number of bytes that have been decoded will be stored in consumed.

765

766

New in version 2.4.

767

</div>

768

769

Changed in version 2.5: This function used an <code class="xref c c-type docutils literal">int</code> type for size and an <code class="xref c c-type docutils literal">int *</code>

770

type for consumed. This might require changes in your code for

771

properly supporting 64-bit systems.

772

</div>

773

</dd></dl>

774

775

776

777

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeUTF16</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, const char *errors, int byteorder)<a class="headerlink" href="#c.PyUnicode_EncodeUTF16" title="Permalink to this definition">¶</a></dt>

778

<dd>Return value: New reference.Return a Python string object holding the UTF-16 encoded value of the Unicode

779

data in s. Output is written according to the following byte order:

780

781

782

byteorder == 1: big endian

783

</pre></div>

784

</div>

785

If byteorder is <code class="docutils literal">0</code>, the output string will always start with the Unicode BOM

786

mark (U+FEFF). In the other two modes, no BOM mark is prepended.

787

If Py_UNICODE_WIDE is defined, a single <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> value may get

788

represented as a surrogate pair. If it is not defined, each <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a>

789

values is interpreted as an UCS-2 character.

790

Return NULL if an exception was raised by the codec.

791

792

793

changes in your code for properly supporting 64-bit systems.

794

</div>

795

</dd></dl>

796

797

798

799

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

800

<dd>Return value: New reference.Return a Python string using the UTF-16 encoding in native byte order. The

801

string always starts with a BOM mark. Error handling is “strict”. Return

802

NULL if an exception was raised by the codec.

803

</dd></dl>

804

805

</div>

806

807

<h3>UTF-7 Codecs<a class="headerlink" href="#utf-7-codecs" title="Permalink to this headline">¶</a></h3>

808

These are the UTF-7 codec APIs:

809

810

811

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

812

<dd>Create a Unicode object by decoding size bytes of the UTF-7 encoded string

813

s. Return NULL if an exception was raised by the codec.

814

</dd></dl>

815

816

817

818

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF7Stateful</code>(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)<a class="headerlink" href="#c.PyUnicode_DecodeUTF7Stateful" title="Permalink to this definition">¶</a></dt>

819

<dd>If consumed is NULL, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF7" title="PyUnicode_DecodeUTF7"><code class="xref c c-func docutils literal">PyUnicode_DecodeUTF7()</code></a>. If

820

consumed is not NULL, trailing incomplete UTF-7 base-64 sections will not

821

be treated as an error. Those bytes will not be decoded and the number of

822

bytes that have been decoded will be stored in consumed.

823

</dd></dl>

824

825

826

827

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeUTF7</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)<a class="headerlink" href="#c.PyUnicode_EncodeUTF7" title="Permalink to this definition">¶</a></dt>

828

<dd>Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> buffer of the given size using UTF-7 and

829

return a Python bytes object. Return NULL if an exception was raised by

830

the codec.

831

If base64SetO is nonzero, “Set O” (punctuation that has no otherwise

832

special meaning) will be encoded in base-64. If base64WhiteSpace is

833

nonzero, whitespace will be encoded in base-64. Both are set to zero for the

834

Python “utf-7” codec.

835

</dd></dl>

836

837

</div>

838

839

<h3>Unicode-Escape Codecs<a class="headerlink" href="#unicode-escape-codecs" title="Permalink to this headline">¶</a></h3>

840

These are the “Unicode Escape” codec APIs:

841

842

843

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

844

<dd>Return value: New reference.Create a Unicode object by decoding size bytes of the Unicode-Escape encoded

845

string s. Return NULL if an exception was raised by the codec.

846

847

848

changes in your code for properly supporting 64-bit systems.

849

</div>

850

</dd></dl>

851

852

853

854

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeUnicodeEscape</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size)<a class="headerlink" href="#c.PyUnicode_EncodeUnicodeEscape" title="Permalink to this definition">¶</a></dt>

855

<dd>Return value: New reference.Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> buffer of the given size using Unicode-Escape and

856

return a Python string object. Return NULL if an exception was raised by the

857

codec.

858

859

860

changes in your code for properly supporting 64-bit systems.

861

</div>

862

</dd></dl>

863

864

865

866

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

867

<dd>Return value: New reference.Encode a Unicode object using Unicode-Escape and return the result as Python

868

string object. Error handling is “strict”. Return NULL if an exception was

869

raised by the codec.

870

</dd></dl>

871

872

</div>

873

874

<h3>Raw-Unicode-Escape Codecs<a class="headerlink" href="#raw-unicode-escape-codecs" title="Permalink to this headline">¶</a></h3>

875

These are the “Raw Unicode Escape” codec APIs:

876

877

878

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

879

<dd>Return value: New reference.Create a Unicode object by decoding size bytes of the Raw-Unicode-Escape

880

encoded string s. Return NULL if an exception was raised by the codec.

881

882

883

changes in your code for properly supporting 64-bit systems.

884

</div>

885

</dd></dl>

886

887

888

889

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeRawUnicodeEscape</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, const char *errors)<a class="headerlink" href="#c.PyUnicode_EncodeRawUnicodeEscape" title="Permalink to this definition">¶</a></dt>

890

<dd>Return value: New reference.Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> buffer of the given size using Raw-Unicode-Escape

891

and return a Python string object. Return NULL if an exception was raised by

892

the codec.

893

894

895

changes in your code for properly supporting 64-bit systems.

896

</div>

897

</dd></dl>

898

899

900

901

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

902

<dd>Return value: New reference.Encode a Unicode object using Raw-Unicode-Escape and return the result as

903

Python string object. Error handling is “strict”. Return NULL if an exception

904

was raised by the codec.

905

</dd></dl>

906

907

</div>

908

909

<h3>Latin-1 Codecs<a class="headerlink" href="#latin-1-codecs" title="Permalink to this headline">¶</a></h3>

910

These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode

911

ordinals and only these are accepted by the codecs during encoding.

912

913

914

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

915

<dd>Return value: New reference.Create a Unicode object by decoding size bytes of the Latin-1 encoded string

916

s. Return NULL if an exception was raised by the codec.

917

918

919

changes in your code for properly supporting 64-bit systems.

920

</div>

921

</dd></dl>

922

923

924

925

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeLatin1</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, const char *errors)<a class="headerlink" href="#c.PyUnicode_EncodeLatin1" title="Permalink to this definition">¶</a></dt>

926

<dd>Return value: New reference.Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> buffer of the given size using Latin-1 and return

927

a Python string object. Return NULL if an exception was raised by the codec.

928

929

930

changes in your code for properly supporting 64-bit systems.

931

</div>

932

</dd></dl>

933

934

935

936

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

937

<dd>Return value: New reference.Encode a Unicode object using Latin-1 and return the result as Python string

938

object. Error handling is “strict”. Return NULL if an exception was raised

939

by the codec.

940

</dd></dl>

941

942

</div>

943

944

<h3>ASCII Codecs<a class="headerlink" href="#ascii-codecs" title="Permalink to this headline">¶</a></h3>

945

These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All other

946

codes generate errors.

947

948

949

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

950

<dd>Return value: New reference.Create a Unicode object by decoding size bytes of the ASCII encoded string

951

s. Return NULL if an exception was raised by the codec.

952

953

954

changes in your code for properly supporting 64-bit systems.

955

</div>

956

</dd></dl>

957

958

959

960

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeASCII</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, const char *errors)<a class="headerlink" href="#c.PyUnicode_EncodeASCII" title="Permalink to this definition">¶</a></dt>

961

<dd>Return value: New reference.Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> buffer of the given size using ASCII and return a

962

Python string object. Return NULL if an exception was raised by the codec.

963

964

965

changes in your code for properly supporting 64-bit systems.

966

</div>

967

</dd></dl>

968

969

970

971

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

972

<dd>Return value: New reference.Encode a Unicode object using ASCII and return the result as Python string

973

object. Error handling is “strict”. Return NULL if an exception was raised

974

by the codec.

975

</dd></dl>

976

977

</div>

978

979

<h3>Character Map Codecs<a class="headerlink" href="#character-map-codecs" title="Permalink to this headline">¶</a></h3>

980

This codec is special in that it can be used to implement many different codecs

981

(and this is in fact what was done to obtain most of the standard codecs

982

included in the <code class="xref py py-mod docutils literal">encodings</code> package). The codec uses mapping to encode and

983

decode characters.

984

Decoding mappings must map single string characters to single Unicode

985

characters, integers (which are then interpreted as Unicode ordinals) or None

986

(meaning “undefined mapping” and causing an error).

987

Encoding mappings must map single Unicode characters to single string

988

characters, integers (which are then interpreted as Latin-1 ordinals) or None

989

(meaning “undefined mapping” and causing an error).

990

The mapping objects provided must only support the __getitem__ mapping

991

interface.

992

If a character lookup fails with a LookupError, the character is copied as-is

993

meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal

994

resp. Because of this, mappings only need to contain those mappings which map

995

characters to different code points.

996

These are the mapping codec APIs:

997

998

999

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeCharmap</code>(const char *s, Py_ssize_t size, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *mapping, const char *errors)<a class="headerlink" href="#c.PyUnicode_DecodeCharmap" title="Permalink to this definition">¶</a></dt>

1000

<dd>Return value: New reference.Create a Unicode object by decoding size bytes of the encoded string s using

1001

the given mapping object. Return NULL if an exception was raised by the

1002

codec. If mapping is NULL latin-1 decoding will be done. Else it can be a

1003

dictionary mapping byte or a unicode string, which is treated as a lookup table.

1004

Byte values greater that the length of the string and U+FFFE “characters” are

1005

treated as “undefined mapping”.

1006

1007

Changed in version 2.4: Allowed unicode string as mapping argument.

1008

</div>

1009

1010

1011

changes in your code for properly supporting 64-bit systems.

1012

</div>

1013

</dd></dl>

1014

1015

1016

1017

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeCharmap</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *mapping, const char *errors)<a class="headerlink" href="#c.PyUnicode_EncodeCharmap" title="Permalink to this definition">¶</a></dt>

1018

1019

mapping object and return a Python string object. Return NULL if an

1020

exception was raised by the codec.

1021

1022

1023

changes in your code for properly supporting 64-bit systems.

1024

</div>

1025

</dd></dl>

1026

1027

1028

1029

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

1030

<dd>Return value: New reference.Encode a Unicode object using the given mapping object and return the result

1031

as Python string object. Error handling is “strict”. Return NULL if an

1032

exception was raised by the codec.

1033

</dd></dl>

1034

1035

The following codec API is special in that maps Unicode to Unicode.

1036

1037

1038

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_TranslateCharmap</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *table, const char *errors)<a class="headerlink" href="#c.PyUnicode_TranslateCharmap" title="Permalink to this definition">¶</a></dt>

1039

<dd>Return value: New reference.Translate a <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal">Py_UNICODE</code></a> buffer of the given size by applying a

1040

character mapping table to it and return the resulting Unicode object. Return

1041

NULL when an exception was raised by the codec.

1042

The mapping table must map Unicode ordinal integers to Unicode ordinal

1043

integers or None (causing deletion of the character).

1044

Mapping tables need only provide the <a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a> interface; dictionaries

1045

and sequences work well. Unmapped character ordinals (ones which cause a

1046

<a class="reference internal" href="../library/exceptions.html#exceptions.LookupError" title="exceptions.LookupError"><code class="xref py py-exc docutils literal">LookupError</code></a>) are left untouched and are copied as-is.

1047

1048

1049

changes in your code for properly supporting 64-bit systems.

1050

</div>

1051

</dd></dl>

1052

1053

</div>

1054

1055

<h3>MBCS codecs for Windows<a class="headerlink" href="#mbcs-codecs-for-windows" title="Permalink to this headline">¶</a></h3>

1056

These are the MBCS codec APIs. They are currently only available on Windows and

1057

use the Win32 MBCS converters to implement the conversions. Note that MBCS (or

1058

DBCS) is a class of encodings, not just one. The target encoding is defined by

1059

the user settings on the machine running the codec.

1060

1061

1062

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

1063

<dd>Return value: New reference.Create a Unicode object by decoding size bytes of the MBCS encoded string s.

1064

Return NULL if an exception was raised by the codec.

1065

1066

1067

changes in your code for properly supporting 64-bit systems.

1068

</div>

1069

</dd></dl>

1070

1071

1072

1073

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeMBCSStateful</code>(const char *s, int size, const char *errors, int *consumed)<a class="headerlink" href="#c.PyUnicode_DecodeMBCSStateful" title="Permalink to this definition">¶</a></dt>

1074

<dd>If consumed is NULL, behave like <a class="reference internal" href="#c.PyUnicode_DecodeMBCS" title="PyUnicode_DecodeMBCS"><code class="xref c c-func docutils literal">PyUnicode_DecodeMBCS()</code></a>. If

1075

consumed is not NULL, <a class="reference internal" href="#c.PyUnicode_DecodeMBCSStateful" title="PyUnicode_DecodeMBCSStateful"><code class="xref c c-func docutils literal">PyUnicode_DecodeMBCSStateful()</code></a> will not decode

1076

trailing lead byte and the number of bytes that have been decoded will be stored

1077

in consumed.

1078

1079

New in version 2.5.

1080

</div>

1081

</dd></dl>

1082

1083

1084

1085

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeMBCS</code>(const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> *s, Py_ssize_t size, const char *errors)<a class="headerlink" href="#c.PyUnicode_EncodeMBCS" title="Permalink to this definition">¶</a></dt>

1086

1087

Python string object. Return NULL if an exception was raised by the codec.

1088

1089

1090

changes in your code for properly supporting 64-bit systems.

1091

</div>

1092

</dd></dl>

1093

1094

1095

1096

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

1097

<dd>Return value: New reference.Encode a Unicode object using MBCS and return the result as Python string

1098

object. Error handling is “strict”. Return NULL if an exception was raised

1099

by the codec.

1100

</dd></dl>

1101

1102

</div>

1103

1104

<h3>Methods & Slots<a class="headerlink" href="#methods-slots" title="Permalink to this headline">¶</a></h3>

1105

</div>

1106

</div>

1107

1108

<h2>Methods and Slot Functions<a class="headerlink" href="#methods-and-slot-functions" title="Permalink to this headline">¶</a></h2>

1109

The following APIs are capable of handling Unicode objects and strings on input

1110

(we refer to them as strings in the descriptions) and return Unicode objects or

1111

integers as appropriate.

1112

They all return NULL or <code class="docutils literal">-1</code> if an exception occurs.

1113

1114

1115

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

1116

<dd>Return value: New reference.Concat two strings giving a new Unicode string.

1117

</dd></dl>

1118

1119

1120

1121

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

1122

<dd>Return value: New reference.Split a string giving a list of Unicode strings. If sep is NULL, splitting

1123

will be done at all whitespace substrings. Otherwise, splits occur at the given

1124

separator. At most maxsplit splits will be done. If negative, no limit is

1125

set. Separators are not included in the resulting list.

1126

1127

1128

changes in your code for properly supporting 64-bit systems.

1129

</div>

1130

</dd></dl>

1131

1132

1133

1134

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

1135

<dd>Return value: New reference.Split a Unicode string at line breaks, returning a list of Unicode strings.

1136

CRLF is considered to be one line break. If keepend is 0, the Line break

1137

characters are not included in the resulting strings.

1138

</dd></dl>

1139

1140

1141

1142

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

1143

<dd>Return value: New reference.Translate a string by applying a character mapping table to it and return the

1144

resulting Unicode object.

1145

The mapping table must map Unicode ordinal integers to Unicode ordinal integers

1146

or None (causing deletion of the character).

1147

1148

and sequences work well. Unmapped character ordinals (ones which cause a

1149

1150

errors has the usual meaning for codecs. It may be NULL which indicates to

1151

use the default error handling.

1152

</dd></dl>

1153

1154

1155

1156

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

1157

<dd>Return value: New reference.Join a sequence of strings using the given separator and return the resulting

1158

Unicode string.

1159

</dd></dl>

1160

1161

1162

1163

Py_ssize_t <code class="descname">PyUnicode_Tailmatch</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *str, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *substr, Py_ssize_t start, Py_ssize_t end, int direction)<a class="headerlink" href="#c.PyUnicode_Tailmatch" title="Permalink to this definition">¶</a></dt>

1164

<dd>Return 1 if substr matches <code class="docutils literal">str[start:end]</code> at the given tail end

1165

(direction == -1 means to do a prefix match, direction == 1 a suffix match),

1166

0 otherwise. Return <code class="docutils literal">-1</code> if an error occurred.

1167

1168

1169

might require changes in your code for properly supporting 64-bit

1170

systems.

1171

</div>

1172

</dd></dl>

1173

1174

1175

1176

Py_ssize_t <code class="descname">PyUnicode_Find</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *str, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *substr, Py_ssize_t start, Py_ssize_t end, int direction)<a class="headerlink" href="#c.PyUnicode_Find" title="Permalink to this definition">¶</a></dt>

1177

<dd>Return the first position of substr in <code class="docutils literal">str[start:end]</code> using the given

1178

direction (direction == 1 means to do a forward search, direction == -1 a

1179

backward search). The return value is the index of the first match; a value of

1180

<code class="docutils literal">-1</code> indicates that no match was found, and <code class="docutils literal">-2</code> indicates that an error

1181

occurred and an exception has been set.

1182

1183

1184

might require changes in your code for properly supporting 64-bit

1185

systems.

1186

</div>

1187

</dd></dl>

1188

1189

1190

1191

Py_ssize_t <code class="descname">PyUnicode_Count</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *str, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *substr, Py_ssize_t start, Py_ssize_t end)<a class="headerlink" href="#c.PyUnicode_Count" title="Permalink to this definition">¶</a></dt>

1192

<dd>Return the number of non-overlapping occurrences of substr in

1193

<code class="docutils literal">str[start:end]</code>. Return <code class="docutils literal">-1</code> if an error occurred.

1194

1195

1196

type for start and end. This might require changes in your code for

1197

properly supporting 64-bit systems.

1198

</div>

1199

</dd></dl>

1200

1201

1202

1203

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Replace</code>(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *str, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *substr, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *replstr, Py_ssize_t maxcount)<a class="headerlink" href="#c.PyUnicode_Replace" title="Permalink to this definition">¶</a></dt>

1204

<dd>Return value: New reference.Replace at most maxcount occurrences of substr in str with replstr and

1205

return the resulting Unicode object. maxcount == -1 means replace all

1206

occurrences.

1207

1208

1209

require changes in your code for properly supporting 64-bit systems.

1210

</div>

1211

</dd></dl>

1212

1213

1214

1215

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

1216

<dd>Compare two strings and return -1, 0, 1 for less than, equal, and greater than,

1217

respectively.

1218

</dd></dl>

1219

1220

1221

1222

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

1223

<dd>Rich compare two unicode strings and return one of the following:

1224

1225

<li><code class="docutils literal">NULL</code> in case an exception was raised</li>

1226

<li><code class="xref py py-const docutils literal">Py_True</code> or <code class="xref py py-const docutils literal">Py_False</code> for successful comparisons</li>

1227

<li><code class="xref py py-const docutils literal">Py_NotImplemented</code> in case the type combination is unknown</li>

1228

</ul>

1229

Note that <code class="xref py py-const docutils literal">Py_EQ</code> and <code class="xref py py-const docutils literal">Py_NE</code> comparisons can cause a

1230

<a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeWarning" title="exceptions.UnicodeWarning"><code class="xref py py-exc docutils literal">UnicodeWarning</code></a> in case the conversion of the arguments to Unicode fails

1231

with a <a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeDecodeError" title="exceptions.UnicodeDecodeError"><code class="xref py py-exc docutils literal">UnicodeDecodeError</code></a>.

1232

Possible values for op are <code class="xref py py-const docutils literal">Py_GT</code>, <code class="xref py py-const docutils literal">Py_GE</code>, <code class="xref py py-const docutils literal">Py_EQ</code>,

1233

<code class="xref py py-const docutils literal">Py_NE</code>, <code class="xref py py-const docutils literal">Py_LT</code>, and <code class="xref py py-const docutils literal">Py_LE</code>.

1234

</dd></dl>

1235

1236

1237

1238

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

1239

<dd>Return value: New reference.Return a new string object from format and args; this is analogous to

1240

<code class="docutils literal">format % args</code>.

1241

</dd></dl>

1242

1243

1244

1245

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

1246

<dd>Check whether element is contained in container and return true or false

1247

accordingly.

1248

element has to coerce to a one element Unicode string. <code class="docutils literal">-1</code> is returned if

1249

there was an error.

1250

</dd></dl>

1251

1252

</div>

1253

</div>

1254

1255

1256

</div>

1257

</div>

1258

</div>

1259

1260

1261

<h3><a href="../contents.html">Table Of Contents</a></h3>

1262

<ul>

1263

<li><a class="reference internal" href="#">Unicode Objects and Codecs</a><ul>

1264

<li><a class="reference internal" href="#unicode-objects">Unicode Objects</a><ul>

1265

<li><a class="reference internal" href="#unicode-type">Unicode Type</a></li>

1266

<li><a class="reference internal" href="#unicode-character-properties">Unicode Character Properties</a></li>

1267

<li><a class="reference internal" href="#plain-py-unicode">Plain Py_UNICODE</a></li>

1268

<li><a class="reference internal" href="#wchar-t-support">wchar_t Support</a></li>

1269

</ul>

1270

</li>

1271

<li><a class="reference internal" href="#built-in-codecs">Built-in Codecs</a><ul>

1272

<li><a class="reference internal" href="#generic-codecs">Generic Codecs</a></li>

1273

<li><a class="reference internal" href="#utf-8-codecs">UTF-8 Codecs</a></li>

1274

<li><a class="reference internal" href="#utf-32-codecs">UTF-32 Codecs</a></li>

1275

<li><a class="reference internal" href="#utf-16-codecs">UTF-16 Codecs</a></li>

1276

<li><a class="reference internal" href="#utf-7-codecs">UTF-7 Codecs</a></li>

1277

<li><a class="reference internal" href="#unicode-escape-codecs">Unicode-Escape Codecs</a></li>

1278

<li><a class="reference internal" href="#raw-unicode-escape-codecs">Raw-Unicode-Escape Codecs</a></li>

1279

<li><a class="reference internal" href="#latin-1-codecs">Latin-1 Codecs</a></li>

1280

<li><a class="reference internal" href="#ascii-codecs">ASCII Codecs</a></li>

1281

<li><a class="reference internal" href="#character-map-codecs">Character Map Codecs</a></li>

1282

<li><a class="reference internal" href="#mbcs-codecs-for-windows">MBCS codecs for Windows</a></li>

1283

<li><a class="reference internal" href="#methods-slots">Methods & Slots</a></li>

1284

</ul>

1285

</li>

1286

<li><a class="reference internal" href="#methods-and-slot-functions">Methods and Slot Functions</a></li>

1287

</ul>

1288

</li>

1289

</ul>

1290

1291

<h4>Previous topic</h4>

1292

<a href="string.html"

1293

title="previous chapter">String/Bytes Objects</a>

1294

<h4>Next topic</h4>

1295

<a href="buffer.html"

1296

title="next chapter">Buffers and Memoryview Objects</a>

1297

1298

1299

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

1300

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

1301

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

1302

</ul>

1303

1304

1305

<h3>Quick search</h3>

1306

1307

1308

1309

1310

1311

</form>

1312

1313

Enter search terms or a module, class or function name.

1314

1315

</div>

1316

1317

</div>

1318

</div>

1319

1320

</div>

1321

1322

<h3>Navigation</h3>

1323

<ul>

1324

1325

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

1326

>index</a></li>

1327

1328

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

1329

>modules</a> |</li>

1330

1331

<a href="buffer.html" title="Buffers and Memoryview Objects"

1332

>next</a> |</li>

1333

1334

<a href="string.html" title="String/Bytes Objects"

1335

>previous</a> |</li>

1336

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

1337

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

1338

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

1339

<li>

1340

2.7.11

1341

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

1342

</li>

1343

1344

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

1345

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

1346

</ul>

1347

</div>

1348

1349

1350

1351

The Python Software Foundation is a non-profit corporation.

1352

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

1353

1354

Last updated on Jan 23, 2016.

1355

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

1356

1357

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

1358

</div>

1359

1360

</body>

1361

</html>

b'\\ No newline at end of file'

Older »