---
name: "Utf"
section: "3tcl"
platform: "linux"
package: "tcl8.3-doc"
version: "8.3.5-13"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/Utf/3tcl"
---

# Utf(3tcl)

routines for manipulating UTF-8 strings.

```

```

## NAME

Tcl\_UniChar, Tcl\_UniCharToUtf, Tcl\_UtfToUniChar, Tcl\_UniCharToUtfDString, Tcl\_UtfToUniCharDString, Tcl\_UniCharLen, Tcl\_UniCharNcmp, Tcl\_UtfCharComplete, Tcl\_NumUtfChars, Tcl\_UtfFindFirst, Tcl\_UtfFindLast, Tcl\_UtfNext, Tcl\_UtfPrev, Tcl\_UniCharAtIndex, Tcl\_UtfAtIndex, Tcl\_UtfBackslash - routines for manipulating UTF-8 strings.

## SYNOPSIS

```
#include <tcl.h>

typedef ... Tcl_UniChar;

int
Tcl_UniCharToUtf(ch, buf)

int
Tcl_UtfToUniChar(src, chPtr)

char *
Tcl_UniCharToUtfDString(uniStr, numChars, dstPtr)

Tcl_UniChar *
Tcl_UtfToUniCharDString(src, len, dstPtr)

int
Tcl_UniCharLen(uniStr)

int
Tcl_UniCharNcmp(uniStr, uniStr, num)

int
Tcl_UtfNcmp(src, src, num)

int
Tcl_UtfNcasecmp(src, src, num)

int
Tcl_UtfCharComplete(src, len)

int
Tcl_NumUtfChars(src, len)

char *
Tcl_UtfFindFirst(src, ch)

char *
Tcl_UtfFindLast(src, ch)

char *
Tcl_UtfNext(src)

char *
Tcl_UtfPrev(src, start)

Tcl_UniChar
Tcl_UniCharAtIndex(src, index)

char *
Tcl_UtfAtIndex(src, index)

int
Tcl_UtfBackslash(src, readPtr, dst)
```

## ARGUMENTS

- char *\*buf* (out)

  Buffer in which the UTF-8 representation of the Tcl\_UniChar is stored.  At most TCL\_UTF\_MAX bytes are stored in the buffer.

- int *ch* (in)

  The Tcl\_UniChar to be converted or examined.

- Tcl\_UniChar *\*chPtr* (out)

  Filled with the Tcl\_UniChar represented by the head of the UTF-8 string.

- CONST char *\*src* (in)

  Pointer to a UTF-8 string.

- CONST Tcl\_UniChar *\*uniStr* (in)

  A NULL-terminated Unicode string.

- int *len* (in)

  The length of the UTF-8 string in bytes (not UTF-8 characters).  If negative, all bytes up to the first null byte are used.

- int *numChars* (in)

  The length of the Unicode string in characters.  Must be greater than or equal to 0.

- Tcl\_DString *\*dstPtr* (in/out)

  A pointer to a previously-initialized **Tcl\_DString**.

- unsigned long *num* (in)

  The number of characters to compare.

- CONST char *\*start* (in)

  Pointer to the beginning of a UTF-8 string.

- int *index* (in)

  The index of a character (not byte) in the UTF-8 string.

- int *\*readPtr* (out)

  If non-NULL, filled with the number of bytes in the backslash sequence,  including the backslash character.

- char *\*dst* (out)

  Buffer in which the bytes represented by the backslash sequence are stored. At most TCL\_UTF\_MAX bytes are stored in the buffer.

  ```

  ```

## DESCRIPTION

These routines convert between UTF-8 strings and Tcl\_UniChars.  A Tcl\_UniChar is a Unicode character represented as an unsigned, fixed-size quantity.  A UTF-8 character is a Unicode character represented as a varying-length sequence of up to TCL\_UTF\_MAX bytes.  A multibyte UTF-8 sequence consists of a lead byte followed by some number of trail bytes.

**TCL\_UTF\_MAX** is the maximum number of bytes that it takes to represent one Unicode character in the UTF-8 representation.

**Tcl\_UniCharToUtf** stores the Tcl\_UniChar *ch* as a UTF-8 string in starting at *buf*.  The return value is the number of bytes stored in *buf*.

**Tcl\_UtfToUniChar** reads one UTF-8 character starting at *src* and stores it as a Tcl\_UniChar in *\*chPtr*.  The return value is the number of bytes read from *src*..  The caller must ensure that the source buffer is long enough such that this routine does not run off the end and dereference non-existent or random memory; if the source buffer is known to be null terminated, this will not happen.  If the input is not in proper UTF-8 format, **Tcl\_UtfToUniChar** will store the first byte of *src* in *\*chPtr* as a Tcl\_UniChar between 0x0000 and 0x00ff and return 1.

