~ubuntu-branches/ubuntu/maverick/eglibc/maverick-security

<tr><td align="left" valign="top"><a href="#Classification-of-Characters">4.1 Classification of Characters</a></td><td>  </td><td align="left" valign="top"> Testing whether characters are

105

letters, digits, punctuation, etc.

106

</td></tr>

107

<tr><td align="left" valign="top"><a href="#Case-Conversion">4.2 Case Conversion</a></td><td>  </td><td align="left" valign="top"> Case mapping, and the like.

108

</td></tr>

109

<tr><td align="left" valign="top"><a href="#Classification-of-Wide-Characters">4.3 Character class determination for wide characters</a></td><td>  </td><td align="left" valign="top"></td></tr>

110

<tr><td align="left" valign="top"><a href="#Using-Wide-Char-Classes">4.4 Notes on using the wide character classes</a></td><td>  </td><td align="left" valign="top"></td></tr>

111

<tr><td align="left" valign="top"><a href="#Wide-Character-Case-Conversion">4.5 Mapping of wide characters.</a></td><td>  </td><td align="left" valign="top"></td></tr>

112

</table>

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

129

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

130

131

</tr></table>

132

133

<h2 class="section">4.1 Classification of Characters</h2>

134

135

136

137

138

139

This section explains the library functions for classifying characters.

140

For example, <code>isalpha</code> is the function to test for an alphabetic

141

character. It takes one argument, the character to test, and returns a

142

nonzero integer if the character is alphabetic, and zero otherwise. You

143

would use it like this:

144

145

<table><tr><td> </td><td><pre class="smallexample">if (isalpha (c))

146

printf ("The character `%c' is alphabetic.\n", c);

147

</pre></td></tr></table>

148

149

Each of the functions in this section tests for membership in a

150

particular class of characters; each has a name starting with ‘<samp>is</samp>’.

151

Each of them takes one argument, which is a character to test, and

152

returns an <code>int</code> which is treated as a boolean value. The

153

character argument is passed as an <code>int</code>, and it may be the

154

constant value <code>EOF</code> instead of a real character.

155

156

The attributes of any given character can vary between locales.

157

See section <a href="libc_7.html#Locales">Locales and Internationalization</a>, for more information on locales.

158

159

These functions are declared in the header file ‘<tt>ctype.h</tt>’.

160

161

162

163

<dl>

164

<dt><a name="index-islower"></a>Function: int islower (int <var>c</var>)</dt>

165

<dd>Returns true if <var>c</var> is a lower-case letter. The letter need not be

166

from the Latin alphabet, any alphabet representable is valid.

167

</dd></dl>

168

169

170

<dl>

171

<dt><a name="index-isupper"></a>Function: int isupper (int <var>c</var>)</dt>

172

<dd>Returns true if <var>c</var> is an upper-case letter. The letter need not be

173

from the Latin alphabet, any alphabet representable is valid.

174

</dd></dl>

175

176

177

<dl>

178

<dt><a name="index-isalpha"></a>Function: int isalpha (int <var>c</var>)</dt>

179

<dd>Returns true if <var>c</var> is an alphabetic character (a letter). If

180

<code>islower</code> or <code>isupper</code> is true of a character, then

181

<code>isalpha</code> is also true.

182

183

In some locales, there may be additional characters for which

184

<code>isalpha</code> is true—letters which are neither upper case nor lower

185

case. But in the standard <code>"C"</code> locale, there are no such

186

additional characters.

187

</dd></dl>

188

189

190

191

<dl>

192

<dt><a name="index-isdigit"></a>Function: int isdigit (int <var>c</var>)</dt>

193

<dd>Returns true if <var>c</var> is a decimal digit (‘<samp>0</samp>’ through ‘<samp>9</samp>’).

194

</dd></dl>

195

196

197

<dl>

198

<dt><a name="index-isalnum"></a>Function: int isalnum (int <var>c</var>)</dt>

199

