mirror of
https://github.com/libsdl-org/SDL.git
synced 2025-05-24 21:49:10 +00:00
Sync SDL3 wiki -> header
This commit is contained in:
parent
1e0ac5771a
commit
b7ab5182d3
1 changed files with 21 additions and 23 deletions
|
@ -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.
|
||||
*
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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 `*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.
|
||||
* 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).
|
||||
* 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](https://www.ietf.org/rfc/rfc3629.txt) for details.
|
||||
* 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](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 pslen a pointer to the number of bytes in the string, to be read
|
||||
* and adjusted. NULL is allowed.
|
||||
* \param pslen a pointer to the number of bytes in the string, to be read and
|
||||
* adjusted. NULL is allowed.
|
||||
* \returns the first Unicode codepoint in the string.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue