---
name: "SDL_StepUTF8"
section: "3"
platform: "linux"
package: "libsdl3-doc"
version: "3.2.10+ds-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/SDL_StepUTF8"
---

# SDL\_StepUTF8(3)

Decode a UTF-8 string, one Unicode codepoint at a time.

## NAME

SDL\_StepUTF8 - Decode a UTF-8 string, one Unicode codepoint at a time.

## HEADER FILE

Defined in SDL3/SDL\_stdinc.h

## SYNOPSIS

```
#include "SDL3/SDL.h"
```

**Uint32 SDL\_StepUTF8(const char \*\*pstr, size\_t \*pslen);**

## DESCRIPTION

This will return the first Unicode codepoint in the UTF-8 encoded string in *pstr* , and then advance pstr past any consumed bytes before returning.

It will not access more than *pslen* bytes from the string. pslen will be adjusted, as well, subtracting the number of bytes consumed. **pslen** is allowed to be NULL, in which case the string \_must\_ be NULL-terminated, as the function will blindly read until it sees the NULL char.

if *pslen* is zero, it assumes the end of string is reached and returns a zero codepoint regardless of the contents of the string buffer.

If the resulting codepoint is zero (a NULL terminator), or pslen is zero, it will not advance *pstr* or pslen at all.

Generally this function is called in a loop until it returns zero, adjusting its parameters each iteration.

If an invalid UTF-8 sequence is encountered, this function returns

**SDL\_INVALID\_UNICODE\_CODEPOINT**\
  and advances the string/length by one byte (which is to say, a multibyte sequence might produce several

**SDL\_INVALID\_UNICODE\_CODEPOINT**\
  returns before it syncs to the next valid UTF-8 sequence).

Several things can generate invalid UTF-8 sequences, including overlong encodings, the use of UTF-16 surrogate values, and truncated data. Please refer to

RFC3629 ⟨URL: https://www.ietf.org/rfc/rfc3629.txt ⟩

for details.

## FUNCTION PARAMETERS

- *pstr*

  a pointer to a UTF-8 string pointer to be read and adjusted.

- *pslen*

  a pointer to the number of bytes in the string, to be read and adjusted. NULL is allowed.

## RETURN VALUE

( **Uint32** ) Returns the first Unicode codepoint in the string.

## THREAD SAFETY

It is safe to call this function from any thread.

## AVAILABILITY

This function is available since SDL 3.2.0.