<dd>Returns true if <var>c</var> is an alphanumeric character (a letter or

200

number); in other words, if either <code>isalpha</code> or <code>isdigit</code> is

201

true of a character, then <code>isalnum</code> is also true.

202

</dd></dl>

203

204

205

<dl>

206

<dt><a name="index-isxdigit"></a>Function: int isxdigit (int <var>c</var>)</dt>

207

<dd>Returns true if <var>c</var> is a hexadecimal digit.

208

Hexadecimal digits include the normal decimal digits ‘<samp>0</samp>’ through

209

‘<samp>9</samp>’ and the letters ‘<samp>A</samp>’ through ‘<samp>F</samp>’ and

210

‘<samp>a</samp>’ through ‘<samp>f</samp>’.

211

</dd></dl>

212

213

214

<dl>

215

<dt><a name="index-ispunct"></a>Function: int ispunct (int <var>c</var>)</dt>

216

<dd>Returns true if <var>c</var> is a punctuation character.

217

This means any printing character that is not alphanumeric or a space

218

character.

219

</dd></dl>

220

221

222

<dl>

223

<dt><a name="index-isspace"></a>Function: int isspace (int <var>c</var>)</dt>

224

<dd>Returns true if <var>c</var> is a whitespace character. In the standard

225

<code>"C"</code> locale, <code>isspace</code> returns true for only the standard

226

whitespace characters:

227

228

229

230

<dd>space

231

232

</dd>

233

234

<dd>formfeed

235

236

</dd>

237

238

<dd>newline

239

240

</dd>

241

242

<dd>carriage return

243

244

</dd>

245

246

<dd>horizontal tab

247

248

</dd>

249

250

<dd>vertical tab

251

</dd>

252

</dl>

253

</dd></dl>

254

255

256

<dl>

257

<dt><a name="index-isblank"></a>Function: int isblank (int <var>c</var>)</dt>

258

<dd>Returns true if <var>c</var> is a blank character; that is, a space or a tab.

259

This function was originally a GNU extension, but was added in ISO C99.

260

</dd></dl>

261

262

263

<dl>

264

<dt><a name="index-isgraph"></a>Function: int isgraph (int <var>c</var>)</dt>

265

<dd>Returns true if <var>c</var> is a graphic character; that is, a character

266

that has a glyph associated with it. The whitespace characters are not

267

considered graphic.

268

</dd></dl>

269

270

271

<dl>

272

<dt><a name="index-isprint"></a>Function: int isprint (int <var>c</var>)</dt>

273

<dd>Returns true if <var>c</var> is a printing character. Printing characters

274

include all the graphic characters, plus the space (‘<samp> </samp>’) character.

275

</dd></dl>

276

277

278

<dl>

279

<dt><a name="index-iscntrl"></a>Function: int iscntrl (int <var>c</var>)</dt>

280

<dd>Returns true if <var>c</var> is a control character (that is, a character that

281

is not a printing character).

282

</dd></dl>

283

284

285

<dl>

286

<dt><a name="index-isascii"></a>Function: int isascii (int <var>c</var>)</dt>

287

<dd>Returns true if <var>c</var> is a 7-bit <code>unsigned char</code> value that fits

288

into the US/UK ASCII character set. This function is a BSD extension

289

and is also an SVID extension.

290

</dd></dl>

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

307

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

308

309

</tr></table>

310

311

<h2 class="section">4.2 Case Conversion</h2>

312

313

314

315

316

This section explains the library functions for performing conversions

317

such as case mappings on characters. For example, <code>toupper</code>

318

converts any character to upper case if possible. If the character

319

can’t be converted, <code>toupper</code> returns it unchanged.

320

321

These functions take one argument of type <code>int</code>, which is the

322

character to convert, and return the converted character as an

323

<code>int</code>. If the conversion is not applicable to the argument given,

324

the argument is returned unchanged.

325

326

Compatibility Note: In pre-ISO C dialects, instead of

