Function: compare-strings

compare-strings is a function defined in fns.c.

Signature

(compare-strings STR1 START1 END1 STR2 START2 END2 &optional IGNORE-CASE)

Documentation

Compare the contents of two strings, converting to multibyte if needed.

The arguments START1, END1, START2, and END2, if non-nil, are positions specifying which parts of STR1 or STR2 to compare. In string STR1, compare the part between START1 (inclusive) and END1
(exclusive). If START1 is nil, it defaults to 0, the beginning of
the string; if END1 is nil, it defaults to the length of the string. Likewise, in string STR2, compare the part between START2 and END2. Like in substring, negative values are counted from the end.

The strings are compared by the numeric values of their characters. For instance, STR1 is "less than" STR2 if its first differing character has a smaller numeric value. If IGNORE-CASE is non-nil, characters are converted to upper-case before comparing them. Unibyte strings are converted to multibyte for comparison.

The value is t if the strings (or specified portions) match. If string STR1 is less, the value is a negative number N;
  - 1 - N is the number of characters that match at the beginning.
If string STR1 is greater, the value is a positive number N;
  N - 1 is the number of characters that match at the beginning.

Probably introduced at or before Emacs version 20.3.

Source Code

// Defined in /usr/src/emacs/src/fns.c
{
  ptrdiff_t from1, to1, from2, to2, i1, i1_byte, i2, i2_byte;

  CHECK_STRING (str1);
  CHECK_STRING (str2);

  /* For backward compatibility, silently bring too-large positive end
     values into range.  */
  if (FIXNUMP (end1) && SCHARS (str1) < XFIXNUM (end1))
    end1 = make_fixnum (SCHARS (str1));
  if (FIXNUMP (end2) && SCHARS (str2) < XFIXNUM (end2))
    end2 = make_fixnum (SCHARS (str2));

  validate_subarray (str1, start1, end1, SCHARS (str1), &from1, &to1);
  validate_subarray (str2, start2, end2, SCHARS (str2), &from2, &to2);

  i1 = from1;
  i2 = from2;

  i1_byte = string_char_to_byte (str1, i1);
  i2_byte = string_char_to_byte (str2, i2);

  while (i1 < to1 && i2 < to2)
    {
      /* When we find a mismatch, we must compare the
	 characters, not just the bytes.  */
      int c1 = fetch_string_char_as_multibyte_advance (str1, &i1, &i1_byte);
      int c2 = fetch_string_char_as_multibyte_advance (str2, &i2, &i2_byte);

      if (c1 == c2)
	continue;

      if (! NILP (ignore_case))
	{
	  c1 = XFIXNUM (Fupcase (make_fixnum (c1)));
	  c2 = XFIXNUM (Fupcase (make_fixnum (c2)));
	}

      if (c1 == c2)
	continue;

      /* Note that I1 has already been incremented
	 past the character that we are comparing;
	 hence we don't add or subtract 1 here.  */
      if (c1 < c2)
	return make_fixnum (- i1 + from1);
      else
	return make_fixnum (i1 - from1);
    }

  if (i1 < to1)
    return make_fixnum (i1 - from1 + 1);
  if (i2 < to2)
    return make_fixnum (- i1 + from1 - 1);

  return Qt;
}