eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-05-25 05:59:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Sync SDL3 wiki -> header

Browse source
This commit is contained in:
SDL Wiki Bot 2024-06-27 21:37:27 +00:00
parent 1e0ac5771a
commit b7ab5182d3
1 changed files with 21 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

44
include/SDL3/SDL_stdinc.h
View file

@ -1267,42 +1267,40 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *st
/** /**
* Decode a UTF-8 string, one Unicode codepoint at a time. * Decode a UTF-8 string, one Unicode codepoint at a time.
* *
* This will return the first Unicode codepoint in the UTF-8 encoded * This will return the first Unicode codepoint in the UTF-8 encoded string in
* string in `*pstr`, and then advance `*pstr` past any consumed bytes * `*pstr`, and then advance `*pstr` past any consumed bytes before returning.
* before returning.
* *
* It will not access more than `*pslen` bytes from the string. * It will not access more than `*pslen` bytes from the string. `*pslen` will
* `*pslen` will be adjusted, as well, subtracting the number of * be adjusted, as well, subtracting the number of bytes consumed.
* bytes consumed.
* *
* `pslen` is allowed to be NULL, in which case the string _must_ be * `pslen` is allowed to be NULL, in which case the string _must_ be
* NULL-terminated, as the function will blindly read until it sees * NULL-terminated, as the function will blindly read until it sees the NULL
* the NULL char. * char.
* *
* if `*pslen` is zero, it assumes the end of string is reached and * if `*pslen` is zero, it assumes the end of string is reached and returns a
* returns a zero codepoint regardless of the contents of the string * zero codepoint regardless of the contents of the string buffer.
* buffer.
* *
* If the resulting codepoint is zero (a NULL terminator), or `*pslen` * If the resulting codepoint is zero (a NULL terminator), or `*pslen` is
* is zero, it will not advance `*pstr` or `*pslen` at all. * zero, it will not advance `*pstr` or `*pslen` at all.
* *
* Generally this function is called in a loop until it returns zero, * Generally this function is called in a loop until it returns zero,
* adjusting its parameters each iteration. * adjusting its parameters each iteration.
* *
* If an invalid UTF-8 sequence is encountered, this function returns * If an invalid UTF-8 sequence is encountered, this function returns
* SDL_INVALID_UNICODE_CODEPOINT and advances the string/length by one * SDL_INVALID_UNICODE_CODEPOINT and advances the string/length by one byte
* byte (which is to say, a multibyte sequence might produce several * (which is to say, a multibyte sequence might produce several
* SDL_INVALID_UNICODE_CODEPOINT returns before it syncs to the next * SDL_INVALID_UNICODE_CODEPOINT returns before it syncs to the next valid
* valid UTF-8 sequence). * UTF-8 sequence).
* *
* Several things can generate invalid UTF-8 sequences, including * Several things can generate invalid UTF-8 sequences, including overlong
* overlong encodings, the use of UTF-16 surrogate values, and * encodings, the use of UTF-16 surrogate values, and truncated data. Please
* truncated data. Please refer to * refer to
* [RFC3629](https://www.ietf.org/rfc/rfc3629.txt) for details. * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt)
* for details.
* *
* \param pstr a pointer to a UTF-8 string pointer to be read and adjusted. * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted.
* \param pslen a pointer to the number of bytes in the string, to be read * \param pslen a pointer to the number of bytes in the string, to be read and
* and adjusted. NULL is allowed. * adjusted. NULL is allowed.
* \returns the first Unicode codepoint in the string. * \returns the first Unicode codepoint in the string.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.