327

returning the argument unchanged, these functions may fail when the

328

argument is not suitable for the conversion. Thus for portability, you

329

may need to write <code>islower(c) ? toupper(c) : c</code> rather than just

330

<code>toupper(c)</code>.

331

332

These functions are declared in the header file ‘<tt>ctype.h</tt>’.

333

334

335

<dl>

336

<dt><a name="index-tolower"></a>Function: int tolower (int <var>c</var>)</dt>

337

<dd>If <var>c</var> is an upper-case letter, <code>tolower</code> returns the corresponding

338

lower-case letter. If <var>c</var> is not an upper-case letter,

339

<var>c</var> is returned unchanged.

340

</dd></dl>

341

342

<dl>

343

<dt><a name="index-toupper"></a>Function: int toupper (int <var>c</var>)</dt>

344

<dd>If <var>c</var> is a lower-case letter, <code>toupper</code> returns the corresponding

345

upper-case letter. Otherwise <var>c</var> is returned unchanged.

346

</dd></dl>

347

348

<dl>

349

<dt><a name="index-toascii"></a>Function: int toascii (int <var>c</var>)</dt>

350

<dd>This function converts <var>c</var> to a 7-bit <code>unsigned char</code> value

351

that fits into the US/UK ASCII character set, by clearing the high-order

352

bits. This function is a BSD extension and is also an SVID extension.

353

</dd></dl>

354

355

<dl>

356

<dt><a name="index-_005ftolower"></a>Function: int _tolower (int <var>c</var>)</dt>

357

<dd>This is identical to <code>tolower</code>, and is provided for compatibility

358

with the SVID. See section <a href="libc_1.html#SVID">SVID (The System V Interface Description)</a>.

359

</dd></dl>

360

361

<dl>

362

<dt><a name="index-_005ftoupper"></a>Function: int _toupper (int <var>c</var>)</dt>

363

<dd>This is identical to <code>toupper</code>, and is provided for compatibility

364

with the SVID.

365

</dd></dl>

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

383

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

384

385

</tr></table>

386

387

<h2 class="section">4.3 Character class determination for wide characters</h2>

388

389

Amendment 1 to ISO C90 defines functions to classify wide

390

characters. Although the original ISO C90 standard already defined

391

the type <code>wchar_t</code>, no functions operating on them were defined.

392

393

The general design of the classification functions for wide characters

394

is more general. It allows extensions to the set of available

395

classifications, beyond those which are always available. The POSIX

396

standard specifies how extensions can be made, and this is already

397

implemented in the GNU C library implementation of the <code>localedef</code>

398

program.

399

400

The character class functions are normally implemented with bitsets,

401

with a bitset per character. For a given character, the appropriate

402

bitset is read from a table and a test is performed as to whether a

403

certain bit is set. Which bit is tested for is determined by the

404

class.

405

406

For the wide character classification functions this is made visible.

407

There is a type classification type defined, a function to retrieve this

408

value for a given class, and a function to test whether a given

409

character is in this class, using the classification value. On top of

410

this the normal character classification functions as used for

411

<code>char</code> objects can be defined.

412

413

<dl>

414

<dt><a name="index-wctype_005ft"></a>Data type: wctype_t</dt>

415

<dd>The <code>wctype_t</code> can hold a value which represents a character class.

416

The only defined way to generate such a value is by using the

417

<code>wctype</code> function.

418

419

420

This type is defined in ‘<tt>wctype.h</tt>’.

421

</dd></dl>

422

423

<dl>

424

<dt><a name="index-wctype"></a>Function: wctype_t wctype (const char *<var>property</var>)</dt>

425

<dd>The <code>wctype</code> returns a value representing a class of wide

426

characters which is identified by the string <var>property</var>. Beside

427

some standard properties each locale can define its own ones. In case

428

no property with the given name is known for the current locale

429

selected for the <code>LC_CTYPE</code> category, the function returns zero.

