---
name: "Utf"
section: "3"
platform: "macos"
package: "tcl"
version: "152"
release: "macOS 26.5"
platforms: ["macos"]
url: "https://new.carta.tech/Utf"
---

# Utf(3)

routines for manipulating UTF-8 strings

## NAME

Tcl\_UniChar, Tcl\_UniCharCaseMatch, Tcl\_UniCharNcasecmp, 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, uniLength, dsPtr)

Tcl_UniChar *
Tcl_UtfToUniCharDString(src, length, dsPtr)

int
Tcl_UniCharLen(uniStr)

int
Tcl_UniCharNcmp(ucs, uct, numChars)

int
Tcl_UniCharNcasecmp(ucs, uct, numChars)

int
Tcl_UniCharCaseMatch(uniStr, uniPattern, nocase)

int
Tcl_UtfNcmp(cs, ct, numChars)

int
Tcl_UtfNcasecmp(cs, ct, numChars)

int
Tcl_UtfCharComplete(src, length)

int
Tcl_NumUtfChars(src, length)

const char *
Tcl_UtfFindFirst(src, ch)

const char *
Tcl_UtfFindLast(src, ch)

const char *
Tcl_UtfNext(src)

const char *
Tcl_UtfPrev(src, start)

Tcl_UniChar
Tcl_UniCharAtIndex(src, index)

const char *
Tcl_UtfAtIndex(src, index)

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

## ARGUMENTS

Buffer in which the UTF-8 representation of the Tcl\_UniChar is stored.  At most **TCL\_UTF\_MAX** bytes are stored in the buffer. The Tcl\_UniChar to be converted or examined. Filled with the Tcl\_UniChar represented by the head of the UTF-8 string. Pointer to a UTF-8 string. Pointer to a UTF-8 string. Pointer to a UTF-8 string. A null-terminated Unicode string. A null-terminated Unicode string. A null-terminated Unicode string. A null-terminated Unicode string. 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. The length of the Unicode string in characters.  Must be greater than or equal to 0. A pointer to a previously initialized **Tcl\_DString**. The number of characters to compare. Pointer to the beginning of a UTF-8 string. The index of a character (not byte) in the UTF-8 string. If non-NULL, filled with the number of bytes in the backslash sequence,  including the backslash character. Buffer in which the bytes represented by the backslash sequence are stored. At most **TCL\_UTF\_MAX** bytes are stored in the buffer. Specifies whether the match should be done case-sensitive (0) or case-insensitive (1).

## 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 *uniLength*, 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** converts the given UTF-8 string to Unicode, storing the result in the previously initialized **Tcl\_DString**. In the argument *length*, you may either specify the length of the given UTF-8 string in bytes or 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** and **Tcl\_UniCharNcasecmp** correspond to **strncmp** and **strncasecmp**, respectively, for Unicode characters. They accept two null-terminated Unicode strings and the number of characters to compare.  Both strings are assumed to be at least *numChars* 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\_UniCharNcasecmp** is the Unicode case insensitive version.

**Tcl\_UniCharCaseMatch** is the Unicode equivalent to **Tcl\_StringCaseMatch**.  It accepts a null-terminated Unicode string, a Unicode pattern, and a boolean value specifying whether the match should be case sensitive and returns whether the string matches the pattern.

**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 *numChars* 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* 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 *length* 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 occurrence 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 occurrence 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 if the string is not terminated by a null character.

Given *src*, a pointer to some location in a UTF-8 string (or to a null byte immediately following such a string), **Tcl\_UtfPrev** returns a pointer to the closest preceding byte that starts a UTF-8 character. 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