Repository: libsdl-org/SDL
File: include/SDL3/SDL_stdinc.h (C/C++)

Code before:
#define SDL_ICONV_ERROR     (size_t)-1
#define SDL_ICONV_E2BIG     (size_t)-2
#define SDL_ICONV_EILSEQ    (size_t)-3
#define SDL_ICONV_EINVAL    (size_t)-4

typedef struct SDL_iconv_data_t *SDL_iconv_t;

/**
 * This function allocates a descriptor for the specified character set conversion.
 *
 * \param tocode The target character encoding, must not be NULL.
 * \param fromcode The source character encoding, must not be NULL.
 * \returns a handle that must be freed with SDL_iconv_close,
 *          or SDL_ICONV_ERROR on failure.
 *
 * \since This function is available since SDL 3.0.0.
 *
 * \sa SDL_iconv
 * \sa SDL_iconv_close
 * \sa SDL_iconv_string
 */
extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode,
                                                   const char *fromcode);

/**
 * This function frees a descriptor used for character set conversion.
 *
 * \param cd The character set conversion handle.
 * \returns 0 on success, or -1 on failure.
 *
 * \since This function is available since SDL 3.0.0.
 *
 * \sa SDL_iconv
 * \sa SDL_iconv_open
 * \sa SDL_iconv_string
 */
extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd);

/**
 * This function converts text between encodings, reading from and writing to a buffer.
 * It returns the number of succesful conversions.
 *
 * \param cd The character set conversion handle.
 * \param inbuf Address of variable that points to the first character of the input sequence.
 * \param inbytesleft The number of bytes in the input buffer.
 * \param outbuf Address of variable that points to the output buffer.
 * \param outbytesleft The number of bytes in the output buffer.
 * \returns the number of conversions on success, else
 *      SDL_ICONV_E2BIG is returned when the output buffer is too small, or
 *      SDL_ICONV_EILSEQ is returned when an invalid input sequence is encountered, or
 *      SDL_ICONV_EINVAL is returned when an incomplete input sequence is encountered.

Review comment (suggestion):
```suggestion
 * This function frees a context used for character set conversion.
```

Code after:
#define SDL_ICONV_ERROR     (size_t)-1
#define SDL_ICONV_E2BIG     (size_t)-2
#define SDL_ICONV_EILSEQ    (size_t)-3
#define SDL_ICONV_EINVAL    (size_t)-4

typedef struct SDL_iconv_data_t *SDL_iconv_t;

/**
 * This function allocates a context for the specified character set conversion.
 *
 * \param tocode The target character encoding, must not be NULL.
 * \param fromcode The source character encoding, must not be NULL.
 * \returns a handle that must be freed with SDL_iconv_close,
 *          or SDL_ICONV_ERROR on failure.
 *
 * \since This function is available since SDL 3.0.0.
 *
 * \sa SDL_iconv
 * \sa SDL_iconv_close
 * \sa SDL_iconv_string
 */
extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode,
                                                   const char *fromcode);

/**
 * This function frees a context used for character set conversion.
 *
 * \param cd The character set conversion handle.
 * \returns 0 on success, or -1 on failure.
 *
 * \since This function is available since SDL 3.0.0.
 *
 * \sa SDL_iconv
 * \sa SDL_iconv_open
 * \sa SDL_iconv_string
 */
extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd);

/**
 * This function converts text between encodings, reading from and writing to a buffer.
 * It returns the number of succesful conversions.
 *
 * \param cd The character set conversion context, created in SDL_iconv_open().
 * \param inbuf Address of variable that points to the first character of the input sequence.
 * \param inbytesleft The number of bytes in the input buffer.
 * \param outbuf Address of variable that points to the output buffer.
 * \param outbytesleft The number of bytes in the output buffer.
 * \returns the number of conversions on success, else
 *      SDL_ICONV_E2BIG is returned when the output buffer is too small, or
 *      SDL_ICONV_EILSEQ is returned when an invalid input sequence is encountered, or
 *      SDL_ICONV_EINVAL is returned when an incomplete input sequence is encountered.