430

431

The properties known in every locale are:

432

433

<table>

434

<tr><td width="25%"><code>"alnum"</code></td><td width="25%"><code>"alpha"</code></td><td width="25%"><code>"cntrl"</code></td><td width="25%"><code>"digit"</code></td></tr>

435

<tr><td width="25%"><code>"graph"</code></td><td width="25%"><code>"lower"</code></td><td width="25%"><code>"print"</code></td><td width="25%"><code>"punct"</code></td></tr>

436

<tr><td width="25%"><code>"space"</code></td><td width="25%"><code>"upper"</code></td><td width="25%"><code>"xdigit"</code></td></tr>

437

</table>

438

439

440

This function is declared in ‘<tt>wctype.h</tt>’.

441

</dd></dl>

442

443

To test the membership of a character to one of the non-standard classes

444

the ISO C standard defines a completely new function.

445

446

<dl>

447

<dt><a name="index-iswctype"></a>Function: int iswctype (wint_t <var>wc</var>, wctype_t <var>desc</var>)</dt>

448

<dd>This function returns a nonzero value if <var>wc</var> is in the character

449

class specified by <var>desc</var>. <var>desc</var> must previously be returned

450

by a successful call to <code>wctype</code>.

451

452

453

This function is declared in ‘<tt>wctype.h</tt>’.

454

</dd></dl>

455

456

To make it easier to use the commonly-used classification functions,

457

they are defined in the C library. There is no need to use

458

<code>wctype</code> if the property string is one of the known character

459

classes. In some situations it is desirable to construct the property

460

strings, and then it is important that <code>wctype</code> can also handle the

461

standard classes.

462

463

464

<dl>

465

<dt><a name="index-iswalnum"></a>Function: int iswalnum (wint_t <var>wc</var>)</dt>

466

<dd>This function returns a nonzero value if <var>wc</var> is an alphanumeric

467

character (a letter or number); in other words, if either <code>iswalpha</code>

468

or <code>iswdigit</code> is true of a character, then <code>iswalnum</code> is also

469

true.

470

471

This function can be implemented using

472

473

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("alnum"))

474

</pre></td></tr></table>

475

476

477

It is declared in ‘<tt>wctype.h</tt>’.

478

</dd></dl>

479

480

481

<dl>

482

<dt><a name="index-iswalpha"></a>Function: int iswalpha (wint_t <var>wc</var>)</dt>

483

<dd>Returns true if <var>wc</var> is an alphabetic character (a letter). If

484

<code>iswlower</code> or <code>iswupper</code> is true of a character, then

485

<code>iswalpha</code> is also true.

486

487

In some locales, there may be additional characters for which

488

<code>iswalpha</code> is true—letters which are neither upper case nor lower

489

case. But in the standard <code>"C"</code> locale, there are no such

490

additional characters.

491

492

This function can be implemented using

493

494

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("alpha"))

495

</pre></td></tr></table>

496

497

498

It is declared in ‘<tt>wctype.h</tt>’.

499

</dd></dl>

500

501

502

<dl>

503

<dt><a name="index-iswcntrl"></a>Function: int iswcntrl (wint_t <var>wc</var>)</dt>

504

<dd>Returns true if <var>wc</var> is a control character (that is, a character that

505

is not a printing character).

506

507

This function can be implemented using

508

509

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("cntrl"))

510

</pre></td></tr></table>

511

512

513

It is declared in ‘<tt>wctype.h</tt>’.

514

</dd></dl>

515

516

517

<dl>

518

<dt><a name="index-iswdigit"></a>Function: int iswdigit (wint_t <var>wc</var>)</dt>

519

<dd>Returns true if <var>wc</var> is a digit (e.g., ‘<samp>0</samp>’ through ‘<samp>9</samp>’).

520

Please note that this function does not only return a nonzero value for

521

decimal digits, but for all kinds of digits. A consequence is

522

that code like the following will not work unconditionally for

