sdlStrncasecmp function

int sdlStrncasecmp(String? str1, String? str2, int maxlen)

Compare two UTF-8 strings, case-insensitively, up to a number of bytes.

This will work with Unicode strings, using a technique called "case-folding" to handle the vast majority of case-sensitive human languages regardless of system locale. It can deal with expanding values: a German Eszett character can compare against two ASCII 's' chars and be considered a match, for example. A notable exception: it does not handle the Turkish 'i' character; human language is complicated!

Since this handles Unicode, it expects the string to be well-formed UTF-8 and not a null-terminated string of arbitrary bytes. Bytes that are not valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT CHARACTER), which is to say two strings of random bits may turn out to match if they convert to the same amount of replacement characters.

Note that while this function is intended to be used with UTF-8, maxlen specifies a byte limit! If the limit lands in the middle of a multi-byte UTF-8 sequence, it may convert a portion of the final character to one or more Unicode character U+FFFD (REPLACEMENT CHARACTER) so as not to overflow a buffer.

maxlen specifies a maximum number of bytes to compare; if the strings match to this number of bytes (or both have matched to a null-terminator character before this number of bytes), they will be considered equal.

\param str1 the first string to compare. NULL is not permitted! \param str2 the second string to compare. NULL is not permitted! \param maxlen the maximum number of bytes to compare. \returns less than zero if str1 is "less than" str2, greater than zero if str1 is "greater than" str2, and zero if the strings match exactly.

\threadsafety It is safe to call this function from any thread.

\since This function is available since SDL 3.1.3.

extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen)

Implementation

int sdlStrncasecmp(String? str1, String? str2, int maxlen) {
  final sdlStrncasecmpLookupFunction = libSdl3.lookupFunction<
      Int32 Function(Pointer<Utf8> str1, Pointer<Utf8> str2, Uint32 maxlen),
      int Function(Pointer<Utf8> str1, Pointer<Utf8> str2,
          int maxlen)>('SDL_strncasecmp');
  final str1Pointer = str1 != null ? str1.toNativeUtf8() : nullptr;
  final str2Pointer = str2 != null ? str2.toNativeUtf8() : nullptr;
  final result = sdlStrncasecmpLookupFunction(str1Pointer, str2Pointer, maxlen);
  calloc.free(str1Pointer);
  calloc.free(str2Pointer);
  return result;
}