gh-124502: Add PyUnicode_Equal() function

[vstinner]

• Issue: [C API] Add PyUnicode_Equal() function #124502

---

📚 Documentation preview 📚: https://cpython-previews--124504.org.readthedocs.build/

[vstinner]

@picnixz @rruuaanng @ZeroIntensity: I addressed your comments. Please review the updated PR.

[picnixz]

Final nitpick but you can ignore it (I don't know whether it's that useful).

[ZeroIntensity]

Thank you! LGTM.

[rruuaanng]

Maybe you are right, But you can consider my suggestion.

[vstinner]

I created capi-workgroup/decisions#43 issue in the C API Working Group.

[vstinner]

I wrote a microbenchmark comparing equal strings of 10 characters:

• bench.patch
• bench.py

Results on Fedora 40 with CPU isolation:

• (private) _PyUnicode_EQ: Mean +- std dev: 9.71 ns +- 0.04 ns
• (private) _PyUnicode_Equal: Mean +- std dev: 8.75 ns +- 0.01 ns
• (public) PyUnicode_Equal: Mean +- std dev: 9.14 ns +- 0.02 ns
• (public) PyUnicode_Compare: Mean +- std dev: 11.1 ns +- 0.1 ns
• (public) PyUnicode_RichCompare: Mean +- std dev: 12.2 ns +- 0.0 ns

Proposed public PyUnicode_Equal() is 1.2x faster than PyUnicode_Compare() (-2.0 ns) and 1.3x faster than PyUnicode_RichCompare() (-3.1 ns).

Private _PyUnicode_EQ() and private _PyUnicode_Equal() are not exactly the same implementation, it seems like private _PyUnicode_Equal() is a little bit faster (1 ns!).

[vstinner]

Microbenchmark on comparison of inequal strings of 10 characters, only the last character is different.

• (private) _PyUnicode_EQ: Mean +- std dev: 10.0 ns +- 0.0 ns
• (private) _PyUnicode_Equal: Mean +- std dev: 9.18 ns +- 0.00 ns
• (public) PyUnicode_Equal: Mean +- std dev: 10.1 ns +- 0.0 ns
• (public) PyUnicode_Compare: Mean +- std dev: 10.9 ns +- 0.0 ns
• (public) PyUnicode_RichCompare: Mean +- std dev: 13.1 ns +- 0.0 ns

[vstinner]

I created capi-workgroup/decisions#43 issue in the C API Working Group.

The C API Working Group approved the API.

[vstinner]

Merged. Thanks for reviews @picnixz and @ZeroIntensity.