523

wide characters:

524

525

<table><tr><td> </td><td><pre class="smallexample">n = 0;

526

while (iswdigit (*wc))

527

{

528

n *= 10;

529

n += *wc++ - L'0';

530

}

531

</pre></td></tr></table>

532

533

This function can be implemented using

534

535

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("digit"))

536

</pre></td></tr></table>

537

538

539

It is declared in ‘<tt>wctype.h</tt>’.

540

</dd></dl>

541

542

543

<dl>

544

<dt><a name="index-iswgraph"></a>Function: int iswgraph (wint_t <var>wc</var>)</dt>

545

<dd>Returns true if <var>wc</var> is a graphic character; that is, a character

546

that has a glyph associated with it. The whitespace characters are not

547

considered graphic.

548

549

This function can be implemented using

550

551

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("graph"))

552

</pre></td></tr></table>

553

554

555

It is declared in ‘<tt>wctype.h</tt>’.

556

</dd></dl>

557

558

559

<dl>

560

<dt><a name="index-iswlower"></a>Function: int iswlower (wint_t <var>wc</var>)</dt>

561

<dd>Returns true if <var>wc</var> is a lower-case letter. The letter need not be

562

from the Latin alphabet, any alphabet representable is valid.

563

564

This function can be implemented using

565

566

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("lower"))

567

</pre></td></tr></table>

568

569

570

It is declared in ‘<tt>wctype.h</tt>’.

571

</dd></dl>

572

573

574

<dl>

575

<dt><a name="index-iswprint"></a>Function: int iswprint (wint_t <var>wc</var>)</dt>

576

<dd>Returns true if <var>wc</var> is a printing character. Printing characters

577

include all the graphic characters, plus the space (‘<samp> </samp>’) character.

578

579

This function can be implemented using

580

581

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("print"))

582

</pre></td></tr></table>

583

584

585

It is declared in ‘<tt>wctype.h</tt>’.

586

</dd></dl>

587

588

589

<dl>

590

<dt><a name="index-iswpunct"></a>Function: int iswpunct (wint_t <var>wc</var>)</dt>

591

<dd>Returns true if <var>wc</var> is a punctuation character.

592

This means any printing character that is not alphanumeric or a space

593

character.

594

595

This function can be implemented using

596

597

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("punct"))

598

</pre></td></tr></table>

599

600

601

It is declared in ‘<tt>wctype.h</tt>’.

602

</dd></dl>

603

604

605

<dl>

606

<dt><a name="index-iswspace"></a>Function: int iswspace (wint_t <var>wc</var>)</dt>

607

<dd>Returns true if <var>wc</var> is a whitespace character. In the standard

608

<code>"C"</code> locale, <code>iswspace</code> returns true for only the standard

609

whitespace characters:

610

611

612

613

<dd>space

614

615

</dd>

616

617

<dd>formfeed

618

619

</dd>

620

621

<dd>newline

622

623

</dd>

624

625

<dd>carriage return

626

627

</dd>

628

629

<dd>horizontal tab

630

631

</dd>

632

633

<dd>vertical tab

634

</dd>

635

</dl>

636

637

This function can be implemented using

638

639

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("space"))

640

</pre></td></tr></table>

641

642

643

It is declared in ‘<tt>wctype.h</tt>’.

644

</dd></dl>

645

646

647

<dl>

648

<dt><a name="index-iswupper"></a>Function: int iswupper (wint_t <var>wc</var>)</dt>

649

<dd>Returns true if <var>wc</var> is an upper-case letter. The letter need not be

650

from the Latin alphabet, any alphabet representable is valid.

651

652

This function can be implemented using

653

654

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("upper"))

655

</pre></td></tr></table>

656

657

658

It is declared in ‘<tt>wctype.h</tt>’.

659

</dd></dl>

660

661

662

<dl>

663

<dt><a name="index-iswxdigit"></a>Function: int iswxdigit (wint_t <var>wc</var>)</dt>

