enum sz_ordering_tValues
sz_less_k | -1 | |
|---|---|---|
sz_equal_k | 0 | |
sz_greater_k | 1 |
See also
std::strong_ordering: https://en.cppreference.com/w/cpp/utility/compare/strong_ordering
Includes core APIs:
sz_equal_best- for equality comparison of two strings.sz_order_best- for the relative order of two strings, similar tomemcmp.
A valid suggestion may be to add an sz_mismatch, as the shared part of sz_order_best and sz_equal_best. That would be great for a general-purpose library, but string processing has little practical use for it.
The functions in this file can be used for both UTF-8 and other inputs. On platforms without masked loads they use interleaved prefix and suffix vector-loads to avoid scalar code, similar to the kernels in memory.h.
API
Types
sz_ordering_tDescribes the result of a comparison, like std::strong_ordering in C++20.
sz_kernel_equal_tSignature of the sz_equal_best kernels.
typedef sz_status_t(*) sz_kernel_equal_t(sz_cptr_t, sz_cptr_t, sz_size_t, sz_bool_t *, sz_stream_t);sz_kernel_order_tSignature of the sz_order_best kernels.
typedef sz_status_t(*) sz_kernel_order_t(sz_cptr_t, sz_size_t, sz_cptr_t, sz_size_t, sz_ordering_t *, sz_stream_t);Functions
sz_equal_bestChecks if two strings are equal, like memcmp(a, b, length) == 0, or a == b in STL.
sz_status_t sz_equal_best(
sz_cptr_t a,
sz_cptr_t b,
sz_size_t length,
sz_bool_t *equal,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_equalserialwestmerehaswellskylakeneonsvervvv128v128relaxedloongsonasxpowervsx
Telling an equal pair from a different one:
#include <stringzilla/compare.h>
int main() {
sz_capability_t capabilities;
sz_bool_t same, different;
sz_capabilities_enabled_cpu(&capabilities);
sz_equal_best("hello", "hello", 5, &same, capabilities, NULL);
sz_equal_best("hello", "world", 5, &different, capabilities, NULL);
return same && !different;
}Parameters
a | in | First string to compare. |
|---|---|---|
b | in | Second string to compare. |
length | in | Number of bytes to compare in both strings. |
equal | out | sz_true_k if the strings are equal, sz_false_k if they differ. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
- memcmp: https://en.cppreference.com/w/c/string/byte/memcmp
- sz_equal_serial, sz_equal_westmere, sz_equal_haswell, sz_equal_skylake, sz_equal_neon, sz_equal_sve, sz_equal_v128, sz_equal_v128relaxed, sz_equal_rvv, sz_equal_loongsonasx, sz_equal_powervsx
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_order_bestCompares two strings lexicographically, like memcmp in LibC.
sz_status_t sz_order_best(
sz_cptr_t a,
sz_size_t a_length,
sz_cptr_t b,
sz_size_t b_length,
sz_ordering_t *ordering,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_orderserialwestmerehaswellskylakeneonsvervvv128v128relaxedloongsonasxpowervsx
Mostly used in sorting and associative containers, and can be used for UTF-8 inputs. This function uses scalar code on most platforms, as in the majority of cases the strings that differ will have differences among the very first characters and fetching more than one cache line may not be justified.
Ordering three pairs of words:
#include <stringzilla/compare.h>
int main() {
sz_capability_t capabilities;
sz_ordering_t first, second, third;
sz_capabilities_enabled_cpu(&capabilities);
sz_order_best("apple", 5, "banana", 6, &first, capabilities, NULL);
sz_order_best("grape", 5, "grape", 5, &second, capabilities, NULL);
sz_order_best("zebra", 5, "apple", 5, &third, capabilities, NULL);
return first < 0 && second == 0 && third > 0;
}Parameters
a | in | First string to compare. |
|---|---|---|
a_length | in | Number of bytes in the first string. |
b | in | Second string to compare. |
b_length | in | Number of bytes in the second string. |
ordering | out | sz_less_k if a sorts before b, sz_greater_k if after, or sz_equal_k if the strings are identical. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
- memcmp: https://en.cppreference.com/w/c/string/byte/memcmp
- sz_order_serial, sz_order_westmere, sz_order_haswell, sz_order_skylake, sz_order_neon, sz_order_sve, sz_order_v128, sz_order_v128relaxed, sz_order_rvv, sz_order_loongsonasx, sz_order_powervsx
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_compare_find_kernelFinds the comparison kernel of kind, from the best of capabilities.
sz_status_t sz_compare_find_kernel(
sz_kernel_kind_t kind,
sz_capability_t capabilities,
sz_kernel_punned_t *kernel,
sz_capability_t *capability);Parameters
kind | in | The verb whose kernel to find. |
|---|---|---|
capabilities | in | The mask to pick the best capability from. |
kernel | out | The kernel, or null when none of capabilities has it. |
capability | out | The capability the kernel belongs to, or zero. |
Statuses
sz_missing_kernel_ksz_missing_library_kHeader-only.