linux: Extend internal clone3 documentation
[glibc.git] / string / str-two-way.h
blob901e779d787f66d5083ef0b83e9e2dff1adf0aa8
1 /* Byte-wise substring search, using the Two-Way algorithm.
2 Copyright (C) 2008-2023 Free Software Foundation, Inc.
3 This file is part of the GNU C Library.
4 Written by Eric Blake <ebb9@byu.net>, 2008.
6 The GNU C Library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2.1 of the License, or (at your option) any later version.
11 The GNU C Library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
16 You should have received a copy of the GNU Lesser General Public
17 License along with the GNU C Library; if not, see
18 <https://www.gnu.org/licenses/>. */
20 /* Before including this file, you need to include <string.h> (and
21 <config.h> before that, if not part of libc), and define:
22 RETURN_TYPE A macro that expands to the return type.
23 AVAILABLE(h, h_l, j, n_l)
24 A macro that returns nonzero if there are
25 at least N_L bytes left starting at H[J].
26 H is 'unsigned char *', H_L, J, and N_L
27 are 'size_t'; H_L is an lvalue. For
28 NUL-terminated searches, H_L can be
29 modified each iteration to avoid having
30 to compute the end of H up front.
32 For case-insensitivity, you may optionally define:
33 CMP_FUNC(p1, p2, l) A macro that returns 0 iff the first L
34 characters of P1 and P2 are equal.
35 CANON_ELEMENT(c) A macro that canonicalizes an element right after
36 it has been fetched from one of the two strings.
37 The argument is an 'unsigned char'; the result
38 must be an 'unsigned char' as well.
40 Other macros you may optionally define:
41 RET0_IF_0(a) Documented below at default definition.
42 CHECK_EOL Same.
44 This file undefines the macros listed above, and defines
45 LONG_NEEDLE_THRESHOLD.
48 #include <limits.h>
49 #include <stdint.h>
50 #include <sys/param.h> /* Defines MAX. */
52 /* We use the Two-Way string matching algorithm, which guarantees
53 linear complexity with constant space. Additionally, for long
54 needles, we also use a bad character shift table similar to the
55 Boyer-Moore algorithm to achieve improved (potentially sub-linear)
56 performance.
58 See http://www-igm.univ-mlv.fr/~lecroq/string/node26.html#SECTION00260
59 and http://en.wikipedia.org/wiki/Boyer-Moore_string_search_algorithm
62 /* Point at which computing a bad-byte shift table is likely to be
63 worthwhile. Small needles should not compute a table, since it
64 adds (1 << CHAR_BIT) + NEEDLE_LEN computations of preparation for a
65 speedup no greater than a factor of NEEDLE_LEN. The larger the
66 needle, the better the potential performance gain. On the other
67 hand, on non-POSIX systems with CHAR_BIT larger than eight, the
68 memory required for the table is prohibitive. */
69 #if CHAR_BIT < 10
70 # define LONG_NEEDLE_THRESHOLD 32U
71 #else
72 # define LONG_NEEDLE_THRESHOLD SIZE_MAX
73 #endif
75 #ifndef CANON_ELEMENT
76 # define CANON_ELEMENT(c) c
77 #endif
78 #ifndef CMP_FUNC
79 # define CMP_FUNC memcmp
80 #endif
82 /* Check for end-of-line in strstr and strcasestr routines.
83 We piggy-back matching procedure for detecting EOL where possible,
84 and use AVAILABLE macro otherwise. */
85 #ifndef CHECK_EOL
86 # define CHECK_EOL (0)
87 #endif
89 /* Return NULL if argument is '\0'. */
90 #ifndef RET0_IF_0
91 # define RET0_IF_0(a) /* nothing */
92 #endif
94 /* Perform a critical factorization of NEEDLE, of length NEEDLE_LEN.
95 Return the index of the first byte in the right half, and set
96 *PERIOD to the global period of the right half.
98 The global period of a string is the smallest index (possibly its
99 length) at which all remaining bytes in the string are repetitions
100 of the prefix (the last repetition may be a subset of the prefix).
102 When NEEDLE is factored into two halves, a local period is the
103 length of the smallest word that shares a suffix with the left half
104 and shares a prefix with the right half. All factorizations of a
105 non-empty NEEDLE have a local period of at least 1 and no greater
106 than NEEDLE_LEN.
108 A critical factorization has the property that the local period
109 equals the global period. All strings have at least one critical
110 factorization with the left half smaller than the global period.
112 Given an ordered alphabet, a critical factorization can be computed
113 in linear time, with 2 * NEEDLE_LEN comparisons, by computing the
114 larger of two ordered maximal suffixes. The ordered maximal
115 suffixes are determined by lexicographic comparison of
116 periodicity. */
117 static size_t
118 critical_factorization (const unsigned char *needle, size_t needle_len,
119 size_t *period)
121 /* Index of last byte of left half, or SIZE_MAX. */
122 size_t max_suffix, max_suffix_rev;
123 size_t j; /* Index into NEEDLE for current candidate suffix. */
124 size_t k; /* Offset into current period. */
125 size_t p; /* Intermediate period. */
126 unsigned char a, b; /* Current comparison bytes. */
128 /* Invariants:
129 0 <= j < NEEDLE_LEN - 1
130 -1 <= max_suffix{,_rev} < j (treating SIZE_MAX as if it were signed)
131 min(max_suffix, max_suffix_rev) < global period of NEEDLE
132 1 <= p <= global period of NEEDLE
133 p == global period of the substring NEEDLE[max_suffix{,_rev}+1...j]
134 1 <= k <= p
137 /* Perform lexicographic search. */
138 max_suffix = SIZE_MAX;
139 j = 0;
140 k = p = 1;
141 while (j + k < needle_len)
143 a = CANON_ELEMENT (needle[j + k]);
144 b = CANON_ELEMENT (needle[max_suffix + k]);
145 if (a < b)
147 /* Suffix is smaller, period is entire prefix so far. */
148 j += k;
149 k = 1;
150 p = j - max_suffix;
152 else if (a == b)
154 /* Advance through repetition of the current period. */
155 if (k != p)
156 ++k;
157 else
159 j += p;
160 k = 1;
163 else /* b < a */
165 /* Suffix is larger, start over from current location. */
166 max_suffix = j++;
167 k = p = 1;
170 *period = p;
172 /* Perform reverse lexicographic search. */
173 max_suffix_rev = SIZE_MAX;
174 j = 0;
175 k = p = 1;
176 while (j + k < needle_len)
178 a = CANON_ELEMENT (needle[j + k]);
179 b = CANON_ELEMENT (needle[max_suffix_rev + k]);
180 if (b < a)
182 /* Suffix is smaller, period is entire prefix so far. */
183 j += k;
184 k = 1;
185 p = j - max_suffix_rev;
187 else if (a == b)
189 /* Advance through repetition of the current period. */
190 if (k != p)
191 ++k;
192 else
194 j += p;
195 k = 1;
198 else /* a < b */
200 /* Suffix is larger, start over from current location. */
201 max_suffix_rev = j++;
202 k = p = 1;
206 /* Choose the longer suffix. Return the first byte of the right
207 half, rather than the last byte of the left half. */
208 if (max_suffix_rev + 1 < max_suffix + 1)
209 return max_suffix + 1;
210 *period = p;
211 return max_suffix_rev + 1;
214 /* Return the first location of non-empty NEEDLE within HAYSTACK, or
215 NULL. HAYSTACK_LEN is the minimum known length of HAYSTACK. This
216 method is optimized for NEEDLE_LEN < LONG_NEEDLE_THRESHOLD.
217 Performance is guaranteed to be linear, with an initialization cost
218 of 2 * NEEDLE_LEN comparisons.
220 If AVAILABLE does not modify HAYSTACK_LEN (as in memmem), then at
221 most 2 * HAYSTACK_LEN - NEEDLE_LEN comparisons occur in searching.
222 If AVAILABLE modifies HAYSTACK_LEN (as in strstr), then at most 3 *
223 HAYSTACK_LEN - NEEDLE_LEN comparisons occur in searching. */
224 static inline RETURN_TYPE
225 two_way_short_needle (const unsigned char *haystack, size_t haystack_len,
226 const unsigned char *needle, size_t needle_len)
228 size_t i; /* Index into current byte of NEEDLE. */
229 size_t j; /* Index into current window of HAYSTACK. */
230 size_t period; /* The period of the right half of needle. */
231 size_t suffix; /* The index of the right half of needle. */
233 /* Factor the needle into two halves, such that the left half is
234 smaller than the global period, and the right half is
235 periodic (with a period as large as NEEDLE_LEN - suffix). */
236 suffix = critical_factorization (needle, needle_len, &period);
238 /* Perform the search. Each iteration compares the right half
239 first. */
240 if (CMP_FUNC (needle, needle + period, suffix) == 0)
242 /* Entire needle is periodic; a mismatch can only advance by the
243 period, so use memory to avoid rescanning known occurrences
244 of the period. */
245 size_t memory = 0;
246 j = 0;
247 while (AVAILABLE (haystack, haystack_len, j, needle_len))
249 const unsigned char *pneedle;
250 const unsigned char *phaystack;
252 /* Scan for matches in right half. */
253 i = MAX (suffix, memory);
254 pneedle = &needle[i];
255 phaystack = &haystack[i + j];
256 while (i < needle_len && (CANON_ELEMENT (*pneedle++)
257 == CANON_ELEMENT (*phaystack++)))
258 ++i;
259 if (needle_len <= i)
261 /* Scan for matches in left half. */
262 i = suffix - 1;
263 pneedle = &needle[i];
264 phaystack = &haystack[i + j];
265 while (memory < i + 1 && (CANON_ELEMENT (*pneedle--)
266 == CANON_ELEMENT (*phaystack--)))
267 --i;
268 if (i + 1 < memory + 1)
269 return (RETURN_TYPE) (haystack + j);
270 /* No match, so remember how many repetitions of period
271 on the right half were scanned. */
272 j += period;
273 memory = needle_len - period;
275 else
277 j += i - suffix + 1;
278 memory = 0;
282 else
284 const unsigned char *phaystack;
285 /* The comparison always starts from needle[suffix], so cache it
286 and use an optimized first-character loop. */
287 unsigned char needle_suffix = CANON_ELEMENT (needle[suffix]);
289 /* The two halves of needle are distinct; no extra memory is
290 required, and any mismatch results in a maximal shift. */
291 period = MAX (suffix, needle_len - suffix) + 1;
292 j = 0;
293 while (AVAILABLE (haystack, haystack_len, j, needle_len))
295 unsigned char haystack_char;
296 const unsigned char *pneedle;
298 phaystack = &haystack[suffix + j];
300 #ifdef FASTSEARCH
301 if (*phaystack++ != needle_suffix)
303 phaystack = FASTSEARCH (phaystack, needle_suffix,
304 haystack_len - needle_len - j);
305 if (phaystack == NULL)
306 goto ret0;
307 j = phaystack - &haystack[suffix];
308 phaystack++;
310 #else
311 while (needle_suffix
312 != (haystack_char = CANON_ELEMENT (*phaystack++)))
314 RET0_IF_0 (haystack_char);
315 # if !CHECK_EOL
316 ++j;
317 if (!AVAILABLE (haystack, haystack_len, j, needle_len))
318 goto ret0;
319 # endif
322 # if CHECK_EOL
323 /* Calculate J if it wasn't kept up-to-date in the first-character
324 loop. */
325 j = phaystack - &haystack[suffix] - 1;
326 # endif
327 #endif
328 /* Scan for matches in right half. */
329 i = suffix + 1;
330 pneedle = &needle[i];
331 while (i < needle_len)
333 if (CANON_ELEMENT (*pneedle++)
334 != (haystack_char = CANON_ELEMENT (*phaystack++)))
336 RET0_IF_0 (haystack_char);
337 break;
339 ++i;
341 #if CHECK_EOL
342 /* Update minimal length of haystack. */
343 if (phaystack > haystack + haystack_len)
344 haystack_len = phaystack - haystack;
345 #endif
346 if (needle_len <= i)
348 /* Scan for matches in left half. */
349 i = suffix - 1;
350 pneedle = &needle[i];
351 phaystack = &haystack[i + j];
352 while (i != SIZE_MAX)
354 if (CANON_ELEMENT (*pneedle--)
355 != (haystack_char = CANON_ELEMENT (*phaystack--)))
357 RET0_IF_0 (haystack_char);
358 break;
360 --i;
362 if (i == SIZE_MAX)
363 return (RETURN_TYPE) (haystack + j);
364 j += period;
366 else
367 j += i - suffix + 1;
370 ret0: __attribute__ ((unused))
371 return NULL;
374 /* Return the first location of non-empty NEEDLE within HAYSTACK, or
375 NULL. HAYSTACK_LEN is the minimum known length of HAYSTACK. This
376 method is optimized for LONG_NEEDLE_THRESHOLD <= NEEDLE_LEN.
377 Performance is guaranteed to be linear, with an initialization cost
378 of 3 * NEEDLE_LEN + (1 << CHAR_BIT) operations.
380 If AVAILABLE does not modify HAYSTACK_LEN (as in memmem), then at
381 most 2 * HAYSTACK_LEN - NEEDLE_LEN comparisons occur in searching,
382 and sublinear performance O(HAYSTACK_LEN / NEEDLE_LEN) is possible.
383 If AVAILABLE modifies HAYSTACK_LEN (as in strstr), then at most 3 *
384 HAYSTACK_LEN - NEEDLE_LEN comparisons occur in searching, and
385 sublinear performance is not possible.
387 Since this function is large and complex, block inlining to avoid
388 slowing down the common case of small needles. */
389 __attribute__((noinline)) static RETURN_TYPE
390 two_way_long_needle (const unsigned char *haystack, size_t haystack_len,
391 const unsigned char *needle, size_t needle_len)
393 size_t i; /* Index into current byte of NEEDLE. */
394 size_t j; /* Index into current window of HAYSTACK. */
395 size_t period; /* The period of the right half of needle. */
396 size_t suffix; /* The index of the right half of needle. */
397 size_t shift_table[1U << CHAR_BIT]; /* See below. */
399 /* Factor the needle into two halves, such that the left half is
400 smaller than the global period, and the right half is
401 periodic (with a period as large as NEEDLE_LEN - suffix). */
402 suffix = critical_factorization (needle, needle_len, &period);
404 /* Populate shift_table. For each possible byte value c,
405 shift_table[c] is the distance from the last occurrence of c to
406 the end of NEEDLE, or NEEDLE_LEN if c is absent from the NEEDLE.
407 shift_table[NEEDLE[NEEDLE_LEN - 1]] contains the only 0. */
408 for (i = 0; i < 1U << CHAR_BIT; i++)
409 shift_table[i] = needle_len;
410 for (i = 0; i < needle_len; i++)
411 shift_table[CANON_ELEMENT (needle[i])] = needle_len - i - 1;
413 /* Perform the search. Each iteration compares the right half
414 first. */
415 if (CMP_FUNC (needle, needle + period, suffix) == 0)
417 /* Entire needle is periodic; a mismatch can only advance by the
418 period, so use memory to avoid rescanning known occurrences
419 of the period. */
420 size_t memory = 0;
421 size_t shift;
422 j = 0;
423 while (AVAILABLE (haystack, haystack_len, j, needle_len))
425 const unsigned char *pneedle;
426 const unsigned char *phaystack;
428 /* Check the last byte first; if it does not match, then
429 shift to the next possible match location. */
430 shift = shift_table[CANON_ELEMENT (haystack[j + needle_len - 1])];
431 if (0 < shift)
433 if (memory && shift < period)
435 /* Since needle is periodic, but the last period has
436 a byte out of place, there can be no match until
437 after the mismatch. */
438 shift = needle_len - period;
440 memory = 0;
441 j += shift;
442 continue;
444 /* Scan for matches in right half. The last byte has
445 already been matched, by virtue of the shift table. */
446 i = MAX (suffix, memory);
447 pneedle = &needle[i];
448 phaystack = &haystack[i + j];
449 while (i < needle_len - 1 && (CANON_ELEMENT (*pneedle++)
450 == CANON_ELEMENT (*phaystack++)))
451 ++i;
452 if (needle_len - 1 <= i)
454 /* Scan for matches in left half. */
455 i = suffix - 1;
456 pneedle = &needle[i];
457 phaystack = &haystack[i + j];
458 while (memory < i + 1 && (CANON_ELEMENT (*pneedle--)
459 == CANON_ELEMENT (*phaystack--)))
460 --i;
461 if (i + 1 < memory + 1)
462 return (RETURN_TYPE) (haystack + j);
463 /* No match, so remember how many repetitions of period
464 on the right half were scanned. */
465 j += period;
466 memory = needle_len - period;
468 else
470 j += i - suffix + 1;
471 memory = 0;
475 else
477 /* The two halves of needle are distinct; no extra memory is
478 required, and any mismatch results in a maximal shift. */
479 size_t shift;
480 period = MAX (suffix, needle_len - suffix) + 1;
481 j = 0;
482 while (AVAILABLE (haystack, haystack_len, j, needle_len))
484 const unsigned char *pneedle;
485 const unsigned char *phaystack;
487 /* Check the last byte first; if it does not match, then
488 shift to the next possible match location. */
489 shift = shift_table[CANON_ELEMENT (haystack[j + needle_len - 1])];
490 if (0 < shift)
492 j += shift;
493 continue;
495 /* Scan for matches in right half. The last byte has
496 already been matched, by virtue of the shift table. */
497 i = suffix;
498 pneedle = &needle[i];
499 phaystack = &haystack[i + j];
500 while (i < needle_len - 1 && (CANON_ELEMENT (*pneedle++)
501 == CANON_ELEMENT (*phaystack++)))
502 ++i;
503 if (needle_len - 1 <= i)
505 /* Scan for matches in left half. */
506 i = suffix - 1;
507 pneedle = &needle[i];
508 phaystack = &haystack[i + j];
509 while (i != SIZE_MAX && (CANON_ELEMENT (*pneedle--)
510 == CANON_ELEMENT (*phaystack--)))
511 --i;
512 if (i == SIZE_MAX)
513 return (RETURN_TYPE) (haystack + j);
514 j += period;
516 else
517 j += i - suffix + 1;
520 return NULL;
523 #undef AVAILABLE
524 #undef CANON_ELEMENT
525 #undef CMP_FUNC
526 #undef RET0_IF_0
527 #undef RETURN_TYPE
528 #undef CHECK_EOL