664

<dd>Returns true if <var>wc</var> is a hexadecimal digit.

665

Hexadecimal digits include the normal decimal digits ‘<samp>0</samp>’ through

666

‘<samp>9</samp>’ and the letters ‘<samp>A</samp>’ through ‘<samp>F</samp>’ and

667

‘<samp>a</samp>’ through ‘<samp>f</samp>’.

668

669

This function can be implemented using

670

671

<table><tr><td> </td><td><pre class="smallexample">iswctype (wc, wctype ("xdigit"))

672

</pre></td></tr></table>

673

674

675

It is declared in ‘<tt>wctype.h</tt>’.

676

</dd></dl>

677

678

The GNU C library also provides a function which is not defined in the

679

ISO C standard but which is available as a version for single byte

680

characters as well.

681

682

683

<dl>

684

<dt><a name="index-iswblank"></a>Function: int iswblank (wint_t <var>wc</var>)</dt>

685

<dd>Returns true if <var>wc</var> is a blank character; that is, a space or a tab.

686

This function was originally a GNU extension, but was added in ISO C99.

687

It is declared in ‘<tt>wchar.h</tt>’.

688

</dd></dl>

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

705

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

706

707

</tr></table>

708

709

<h2 class="section">4.4 Notes on using the wide character classes</h2>

710

711

The first note is probably not astonishing but still occasionally a

712

cause of problems. The <code>isw<var>XXX</var></code> functions can be implemented

713

using macros and in fact, the GNU C library does this. They are still

714

available as real functions but when the ‘<tt>wctype.h</tt>’ header is

715

included the macros will be used. This is the same as the

716

<code>char</code> type versions of these functions.

717

718

The second note covers something new. It can be best illustrated by a

719

(real-world) example. The first piece of code is an excerpt from the

720

original code. It is truncated a bit but the intention should be clear.

721

722

<table><tr><td> </td><td><pre class="smallexample">int

723

is_in_class (int c, const char *class)

724

{

725

if (strcmp (class, "alnum") == 0)

726

return isalnum (c);

727

if (strcmp (class, "alpha") == 0)

728

return isalpha (c);

729

if (strcmp (class, "cntrl") == 0)

730

return iscntrl (c);

731

…

732

return 0;

733

}

734

</pre></td></tr></table>

735

736

Now, with the <code>wctype</code> and <code>iswctype</code> you can avoid the

737

<code>if</code> cascades, but rewriting the code as follows is wrong:

738

739

<table><tr><td> </td><td><pre class="smallexample">int

740

is_in_class (int c, const char *class)

741

{

742

wctype_t desc = wctype (class);

743

return desc ? iswctype ((wint_t) c, desc) : 0;

744

}

745

</pre></td></tr></table>

746

747

The problem is that it is not guaranteed that the wide character

748

representation of a single-byte character can be found using casting.

749

In fact, usually this fails miserably. The correct solution to this

750

problem is to write the code as follows:

751

752

<table><tr><td> </td><td><pre class="smallexample">int

753

is_in_class (int c, const char *class)

754

{

755

wctype_t desc = wctype (class);

756

return desc ? iswctype (btowc (c), desc) : 0;

757

}

758

</pre></td></tr></table>

759

760

See section <a href="libc_6.html#Converting-a-Character">Converting Single Characters</a>, for more information on <code>btowc</code>.

761

Note that this change probably does not improve the performance

762

of the program a lot since the <code>wctype</code> function still has to make

763

the string comparisons. It gets really interesting if the

764

<code>is_in_class</code> function is called more than once for the

765

same class name. In this case the variable <var>desc</var> could be computed

766

once and reused for all the calls. Therefore the above form of the

767

function is probably not the final one.

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

785

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

786

787

</tr></table>

788

789

<h2 class="section">4.5 Mapping of wide characters.</h2>

790

791

The classification functions are also generalized by the ISO C

792

