company logo

String :: compare - Compares this string data with data of another specified string.

Compares the calling string with cString and returns an integer less than, equal to, or greater than zero if the current string value is less than, equal to, or greater than cString. Depending on the parameter bCaseSensitive, the comparison is case sensitive (true is default); otherwise the search is case insensitive.

Comparison depends on the string coding type of the calling string. When encoding types between strings differ, a copy of cString is created and recoded to the encoding type of the current string before compare operation.

Comparing an empty string with an empty string returns equal (0). Comparing an empty string with any nonempty string returns lower (-1).

odaba::String  str("auto");

int32 x = str.compare("AuTo",false);  // x == 0 (case-insensitive)

int32 y = str.compare("Car",true);    // y > 0  (case-sensitive)

int32 z = str.compare("Car",false);   // z < 0  (case-insensitive)

Return value:  Compare result ( int32  )

The result of a comparison is an integer value with the following meaning:

  • 0: both operands have the same value
  • 1: the calling operand is greater than the passed operand
  • -1: the calling operand is smaller than the passed operand

Implementation overview

Implementation details

  1. Compare part of the string
    int32 String  :: compare ( int32 iPosition, int32 iCount, odaba::String &cString, bool bCaseSensitive )

    The function compares iCount units of the current string value at iPosition (in units) with the string value passed in cString. For iCount equal -1 all content after iPosition is included in comparison. If bCaseSensitive is true, the comparison is case sensitive; otherwise the comparison is case insensitive.

    The function provides a sort of shortcut for mid(iPosition,iCount).compare(cString).

    When iPosition is less than zero or iCount is less than -1, the function throws an exception.

    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    • iCount - Number of items

      The value contains the number of items to be processed or stored in a collection.
    • cString - Constant string object

      When iPosition exceeds the string length or when the string is empty, the the function returns -1 (lower).
    • bCaseSensitive - Case sensitive option

      The option indicates case sensitive data in text (true)
    2. to list
  2. Compare strings case sensitive
    int32 String  :: compare ( odaba::String &cString )

    The function compares the current string value with the string value passed in cString. Comparison is case insensitive.

    When the string is empty, the the function returns -1 (lower).
    • cString - Constant string object

      When iPosition exceeds the string length or when the string is empty, the the function returns -1 (lower).
    3. to list
  3. Compare two strings
    int32 String  :: compare ( odaba::String &cString, bool bCaseSensitive )

    The function compares the current string value with the string value passed in cString. When bCaseSensitive is true, the comparison is case sensitive; otherwise the comparison is case insensitive.

    When the string is empty, the the function returns -1 (lower).
    • cString - Constant string object

      When iPosition exceeds the string length or when the string is empty, the the function returns -1 (lower).
    • bCaseSensitive - Case sensitive option

      The option indicates case sensitive data in text (true)
    4. to list
  4. Compare part of the string case sensitive
    int32 String  :: compare ( int32 iPosition, int32 iCount, odaba::String &cString )

    The function compares iCount units of the current string value at iPosition (in units) with the string value passed in cString. Comparison is case insensitive.

    The function calls compare(iPosition,iCount,cString,true).
    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    • iCount - Number of items

      The value contains the number of items to be processed or stored in a collection.
    • cString - Constant string object

      When iPosition exceeds the string length or when the string is empty, the the function returns -1 (lower).
    5. to list
to top next upper table of contents Comment