**Tcl\_UniCharToUtfDString** converts the given Unicode string to UTF-8, storing the result in a previously-initialized **Tcl\_DString**. You must specify the length of the given Unicode string. The return value is a pointer to the UTF-8 representation of the Unicode string.  Storage for the return value is appended to the end of the **Tcl\_DString**.

**Tcl\_UtfToUniCharDString** coverts the given UTF-8 string to Unicode, storing the result in the previously-initialized **Tcl\_DString**. you may either specify the length of the given UTF-8 string or "-1", in which case **Tcl\_UtfToUniCharDString** uses **strlen** to calculate the length.  The return value is a pointer to the Unicode representation of the UTF-8 string.  Storage for the return value is appended to the end of the **Tcl\_DString**.  The Unicode string is terminated with a Unicode NULL character.

**Tcl\_UniCharLen** corresponds to **strlen** for Unicode characters.  It accepts a NULL-terminated Unicode string and returns the number of Unicode characters (not bytes) in that string.

**Tcl\_UniCharNcmp** corresponds to **strncmp** for Unicode characters.  It accepts two NULL-terminated Unicode strings and the number of characters to compare.  (Both strings are assumed to be at least *len* characters long.) **Tcl\_UniCharNcmp** compares the two strings character-by-character according to the Unicode character ordering.  It returns an integer greater than, equal to, or less than 0 if the first string is greater than, equal to, or less than the second string respectively.

**Tcl\_UtfNcmp** corresponds to **strncmp** for UTF-8 strings. It accepts two NULL-terminated UTF-8 strings and the number of characters to compare.  (Both strings are assumed to be at least *len* characters long.)  **Tcl\_UtfNcmp** compares the two strings character-by-character according to the Unicode character ordering. It returns an integer greater than, equal to, or less than 0 if the first string is greater than, equal to, or less than the second string respectively.

**Tcl\_UtfNcasecmp** corresponds to **strncasecmp** for UTF-8 strings.  It is similar to **Tcl\_UtfNcmp** except comparisons ignore differences in case when comparing upper, lower or title case characters.

**Tcl\_UtfCharComplete** returns 1 if the source UTF-8 string *src* of length *len* bytes is long enough to be decoded by **Tcl\_UtfToUniChar**, or 0 otherwise.  This function does not guarantee that the UTF-8 string is properly formed.  This routine is used by procedures that are operating on a byte at a time and need to know if a full Tcl\_UniChar has been seen.

**Tcl\_NumUtfChars** corresponds to **strlen** for UTF-8 strings.  It returns the number of Tcl\_UniChars that are represented by the UTF-8 string *src*.  The length of the source string is *len* bytes.  If the length is negative, all bytes up to the first NULL byte are used.

**Tcl\_UtfFindFirst** corresponds to **strchr** for UTF-8 strings.  It returns a pointer to the first occurance of the Tcl\_UniChar *ch* in the NULL-terminated UTF-8 string *src*.  The NULL terminator is considered part of the UTF-8 string.

**Tcl\_UtfFindLast** corresponds to **strrchr** for UTF-8 strings.  It returns a pointer to the last occurance of the Tcl\_UniChar *ch* in the NULL terminated UTF-8 string *src*.  The NULL terminator is considered part of the UTF-8 string.

Given *src*, a pointer to some location in a UTF-8 string, **Tcl\_UtfNext** returns a pointer to the next UTF-8 character in the string.  The caller must not ask for the next character after the last character in the string.

Given *src*, a pointer to some location in a UTF-8 string, **Tcl\_UtfPrev** returns a pointer to the previous UTF-8 character in the string.  This function will not back up to a position before *start*, the start of the UTF-8 string.  If *src* was already at *start*, the return value will be *start*.

**Tcl\_UniCharAtIndex** corresponds to a C string array dereference or the Pascal Ord() function.  It returns the Tcl\_UniChar represented at the specified character (not byte) *index* in the UTF-8 string *src*.  The source string must contain at least *index* characters.  Behavior is undefined if a negative *index* is given.

**Tcl\_UtfAtIndex** returns a pointer to the specified character (not byte) *index* in the UTF-8 string *src*.  The source string must contain at least *index* characters.  This is equivalent to calling  **Tcl\_UtfNext** *index* times.  If a negative *index* is given, the return pointer points to the first character in the source string.

**Tcl\_UtfBackslash** is a utility procedure used by several of the Tcl commands.  It parses a backslash sequence and stores the properly formed UTF-8 character represented by the backslash sequence in the output buffer *dst*.  At most TCL\_UTF\_MAX bytes are stored in the buffer. **Tcl\_UtfBackslash** modifies *\*readPtr* to contain the number of bytes in the backslash sequence, including the backslash character. The return value is the number of bytes stored in the output buffer.

See the **Tcl** manual entry for information on the valid backslash sequences.  All of the sequences described in the Tcl manual entry are supported by **Tcl\_UtfBackslash**.

## KEYWORDS

utf, unicode, backslash