standard. Instead of just allowing the two standard mappings, a

793

locale can contain others. Again, the <code>localedef</code> program

794

already supports generating such locale data files.

795

796

<dl>

797

<dt><a name="index-wctrans_005ft"></a>Data Type: wctrans_t</dt>

798

<dd>This data type is defined as a scalar type which can hold a value

799

representing the locale-dependent character mapping. There is no way to

800

construct such a value apart from using the return value of the

801

<code>wctrans</code> function.

802

803

804

This type is defined in ‘<tt>wctype.h</tt>’.

805

</dd></dl>

806

807

<dl>

808

<dt><a name="index-wctrans"></a>Function: wctrans_t wctrans (const char *<var>property</var>)</dt>

809

<dd>The <code>wctrans</code> function has to be used to find out whether a named

810

mapping is defined in the current locale selected for the

811

<code>LC_CTYPE</code> category. If the returned value is non-zero, you can use

812

it afterwards in calls to <code>towctrans</code>. If the return value is

813

zero no such mapping is known in the current locale.

814

815

Beside locale-specific mappings there are two mappings which are

816

guaranteed to be available in every locale:

817

818

<table>

819

<tr><td width="50%"><code>"tolower"</code></td><td width="50%"><code>"toupper"</code></td></tr>

820

</table>

821

822

823

These functions are declared in ‘<tt>wctype.h</tt>’.

824

</dd></dl>

825

826

<dl>

827

<dt><a name="index-towctrans"></a>Function: wint_t towctrans (wint_t <var>wc</var>, wctrans_t <var>desc</var>)</dt>

828

<dd><code>towctrans</code> maps the input character <var>wc</var>

829

according to the rules of the mapping for which <var>desc</var> is a

830

descriptor, and returns the value it finds. <var>desc</var> must be

831

obtained by a successful call to <code>wctrans</code>.

832

833

834

This function is declared in ‘<tt>wctype.h</tt>’.

835

</dd></dl>

836

837

For the generally available mappings, the ISO C standard defines

838

convenient shortcuts so that it is not necessary to call <code>wctrans</code>

839

for them.

840

841

<dl>

842

<dt><a name="index-towlower"></a>Function: wint_t towlower (wint_t <var>wc</var>)</dt>

843

<dd>If <var>wc</var> is an upper-case letter, <code>towlower</code> returns the corresponding

844

lower-case letter. If <var>wc</var> is not an upper-case letter,

845

<var>wc</var> is returned unchanged.

846

847

<code>towlower</code> can be implemented using

848

849

<table><tr><td> </td><td><pre class="smallexample">towctrans (wc, wctrans ("tolower"))

850

</pre></td></tr></table>

851

852

853

This function is declared in ‘<tt>wctype.h</tt>’.

854

</dd></dl>

855

856

<dl>

857

<dt><a name="index-towupper"></a>Function: wint_t towupper (wint_t <var>wc</var>)</dt>

858

<dd>If <var>wc</var> is a lower-case letter, <code>towupper</code> returns the corresponding

859

upper-case letter. Otherwise <var>wc</var> is returned unchanged.

860

861

<code>towupper</code> can be implemented using

862

863

<table><tr><td> </td><td><pre class="smallexample">towctrans (wc, wctrans ("toupper"))

864

</pre></td></tr></table>

865

866

867

This function is declared in ‘<tt>wctype.h</tt>’.

868

</dd></dl>

869

870

The same warnings given in the last section for the use of the wide

871

character classification functions apply here. It is not possible to

872

simply cast a <code>char</code> type value to a <code>wint_t</code> and use it as an

873

argument to <code>towctrans</code> calls.

874

875

876

877

878

879

880

881

882

883

884

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

885

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

886

887

</tr></table>

888

889

890

This document was generated by root on May 20, 2010 using <a href="http://www.nongnu.org/texi2html/">texi2html 1.82</a>.

891

892

893

894

895

</body>

896

</html>

Older »